Install ArcGIS Notebook Server and Windows containers

At 11.0, ArcGIS Notebook Server with Windows containers and Mirantis Container Runtime is available as a beta release on Windows.

Note:

While in beta, these features may have known performance or quality issues and will not be supported by Esri Technical Support.

ArcGIS Notebook Server and Windows containers

Similar to other ArcGIS Notebook Server deployments, ArcGIS Notebook Server with Windows containers is installed on a server operating system and is configured and federated with an ArcGIS Enterprise portal. Additionally, a web adaptor can be deployed in front of the ArcGIS Notebook Server software.

ArcGIS Notebook Server uses virtualized operating systems known as containers to isolate notebook authors' environments. As a result, the containers allow each author to use a subset of server resources without their work or resource usage interfering with others.

These containers are allocated and maintained by Mirantis Container Runtime, formerly Docker Engine Enterprise, a third-party software component. Before installing ArcGIS Notebook Server, you must install Mirantis Container Runtime version 20.10 or later. Once ArcGIS Notebook Server is installed, it must be configured to work with Mirantis Container Runtime.

ArcGIS Notebook Server allocates one container per runtime to each notebook author on the site, and only they can work in the container. The computing resources the authors use when running notebooks will not affect other authors' containers.

When a portal member with corresponding privileges opens their first notebook, a container is launched on the ArcGIS Notebook Server site. This session between the notebook and the container will be ongoing through the duration of the notebook.

ArcGIS Notebook Server can join multiple machines together in a site. Machines in a multiple-machine configuration must be configured to be identical, and each machine can run ArcGIS Notebooks.

Notebook runtimes and Windows container images

Esri provides a single Windows container image for ArcGIS Notebook Server. This container image includes the Standard and Advanced notebook runtimes, which make Python resources available in ArcGIS Notebooks. See Available Python libraries for more information on the libraries available in each runtime.

The two ArcGIS Notebook Server runtimes, Standard and Advanced, are available in notebooks as part of the container image. Depending on your license and user privilege, either the Standard or both the Standard and Advanced runtimes will be available for use.

The Windows containers in an ArcGIS Notebook Server site support two modes of runtime isolation, process and Hyper-V. See the Microsoft documentation on Isolation Modes for more information on the modes. If you configure your site to use Hyper-V isolation, the Hyper-V role must be installed on the machine.

Note:

There are limitations with respect to the number of containers that can be run when using Windows containers with Hyper-V. See this Microsoft FAQ for more information.

When a container is launched, the Windows container image provided by Esri is applied to the container. The runtime will depend on the license configured for ArcGIS Notebook Server and the notebook author's privilege.

Note:

At 11.0, there is a known limitation that may result in WinError 1455 when importing the torch library or Python libraries that have torch as a dependency.

Note:

fiona, rasterstats, and rasterio are not installed in the Windows containers.

Set up prerequisite software

Before installing ArcGIS Notebook Server, you must install and configure the following prerequisite software.

System requirements

The following system requirements must be met to install ArcGIS Notebook Server with Windows containers:

• Windows Server 2022 is the only operating system that is supported for ArcGIS Notebook Server with Windows containers.
• ArcGIS Notebook Server with Windows containers requires Mirantis Container Runtime version 20.10 or later.
• Hyper-V is optional, depending on the runtime isolation mode chosen for your ArcGIS Notebook Server site.
• ArcGIS Notebook Server with Windows containers requires a minimum of 75 GB of available disk space.
• Review the ArcGIS Notebook Server system requirements.

Enable Hyper-V (optional)

Hyper-V is only required if you intend to run Windows containers in the Hyper-V isolation mode.

To enable Hyper-V, refer to Install the Hyper-V role on Windows Server in the Microsoft documentation.

Install Mirantis Container Runtime

Follow the steps below to install Mirantis Container Runtime on your machine.

1. Uninstall any previous version of Docker on your machine.
2. Do not enable the Containers feature on your local server prior to installing Mirantis Container Runtime. If this feature is already enabled, disable it on your server machine. See Install or Uninstall Roles, Role Services, or Features in the Microsoft documentation for more information.
3. Follow the steps in Install Mirantis Container Runtime on Windows Server in the Mirantis documentation.
4. Verify that Mirantis Container Runtime is installed and has been started by running the following command:
   docker run hello-world:nanoserver

5. Once completed, follow the steps below to configure Mirantis Container Runtime.

Configure Mirantis Container Runtime

1. Enable port 2375 to enable the use of the Docker remote API. This port will only be used internally by ArcGIS Notebook Server and should be protected from external use. To enable the port, open a command prompt as an administrator and run the following command:
   sc config docker binpath= "\"C:\Program Files\docker\dockerd.exe\" --run-service -H tcp://localhost:2375 -H npipe://"

2. Open a PowerShell window as an administrator and run the following command:

   Restart-Service docker

3. Once the Docker component is installed, restart your machine.

   Note:

   Each time you install or upgrade the Docker component, you must restart the machine.

Install ArcGIS Notebook Server

Follow the steps in the Install ArcGIS Notebook Server help topic to install ArcGIS Notebook Server using either the installation wizard or the command line.

Configure ArcGIS Notebook Server after installation

When your ArcGIS Notebook Server installation is complete, run the postinstallation utility to install the Windows container image. Sign up for the ArcGIS Enterprise beta features testing program in the Esri Early Adopter Community (EAC) to download the Windows container image. Perform the following steps for each machine on which you have installed ArcGIS Notebook Server.

1. Open the command prompt window as an administrator.
2. Change directories to the ArcGIS Notebook Server tools folder. By default, the path is C:\Program Files\ArcGIS\NotebookServer\tools\PostInstallUtility.
3. Determine whether Mirantis Container Runtime is active on your machine by running the following command:

   PostInstallUtility.bat -d

4. If Mirantis Container Runtime is not installed, install and configure it using the instructions provided above.
5. Run the following command:

   > PostInstallUtility.bat -l <path of .tar.gz Docker image>

Create an ArcGIS Notebook Server site

After you have installed ArcGIS Notebook Server and have configured the Windows container image using the postinstallation utility, create a server site by following the instructions in Create an ArcGIS Notebook Server site.

Note:

If you intend to deploy ArcGIS Notebook Server on multiple machines, read the Considerations for the Notebook Server directories and configuration store section below before creating a site.

Considerations for the Notebook Server directories and configuration store

If you plan to deploy ArcGIS Notebook Server on multiple machines, the content directory and configuration store must use a shared directory referenced by a Universal Naming Convention (UNC) path. The workspace directory must always use a UNC path configured as a mapped network, with a matching drive letter on all machines participating in the site, and use it as the workspace directory.

See the Set up a mapped network drive for the workspace directory section below for instructions on how to configure a mapped network drive.

Enable a Windows container feature for Notebook Server

After successfully creating your site, follow the steps below to opt-in to use ArcGIS Notebook Server with Windows containers. Once your ArcGIS Notebook Server site has been created, sign in to the Administrative API to ensure the site is configured to use Windows containers.

1. Sign in to the ArcGIS Notebook Server Administrative directory as an administrator.
2. Click System > Properties.
3. Click Update properties.
4. Update the useWindowsContainers property to be set to true.
5. Click Update properties to save the changes.
6. Once the Notebook Server restarts and the administrative directory is accessible, click Notebook > Runtimes > Restore Factory Runtimes.

   https://notebook.domain.com:11443/arcgis/admin/notebooks/runtimes/restore

7. Click Restore Factory Runtimes to update the Notebook Server standard and advanced runtimes to use the Windows container images.

Install and configure ArcGIS Web Adaptor with ArcGIS Notebook Server

Once your ArcGIS Notebook Server site has been created, you must install ArcGIS Web Adaptor and register it with ArcGIS Notebook Server. See Install and configure ArcGIS Web Adaptor with ArcGIS Notebook Server for more information.

Install and configure ArcGIS Notebook Server samples data

ArcGIS Notebook Server samples data is required for Esri-curated sample notebooks that are included with ArcGIS Notebook Server. See Install and configure ArcGIS Notebook Server samples data for more information.

Configure Notebook Server with ArcGIS Enterprise Portal

After you have installed ArcGIS Notebook Server, configured it with Mirantis Container Runtime, created a server site, and registered the site with a web adaptor, you can configure the site with an ArcGIS Enterprise Portal. See Configure ArcGIS Notebook Server with the portal for more information.

Join additional machines to the ArcGIS Notebook Server site

ArcGIS Notebook Server supports multiple-machine sites. In a multiple-machine site, each machine must have the same configuration, with the same OS, identical Mirantis Container Runtime setup, and mapped network drive with the same drive letter for the workspace directory. See the Install and configure a multiple-machine site section of the Join additional machines to an ArcGIS Notebook Server site topic for more information.

Set up a mapped network drive for the workspace directory

This is an optional process that is only necessary if you plan to set up a multi-machine Notebook Server site.

1. Create a UNC share for the ArcGIS Notebook Server workspace directory on a separate machine that is accessible to the Notebook Server.

   Note:

   This directory must have read-write access to the ArcGIS Notebook Server Windows run-as account. It is recommended that you create a UNC share for the ArcGIS Notebook Server workspace directory on a machine separate from the machine participating in the ArcGIS Notebook Server site. There is a known issue in which SMB shares created on the same machine as the Notebook Server will disconnect when restarting the machine.

2. On the Notebook Server machine, open a PowerShell window as an administrator.
3. Save your ArcGIS Notebook Server user account password as a secured string for later using the following command:

   $password = ConvertTo-SecureString '<password>' -AsPlainText -Force

4. Add credential support to the PowerShell functions:

   $credential = New-Object System.Management.Automation.PSCredential('<domain\username>', $password)

5. Mount the folder with the Persistent flag set:

   New-SmbGlobalMapping -Persistent $true -RemotePath <shared folder path> -Credential $credential -LocalPath <unassigned drive letter>:

6. Repeat steps 2 through 5 on all machines participating in the ArcGIS Notebook Server site and assign the same drive letter for the mapped drive on all machines.
7. Use the shared network drive created in the previous step to configure the workspace directory when creating the ArcGIS Notebook Server site.

Extend a notebook runtime

See Extend a notebook runtime for more information.

After successfully following the steps in this topic, you will now have an ArcGIS Notebook Server deployment set up with Windows containers.