Extend a notebook runtime—Administer ArcGIS Notebook Server

Esri provides two notebook runtimes — collections of Python modules — with ArcGIS Notebook Server. These runtimes are made available to notebook users through container images, which are applied to each container that runs in your server site.

Both the Standard and Advanced notebook runtimes include the ArcGIS API for Python and various Python modules that can be used for data science, spatial analysis, content management and administration. The Advanced runtime also includes ArcPy.

See the list of available Python libraries

In some cases, your notebook authors may need modules or specific versions of modules beyond what's included in these two runtimes. There are two ways you can access additional Python modules in ArcGIS Notebook Server:

Install a Python module during a notebook session. This makes the module available for use in that notebook.
Extend an Esri container image to include additional Python libraries in a custom runtime. The container image you create will make the extended runtime available for all notebook authors in your site.

Install modules during a session

Notebook authors can make Python modules, or versions of modules, not in either runtime available for use during a notebook session using the conda or pip package management systems. The recommended system to use is conda, because ArcGIS Notebook Server already uses it to manage modules; however, some Python modules are available in pip and not in conda.

This approach will install the desired module for the duration of the notebook session; once the notebook is closed or the container belonging to the user is terminated, the module will no longer be available. To install modules using this method, users must have internet connectivity to the conda or pip channels.

Note:

Both conda and pip are included in the two Esri notebook runtimes. You do not need to install them.

To install the scrapy package during a session, for example, run a notebook cell with either of the following commands:

Using the conda package management system

!conda install --yes scrapy

Using the pip package management system

!pip install scrapy

If you need to use a different version of a Python module in the Esri notebook runtime you're working in, specify the version number in the command.

For example, the numpy package is available in both Esri runtimes at version 1.15.2. To make version 1.16 of numpy available during a notebook session, run a notebook cell with either of the following commands:

Using the conda package management system

!conda install --yes numpy==1.16

Using the pip package management system

!pip install numpy==1.16

Build a custom container image

If you want to make persistent changes to a notebook runtime, you can build a custom container image for use in a site. The following workflow, which requires administrative privileges, creates a custom image and configures ArcGIS Notebook Server to use it.

You will use either of the two Esri notebook runtimes (Standard or Advanced) as a starting point. That runtime will be replaced by the modified runtime in your container image.

Install and configure ArcGIS Notebook Server following the comprehensive install guide.
Log into the ArcGIS Notebook Server Administrator Directory as an administrator. The URL is formatted https://notebookserver.domain.com:11443/arcgis/admin/.
Navigate to notebooks > runtimes, then select the Esri notebook runtime you want to extend for your custom image. On the runtime's resource page, note the imageId value for this runtime. You will include this value in the next step.
Create a Dockerfile that adds your desired Python modules to the custom image. A Dockerfile is a simple text file that serves as a recipe to build a Docker container image. Follow the Dockerfile documentation for information and best practices. Save your Dockerfile on the machine.
In this example, we want to add the data visualization Python package graphviz to the Advanced notebook runtime. The following codeblock in our Dockerfile tells Docker to access the Advanced runtime using its imageId value, then to install graphviz within the runtime. The conda clean command is a best practice to reduce file size.
```
# Specify the existing notebook runtime imageId as FROM
FROM aa7a1a346e5b

# Use RUN to issue a command to install, then clean
RUN conda install -c anaconda graphviz \
  && conda clean -y -a
```
Build your new custom container image using a Docker command. This image will contain a new runtime as specified in your Dockerfile. Open Command Prompt and run a command with the following syntax:
```
docker build -t <name of my new runtime>:v1.0 -f <path to my Dockerfile> .
```
Note:
Be sure to include the period at the end of the command.
When the command executes, Docker will build your new container image. The last line in the command output will be Successfully built <imageId> with the abridged ID value of the new image. You'll need to provide your ArcGIS Notebook Server site with its full imageId value. To obtain this value for the new image, run the following command in your Command Prompt:
```
docker inspect <imageId>
```
Now that your custom image is built and you have its full imageId value, update the ArcGIS Notebook Server Administrator Directory to include the new image. Return to the resource page for the runtime you used in step 3, and click Update. Change the value for imageId, then save your edits.
Test this update by opening a new notebook. Verify that the modules or versions of modules you added to your custom image are available in the notebook.

If you ever want to revert the runtimes available in your ArcGIS Notebook Server site to the original settings, use the Restore Factory Runtimes operation in the Administrator Directory. This is available at the URL https://notebookserver.domain.com:11443/arcgis/admin/notebooks/runtimes/restore.

Feedback on this topic?