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

The ArcGIS Notebook Server 11.2 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.2.

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

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

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

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.2 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 of before beginning the upgrade process.
• Upgrade Docker to version 23.0 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.

Move your workspace directory

This process is required for single-machine ArcGIS Notebook Server deployments on Linux that have a workspace directory located inside 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. Check whether the current path to the arcgisworkspace directory is inside the ArcGIS Notebook Server install directory.

   <installdir>/arcgis/notebook/directories/arcgisworkspace

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

   If the arcgisworkspace directory is not inside the ArcGIS Notebook Server install 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 of the installation directory.

   <installdir>/arcgis/arcgisnotebookserver/directories/arcgisworkspace

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

Back up your deployment

Before you upgrade, it's recommended that you make backups of your 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.

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.2. 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.2. 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 ./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.2. 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 section Authorize in a disconnected environment for information on authorizing ArcGIS Notebook Server installs 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 found 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.2.

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 have received the .ecp authorization file using either above method, 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 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 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.

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.

Follow these steps to install ArcGIS Notebook Server samples data:

1. Open a command shell as the user who will run ArcGIS Notebook Server. Browse to the directory where you downloaded the ArcGIS Notebook Server samples data tar.gz file from My Esri.
2. Uncompress the tar.gz file with the following command:

   tar -xvzf ArcGIS_Notebook_Server_Samples_Data_Linux_.tar.gz

3. Browse to <install directory>/notebookserver/License to read the license agreement.
4. From the directory, run the script.

   ./ArcGISNotebookServerSamplesData-Setup.sh

5. Change directories to the ArcGIS Notebook Server tools folder.

   By default, this path is ${HOME}/arcgis/notebookserver/tools/postInstallUtility.

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

   > ./PostInstallUtility.sh -h

7. Run the post installation utility to extract the samples data to the arcgisworkspace directory of the Notebook Server site.

   > ./PostInstallUtility.sh -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.2 and configure it with ArcGIS Notebook Server.
Once your deployment upgrade is complete, you can use 11.2 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.2 site is now ready to host ArcGIS Notebooks.