Upgrade ArcGIS Notebook Server on Windows Server 2019 (Linux containers)—ArcGIS Notebook Server

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

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

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

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

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

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.3 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 Desktop for Windows to version 4.24.2 or earlier
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 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.
The Windows service account for your ArcGIS Notebook Server site (its Run As account) must remain the same when upgrading.

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:

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.
Browse to site > Export Site.
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.
Click Export.
When the export operation is complete, the directory provides 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 11.3. 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:

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.
After the upgrade utility has completed, reauthorize the ArcGIS Notebook Server software for 11.3. Use the software authorization wizard to complete the authorization.
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.
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:

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 the 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
```
Use the upgradesite utility and complete the upgrade by running the following command. By default, the upgradesite utility is available 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.
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.3.

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.

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

<ArcGIS Notebook Server install directory>\tools\SoftwareAuthorization\SoftwareAuthorization.exe /F <full path to the .prvc file> /O <full path to authorization file output>

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 authorize@esri.com. Esri will send an .ecp authorization file back to you in an email.
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:
```
<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 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:

Open the command prompt window as an administrator.
Change directories to the ArcGIS Notebook Server tools folder. By default, this path is C:\Program Files\ArcGIS\NotebookServer\tools\postInstallUtility.
Optionally, refer to the utility's help by running the following command: PostInstallUtility.bat -h
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
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.
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.
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.

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.

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, complete the following steps:

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.
Open the command prompt window as an administrator.
Change directories to the ArcGIS Notebook Server tools folder.
By default, this path is C:\Program Files\ArcGIS\NotebookServer\tools\postInstallUtility.
Optionally, refer to the utility's help by running the following command:
```
 > PostInstallUtility.bat -h
```
Run the postinstallation 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:

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.
Install a new instance of ArcGIS Web Adaptor 11.3 and configure it with ArcGIS Notebook Server.

Once the deployment upgrade is complete, you can use 11.3 functionality.

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.3 site is now ready to host ArcGIS Notebooks.

Feedback on this topic?

Note:

Note:

Prepare to upgrade

Back up the deployment

Upgrade using the setup program

Note:

Upgrade from the command line

Authorize silently

Authorize in a disconnected environment

Steps after upgrading

Run the post installation utility

Note:

Note:

Note:

Note:

Install and configure ArcGIS Notebook Server samples data

Replace ArcGIS Web Adaptor instances

In this topic