Upgrade ArcGIS Notebook Server (Linux containers)

Upgrading ArcGIS Notebook Server provides your organization with the latest features and improvements to the software, while preserving your users' existing notebooks. If you are upgrading your ArcGIS Enterprise deployment to 11.1, you must also upgrade ArcGIS Notebook Server.

The ArcGIS Notebook Server 11.1 setup package detects whether you have an existing installation of a previous version of ArcGIS Notebook Server on your machine. If you do, it can upgrade the software to 11.1.

During the upgrade process, you must reauthorize the ArcGIS Notebook Server software for 11.1 if you have upgraded from 10.8.1 or earlier.

You must also install new container images from Esri, providing your users with 11.1 notebook runtimes. The notebook runtimes from the previous version will remain in the site; users can still run notebooks using those runtimes. However, if your users want to use functionality that is new at 11.1, they must update the runtime of their notebooks. The notebook runtimes corresponding to 11.1 are at version 8.0 (ArcGIS Notebook Server Standard 8.0 and ArcGIS Notebook Server Advanced 8.0).

Note:

If any notebooks were using custom runtimes, you must rebuild and reregister the custom runtimes on the Windows notebook server and update the runtime settings for the associated notebook items.

Note:

Notebook runtimes will be deprecated following the ArcGIS Enterprise Life Cycle. Notebooks should not use deprecated runtimes and should be updated to a supported runtime.

Upgrading the ArcGIS Enterprise portal will also update the sample notebooks available in the site's gallery.

Multiple-machine ArcGIS Notebook Server sites are supported at 10.7.1 and later. If you have a single-machine site and want to expand your ArcGIS Notebook Server site to multiple machines after upgrading, follow the steps to join additional machines to the site after you have finished upgrading to 11.1.

The upgrade process for ArcGIS Notebook Server is an in-place upgrade, which does not require uninstalling and reinstalling software. The site will be down during the upgrade process, and users will be unable to access or run notebooks until the upgrade is complete.

Follow the steps below to upgrade ArcGIS Notebook Server to 11.1.

Prepare to upgrade

Before upgrading, carefully review the following information:

• You can access all of the necessary files in My Esri before upgrading, including the 11.1 container images.
• For ArcGIS Notebook Server to function correctly, its version must match the version of the portal with which it's federated.
• Upgrade Docker to version 20.10.13 or later.
• To upgrade your ArcGIS Enterprise deployment, do the following:
  1. Upgrade Portal for ArcGIS.
  2. Upgrade ArcGIS Web Adaptor (for Portal).
  3. Upgrade the ArcGIS Server site serving as the portal's hosting server.
  4. Upgrade ArcGIS Web Adaptor (for Server).
  5. Upgrade ArcGIS Data Store (upgrade primary first, then standby).
  6. Upgrade any other servers, including ArcGIS Notebook Server.
  7. Install ArcGIS Notebook Server Samples Data
• Do not uninstall your existing ArcGIS Notebook Server. The ArcGIS Notebook Server setup and command line installers are designed to detect and upgrade an existing installation of ArcGIS Notebook Server components.
• Do not unfederate your ArcGIS Notebook Server site from the portal or remove its designation as the portal's Notebook Server at any point during the upgrade process. This adversely impacts the existing notebooks hosted by the portal.
• You can upgrade ArcGIS Notebook Server by either using the Setup or Command line installer. Choose one of these methods to upgrade.
• Before upgrading, clear the caches of all web browsers used on the ArcGIS Notebook Server machine.
• The Windows service account for your ArcGIS Notebook Server site (its Run As account) must remain the same when upgrading.

Back up your deployment

Before you upgrade, it's recommended that you make backups of your deployment.

Legacy:

In 10.7, you must manually back up the site's configuration store and server directories.

Notebooks will be included in portal backups using the webgisdr utility.

You can use the exportSite operation in the ArcGIS Notebook Server Administrator Directory to back up a site's configuration store, as described below. In addition to this site configuration backup, consider making manual backups of your file system.

Perform the following steps to run the backup operation:

1. Open the ArcGIS Notebook Server Administrator Directory and sign in as a user with administrative privileges.

   The URL is typically https://notebookserver.domain.com:11443/arcgis/admin.

2. Browse to site > Export Site.
3. Enter the full path of the location on your machine to which you want to export the file.

   The site must have access to this directory.

4. Click Export.

   When the export operation is complete, the directory provides a link to the backup file location on the server.

5. Download the file, which will have an .agssite file extension, as promptly as possible.

Upgrade using the setup program

Note:

Use the setup file to upgrade ArcGIS Notebook Server to 11.1. After upgrading the setup, you must upgrade the ArcGIS Notebook Server site using the configuration wizard or the upgrade site utility.

If you have a multiple-machine site, follow steps 1 through 3 for one machine, and repeat those steps for each machine in the site.

ArcGIS Notebook Server is designed to detect and upgrade an existing installation of ArcGIS Notebook Server components.

1. To start the upgrade, run ./Setup from the location where ArcGIS Notebook Server was extracted and follow the prompts to complete the upgrade.

   The setup must be run as the user account that installed the existing ArcGIS Notebook Server. During installation, the setup program identifies the existing installation, and you are prompted to confirm the upgrade. Enter choice y to proceed with the installation.

   This will uninstall the previous version of ArcGIS Notebook Server and install the upgraded version of ArcGIS Notebook Server.

2. After the upgrade utility has completed, reauthorize the ArcGIS Notebook Server software for 11.1. Use the software authorization wizard to complete the authorization.
3. Open the configuration wizard using the URL listed at the end of upgrading your install and follow the on-screen instructions to upgrade the site.
4. For a multiple-machine site, follow steps 1 through 3 for each machine in the site.

Upgrade from the command line

To upgrade from the command line, complete the following steps:

1. To start the upgrade, run the ArcGIS Notebook Server setup command with the argument shown in the example below. Ensure that you use the same ArcGIS Notebook Server account used by your existing installation.

   This uninstalls the previous version of ArcGIS Notebook Server and installs the upgraded version of ArcGIS Notebook Server.

   setup.exe /qn USER_NAME=<ArcGIS Notebook Server account username> PASSWORD=<password> ACCEPTEULA=yes

2. Use the upgradesite utility and complete the upgrade by running the following command. By default, the upgradesite utility is found at C:\Program Files\ArcGIS\NotebookServer\tools\upgradesiteutility\upgradesite.bat.

   upgradesite.bat -s

   The utility displays progress reports and stop when the upgrade is complete. The utility has two parameters:

   • -s—When included in the command, this prompts the utility to run the upgrade. The upgrade won't run without -s. This is intended as a safeguard to ensure you only run the upgrade when you're ready.
   • -h—Displays the help for the tool. When the command is run without -s, the help also displays.

3. For a multiple-machine site, repeat steps 1 and 2 for each machine in the site, and continue to the steps in the next section.

Authorize silently

After the upgrade utility has completed, you must reauthorize the ArcGIS Notebook Server software for 11.1 if you have upgraded from 10.8.1 or earlier.

Run SoftwareAuthorization.exe with the following syntax to authorize ArcGIS Notebook Server silently. You must have all user information complete in the authorization or provisioning file before running the file.

If you have an authorization file and your machine is connected to the internet, run the following:

<System disk drive>\Program Files\ArcGIS\NotebookServer\framework\bin /S /Ver <version number> /LIF <full path and name of authorization file>

Authorize in a disconnected environment

You can authorize ArcGIS Notebook Server in a disconnected environment using a provisioning (.prvc) file. During the process, a file is generated for you to send to Esri to complete the process.

1. At the prompt, run the command provided below after the ArcGIS Notebook Server upgrade is complete:

   <System disk drive>\Program Files\Common Files\ArcGIS\bin\SoftwareAuthorization.exe /F <full path to the .prvc file> /O <full path to authorization file output>

2. When the output information file has been created, do one of the following:
   • Browse to the Esri customer service website at https://service.esri.com/drm. Follow the instructions on the screen to upload the authorization information file and download the .ecp authorization file.
   • Send the authorization information file by email to [e-mail]. Esri will send an .ecp authorization file back to you in an email.
3. When you have received the .ecp authorization file using either above method, run the authorizeSoftware script again to process it and complete the server authorization process:

   <System disk drive>\Program Files\Common Files\ArcGIS\bin\SoftwareAuthorization.exe /F <full path to the .ecp file>

Repeat this workflow for each machine running ArcGIS Notebook Server.

Steps after upgrading

Before your upgraded and reauthorized ArcGIS Notebook Server site can be used, you must run the post installation utility to add your new Docker container images to the site. You must also replace the ArcGIS Web Adaptor instances registered with your site to match the new version.

Run the post installation utility

To run the post installation utility, complete the following steps:

1. Open the command prompt window as an administrator.
2. Change directories to the ArcGIS Notebook Server tools folder. By default, this path is C:\Program Files\ArcGIS\NotebookServer\tools\postInstallUtility.
3. Optionally, refer to the utility's help by running the following command: PostInstallUtility.bat -h
4. ArcGIS Notebook Server requires Docker Engine Community Edition to be installed on your machine. Determine whether Docker is active on your machine by running the following command: PostInstallUtility.bat -d
5. If Docker Desktop is not installed, install it now.

   ArcGIS Notebook Server uses Linux containers in Docker Desktop. When you install Docker Desktop, ensure that you specify Linux containers, and do not click the Switch to Windows containers option.

6. When using Docker Desktop, modify each of the following settings:
   1. Right-click the Docker button in the system tray and click Settings. Under General, check Expose daemon on tcp://localhost:2375 without TLS.

      You'll be using the Docker Remote API, which requires the use of port 2375.

   2. Right-click the Docker button in the system tray and click Settings. In the Settings menu, click Resources > File sharing and add the drive directory that will be used for your ArcGIS Notebook Server configuration store.

      Note:

      Docker for Windows only supports local directories on Windows that are to be shared with Linux containers.

7. Install your Notebooks image by specifying its file path. The image should be zipped in the .tar.gz format. If you have an Advanced license and Docker Desktop, run the command twice to install both the Standard and Advanced container images you downloaded from My Esri.

   Note:

   Ensure that your machine has at least 75 GB of available disk space.

   Run the following command: PostInstallUtility.bat -l <path of .tar.gz Docker image>

   Note:

   Ensure you install both container images. Even if you have the Advanced license, your users may still need to use the Standard runtime.

Install and configure ArcGIS Notebook Server samples data

When setting up a multiple-machine ArcGIS Notebook Server site, you must install and configure the samples data only on the first machine where you have installed Notebook Server and created the site.

To install and configure the samples data, follow these steps:

1. Run the ArcGIS Notebook Server samples data installation wizard you downloaded from My Esri.

   The samples data is installed in the directory where ArcGIS Notebook Server is installed.

2. Open the command prompt window as an administrator.
3. Change directories to the ArcGIS Notebook Server tools folder.

   By default, this path is C:\Program Files\ArcGIS\NotebookServer\tools\postInstallUtility.

4. Optionally, refer to the utility's help by running the following command:

    > PostInstallUtility.bat -h

5. Run the post installation utility to extract the samples data to the arcgisworkspace directory of the notebook server site:

    PostInstallUtility.bat -x

Replace ArcGIS Web Adaptor instances

To replace ArcGIS Web Adaptor instances, complete the following steps:

1. Unregister the previous instance of ArcGIS Web Adaptor from your site and uninstall.
   1. Sign in to your ArcGIS Notebook Server Administrator Directory.
   2. Browse to System > Web Adaptors > registered machine.
   3. Click Unregister Web Adaptor.
2. Install a new instance of ArcGIS Web Adaptor 11.1 and configure it with ArcGIS Notebook Server.
Once your deployment upgrade is complete, you can use 11.1 functionality.
3. If upgrading from 10.8 or earlier, to enable scheduling of notebooks in your portal, do the following:
   1. Optionally, update any of your custom roles that include notebook privileges to add the new Schedule Notebooks privilege.
   2. Instruct your notebook authors to update the runtime of each of their notebooks if they want to use the scheduling feature.

      Only notebooks using the 10.8.1 runtime (version 4.0) or later can be scheduled.

Your ArcGIS Notebook Server 11.1 site is now ready to host ArcGIS Notebooks.