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.4, you must also upgrade ArcGIS Notebook Server.

The ArcGIS Notebook Server 11.4 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.4.

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

You must also install new container images from Esri, providing your users with 11.4 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.4, they must update the runtime of their notebooks. The notebook runtimes corresponding to 11.4 are at version 11.0 (ArcGIS Notebook Server Standard 11.0 and ArcGIS Notebook Server Advanced 11.0 options).

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 retired following the ArcGIS Enterprise Life Cycle. A notebook runtime will be retired at the same time the associated version of ArcGIS Enterprise is retired. Notebooks should not use retired 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. 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 finish upgrading to 11.4.

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.4.

Prepare to upgrade

Before upgrading, review the following information:

• You can access all of the necessary files in My Esri before upgrading, including the 11.4 container images.
• For ArcGIS Notebook Server to function correctly, its version must match the version of the portal with which it's federated.
• If your Notebook server is currently in read-only mode, turn the mode off before beginning the upgrade process.
• Upgrade Docker to version 27.1.2 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.
• 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 using either the setup program or the 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.

Move the workspace directory

This process is required for single-machine ArcGIS Notebook Server deployments on Linux that have a workspace directory\ in the notebook server installation directory.

1. Sign in to your ArcGIS Enterprise portal as an administrator and open ArcGIS Notebook Server Manager.
2. Click the Settings tab.
3. Click Directories.
4. Determine whether the current path to the arcgisworkspace directory is in the ArcGIS Notebook Server installation directory.

   <installdir>/arcgis/notebook/directories/arcgisworkspace

   If the arcgisworkspace directory is in the ArcGIS Notebook Server installation directory, you must move the workspace directory to a location outside the installation directory before you can upgrade.

   If the arcgisworkspace directory is not in the ArcGIS Notebook Server installation directory, you do not need to perform the remaining steps in this section.

5. Click Edit for the arcgisworkspace directory.
6. Replace the existing directory path value with the new path for the arcgisworkspace directory that is outside the installation directory.

   <installdir>/arcgis/arcgisnotebookserver/directories/arcgisworkspace

7. Click Save.
8. Manually copy all of the contents from the previous arcgisworkspace directory to the new arcgisworkspace directory.

Back up the deployment

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

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.

To run the backup operation, complete the following steps:

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. Provide the full path of the location on your machine where 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.4. 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.

To upgrade using the setup program, complete the following steps:

1. 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 uninstalls the previous version of ArcGIS Notebook Server and installs the upgraded version of ArcGIS Notebook Server.

2. After the upgrade utility has completed, reauthorize the ArcGIS Notebook Server software for 11.4. Use the software authorization wizard to complete the authorization.
3. Open the configuration wizard using the URL listed at the end of upgrading the installation 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 ./Setup from the location where ArcGIS Notebook Server was extracted, with the argument shown in the example below and follow the prompts to complete the upgrade.

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

   <untar directory>/Setup -l yes -m silent

2. After the upgrade utility has completed, reauthorize the ArcGIS Notebook Server software for 11.4. Run the software authorization with the following syntax to authorize ArcGIS Notebook Server silently:

   <ArcGIS Notebook Server install directory>/tools/authorizeSoftware

   Run the following command to view all options for authorization:

   <ArcGIS Notebook Server install directory>/tools/authorizeSoftware --help

   Note:

   See the Authorize in a disconnected environment section below for information about authorizing ArcGIS Notebook Server installations in a disconnected environment.

3. Upgrade the site using the upgradesite command line utility.

   This 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.

   By default, the upgradesite utility is available at ${HOME}/arcgis/notebookserver/tools/upgradesiteutility/upgradesite.sh.

   Before upgrading, review the preparation information at the beginning of this topic. When you are ready to upgrade, open a command terminal on the machine you're upgrading. Browse to the directory where the utility is located, and run the following command:

   > ./upgradesite.sh -s

   The utility displays progress reports and stops when the upgrade is complete.

4. For a multiple-machine site, follow steps 1 through 3 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.4.

Run the software authorization with the following syntax to authorize ArcGIS Notebook Server silently:

<ArcGIS Notebook Server install directory>/tools/authorizeSoftware

Run the following command to view all options for authorization:

<ArcGIS Notebook Server install directory>/tools/authorizeSoftware --help

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:

   <ArcGIS Notebook Server installation directory>/tools/authorizeSoftware -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 self-service site. 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 receive the .ecp authorization file using either method above, run the authorizeSoftware script again to process it and complete the server authorization process:

   <ArcGIS Notebook Server installation directory>/tools/authorizeSoftware -f <full path to the .ecp file>

Repeat this workflow for each machine running ArcGIS Notebook Server.

Steps after upgrading

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

Run the post installation utility

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

1. Open a terminal using the ArcGIS Notebook Server installation account.
2. Change directories to the ArcGIS Notebook Server tools folder. By default, this path is ${HOME}/arcgis/notebookserver/tools/postInstallUtility.
3. Optionally refer to the utility's help by running the following command: ./PostInstallUtility.sh -h
4. ArcGIS Notebook Server requires Docker Engine to be installed on your machine. Determine whether Docker is active on your machine by running the following command: ./PostInstallUtility.sh -d
5. If Docker Desktop is not installed, install it now.
6. 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.sh -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.

Note:

Older images are not automatically removed. You must manually update the runtimes associated with each notebook to the newer version before you delete the previous runtime images.

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 the site and uninstall it.
   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.4 and configure it with ArcGIS Notebook Server.
Once the deployment upgrade is complete, you can use 11.4 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 the custom roles that include notebook privileges to add the new Schedule Notebooks privilege.
   2. Instruct 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.

The ArcGIS Notebook Server 11.4 site is now ready to host ArcGIS Notebooks.