Docker

While Anaconda is an environment-level container, Docker (and Singularity below) are OS-level containers.1 Docker is probably the best method of running Jupyter+pyroot without having to worry about issues like package compilation, though you won’t be able to use it to go through The Basics. Its disadvantage is that it requires administrative access to the host computer system (e.g., your laptop), both to install Docker and to run the Docker container.2

The first step is to install Docker. For Mac and Windows systems, use Docker Desktop; there’s a different procedure needed for Linux systems.

Once Docker is installed and running, you’ll be able to download and run a Docker container:

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot:latest-<proc>

where <proc> is amd64 for any machine with an Intel or AMD processor, or arm64 for a system with an ARM processor (such as a Mac with an M1 or M2 chip).

(Windows users will probably need to use %CD% instead of $PWD.)

The first time you run this command, it will download a ~2.5GB container. Give it time.

Finally, you’ll see some output. Look at that output carefully, as it will tell you how to access Jupyter via a web browser. For example, assume the output contains something like this:

To access the notebook, open this file in a browser:
file:///root/.local/share/jupyter/runtime/nbserver-1-open.html
Or copy and paste one of these URLs:
http://649d0c4b4dc1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c
or
http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

Remember, your complicated token won’t be 97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c. That was just the value returned by Jupyter at the time I created this example.

Start up a web browser and visit (in this example):
http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

You’ll see the standard Jupyter home page.

That will get you started. The next few sub-sections are for refining your use of Docker.

Changing the port

Consider the command:3

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot:latest-amd64

That first 8080 is the port to use on your local computer. If you want to use a different port on your computer (for example, you’re already using port 8080 for something else), change that first 8080 to a different port. Note that if you change the port, you’ll also have to change the port in the URL in the output; e.g.,

sudo docker run -p 7000:8080 -v $PWD:/work wgseligman/jupyter-pyroot:latest-amd64

means you’ll have to change:

http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

to:

http://127.0.0.1:7000/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

Changing the directory

Again, consider:

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot:latest-amd64

That $PWD (%CD% in Windows) just means “the current directory.” The execution environment within the container uses /work for its files; the -v option in the command means “map /work to the current directory in the terminal.” If you’d like to use a different directory on your computer as the work directory in the Docker container, substitute that directory for $PWD. For example:

sudo docker run -p 8080:8080 -v ~jsmith/root-class:/work wgseligman/jupyter-pyroot:latest-amd64

Changing the container

You can use click on the Terminal icon within Jupyter to get a shell. Within that shell, you can modify anything within the container you want; for example, you can use pip3) to install new Python packages or yum) to install new Linux packages.4

However, any changes you make to the Docker container won’t be automatically saved when you quit the container. When you next start the container, it will start “fresh.” If you want to save your changes, you’ll have to commit.) them.

For example, assume that you’ve made some changes to your copy of the jupyter-pyroot container. Look up the ID of the container as assigned by your local docker process:

sudo docker container ls
CONTAINER ID IMAGE COMMAND [...]
1105371318e8 wgseligman/jupyter-pyroot "jupyter notebook ..." [...]

Your output will be different; I’ve omitted most of the columns, and you’ll have a different CONTAINER ID. Commit a revised container using your own image name:

sudo docker commit 1105371318e8 $USER/jupyter-pyroot

You’ll can see your new image with the docker images command. For example, if $USER is “jsmith”:

sudo docker images
REPOSITORY TAG IMAGE ID [...]
jsmith/jupyter-pyroot latest 97ca601cbf9c [...]
docker.io/wgseligman/jupyter-pyroot latest 16c3bbdc8144 [...]

From that point forward, you’ll probably want to run your new container with your changes:

sudo docker run -p 8080:8080 -v $PWD:/work jsmith/jupyter-pyroot

Docker container notes

I prepared the container wgseligman/jupyter-pyroot to be similar to the environment of the notebook server; for example, it runs the same version of the OS and of ROOT (as of May-2023, that’s AlmaLinx 9 and ROOT 6.28.02).

A little bit web searching will show there are other ROOT containers available. For example:

sudo docker run -p 3000:8080 pedwink/pyroot-notebook

That particular container uses Fedora 28 and ROOT 6.14, and it also offers Python 2 versions of its notebook kernels (wgseligman/jupyter-pyroot only offers Python 3).

So, if you can’t find the feature you want in wgseligman/jupyter-pyroot, hunt around a bit. It’s probably out there.

xkcd containers — Figure 68: https://xkcd.com/1988/ by Randall Munroe

1: In contrast to emulators like VMware, which are machine-level containers.
2: Strictly speaking, you can in theory run Docker in “rootless” mode, either on its own or using the docker alternative podman. In practice, when I tried this it led me down a road of complexity that was roughly equivalent to installing ROOT from scratch. If you don’t have administrative access to your computer, I recommend looking at a different solution than docker or podman.
3: For the rest of this page, I’m going to assume that you’re on a system with an Intel-compatible processor. If you’re on M1 or M2 Mac, don’t forget to replace amd64 with arm64.
4: If you install something of general interest, let me know. I may add it to the main jupyter-pyroot container.