Upgrade ArcGIS Notebook Server

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

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

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

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

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

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

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 10.9 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 a supported version.
• 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 ArcGIS 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.

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 execute 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.
5. When the export operation is complete, the directory will provide a link to the backup file location on the server. 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 10.9. 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.

1. ArcGIS Notebook Server is designed to detect and upgrade an existing installation of ArcGIS Notebook Server components. 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 will identify the existing installation, and you will be 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, you must reauthorize your ArcGIS Notebook Server software for 10.9. 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

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 will uninstall the previous version of ArcGIS Notebook Server and install the upgraded version of ArcGIS Notebook Server.

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

2. After the upgrade utility has completed, you must reauthorize your ArcGIS Notebook Server software for 10.9. 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 the 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 will display progress reports and stop when the upgrade is complete.

4. For a multiple-machine site, follow steps 1 through 3 for each machine in the site, then continue to the steps in the next section.

Authorize silently

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

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 will be 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 customer service website at https://service.esri.com/drm. Follow the instructions on the screen to upload your authorization information file and download your .ecp authorization file.
   • Send your authorization information file by email to [e-mail]. Esri will send your .ecp authorization file back to you in an email.
3. When you have received your .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 postinstallation 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 postinstallation utility

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 is not installed, install it now.
6. Install your Docker image by specifying its file path. The image should be zipped in the .tar.gz format. If you have an Advanced license, run the command twice to install both the Standard and Advanced container images you downloaded from My Esri. 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

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 10.9 and register it with ArcGIS Notebook Server.
3. Once your deployment upgrade is complete, you can take advantage of 10.9 functionality. If upgrading from 10.8 or earlier, to enable scheduling of notebooks in your portal, do the following:

   • Update any of your custom roles that include notebook privileges to add the new Schedule Notebooks privilege, if desired.
   • 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 10.9 site is now ready to host ArcGIS Notebooks.