Simple setup of JupyterHub in Docker

Have you ever wanted to test out Jupyter Lab Notebooks in a multi-user environment, but didn’t want to setup a full server stack just to see if this is the right tool for your Lab? Thanks to sandboxed virtual containers like Docker, this can be an easy setup for an internal deployment. However, it is not as simple as downloading the Docker container for JupyterHub. There is a bit more of a process to get a Dev environment setup and working to use the JupyterLab Notebooks. Here is a simple procedure I used to test out the notebooks in my Dev environment.

Assumptions

First, I will assume that you have already installed Docker and have a vague familiarity with how to start Docker containers. I will also assume you have a brief understanding on using the Terminal session for Debian based Linux distributions. In this case, we will be using a minimal Ubuntu Server. It is also assumed that the user web clients can access the server through the opened port. (or simulate multiple users by logging in and out of various users on your own system)

Warning

Do not expose this server outside of your Dev environment. This simple setup does not take into account setting up the SSL certificates or other security measures. The JupyterHub documentation should be consulted for best practices. This article is just to help you get your feet wet and quickly so you can test if this is the right tool for your Lab. If you find you would like to deploy this live to your users, it is your responsibility to fully research the proper way to deploy a server. It is usually not recommended to use the Docker containers for your live servers, and by what I have read of the documentation it appears that a well versed Linux admin should be able to install the software on your more hardened server stacks. Use my guide at your own risk!

Startup the Jupyterhub container

If you review the Docker Hub for jupyterhub/jupyterhb, the directions have you directly run jupyterhub at the startup of your container. This will startup a a generic JupyterHub, but you will not be able to log in as an Admin user nor will it be connected to any Jupyter Lab Notebook servers. My tests allow you to adjust the config so that you can run the JupyterHub service as well as connect it to the local Jupyter Lab Notebook server in the same container, as well as setup an ‘Admin’ user.

To start the container (and automatically download the latest image if you do not yet have it), enter the following command in a terminal window (assumes you have Docker running and can start containers from your terminal).

docker run -it -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub bash

This will download and start the container in an interactive mode (so you can see the logs live), open port 8000, give the container an easy name (jupyterhub), which container to use (jupyterhub/jupyterhub) and start the bash prompt (instead of the Docker Hub instructions which automatically start jupyterhub).

Update and Install useful packages

The container is a minimal version of Ubuntu, so we will want to update the package manager listings and make sure all existing packages are up to date. As a personal preference, I prefer to use the Nano package for editing text files so we will add that as well. For security reasons, you will want to create a user and give them sudo privileges to perform these steps but we will not address that here as that is beyond the scope of this article. Use the ‘root’ user at your own risk. Type the following at the command prompt inside the container ( should say something similar to ‘root@containerId’ )

apt update
apt upgrade
apt install nano

Add users to the Ubuntu Operating System

For this simple setup, we will use the default authentication setup for JupyterHub which uses the operating system user names and passwords to manage user access. One of the biggest issues I found when using the same container to launch the Jupyter Lab Notebooks service, each user also needed to have their own home directory in the OS in order to store their notebooks. Otherwise, when JupyterHub attempted to start the notebook service it would fail with a very cryptic message. I don’t remember how I figured this out but Stack Overflow was very helpful.

Note, you can use the linux ‘adduser’ command if you prefer as it will walk you through setting up details about the user, set their password and automatically create their home directory. However, since all I really need is the username, password and a home directory I will use the ‘useradd -m’ command ( -m creates home directory for user ), followed by the ‘passwd’ command to set their password. Enter the following to create two users, replacing with your preferred names:

useradd -m labadmin
useradd -m chemist1

and then set passwords for each user

passwd labadmin
passwd chemist1

Generate a default JupyterHub configuration file

Generating a default configuration file will allow you to see all the various aspects of the server you can adjust to your needs. This is a very extensive listing that shows you all the default values for each. Take a few minutes to read through it just to get an idea of all the settings you could possibly adjust. We however will only add one line at the top so that we can have an ‘Administrator’ user to allow us to manage the JupyterHub server, add users to the Hub and start/stop Lab Notebook servers. From the command prompt, enter the following (note, you should already be in the /srv/jupyterhub/ folder):

jupyterhub --generate-config

Next we want to edit this configuration file to add the ‘labadmin’ (or whatever name you chose above) user as the Administrator. From the command prompt enter the following:

nano jupyterhub_config.py

Inside of Nano, move the cursor down a couple lines and type the following ( replacing with your admin username )

c.Authenticator.admin_users = set('labadmin')

Then save the file using CONTROL+X then press Y to save the buffer, and then press ENTER key to accept same file name.

Install JupyterLab Notebooks

Next is to install the JupyterLab Notebook service inside the container to make this an easy solution. You could host the lab notebooks on another server if you prefer, you will need to edit the jupyterhub_config.py file accordingly to point to the notebook server ( read the JupyterHub docs, as using external server is beyond the scope of this article ). From the command prompt type the following:

pip install jupyterlab

Running the JupyterHub

We are now at the point of starting up the JupyterHub and logging into the Administration page to add users to the Hub. (Note, you can actually add users to the jupyterhub_config.py file in advance if you prefer not to use the admin interface). From the command prompt type the following:

jupyterhub

Next, open a web browser to the default port set in the docker run command: http://localhost:8000/

Log is with the ‘labadmin’ and password you assigned to the Administrator user. Then click the ‘Control Panel’ button at the top right. Next click the ‘Admin’ link at the top menu. Click the ‘Add Users’ button. This will open a popup message to enter new users each separated by a line break. Add the ‘chemist1’ user we added to the Ubuntu OS. You can add as many users as you want here, as long as they have accounts created on the Ubuntu server as we did near the beginning of the article.

The next steps is to play around a little, add some notebooks and files. It is beyond the scope of this article at this time to go into how to use JupyterHub and JupyterLab notebooks, but stay tuned for a future article where I will give some tips for how I like to use the Hub and organize my files and notebooks.