I already wrote about Jupyter and JupyterLab which is my standard sandbox environment nowadays. There is even a blog post about how to install JupyterLab in an OCI Compute instance. But, JupyterLab is a single-user environment: how can you have the same for multiple users?

Jupyter has an answer for you, it’s named JupyterHub. A tool giving you Jupyter for multiple users, each will have a separate instance and not interfere one with the other (you crash yours, your colleague will not be impacted by it).
Reading the official JupyterHub page I had the impression the installation was tedious and that’s why they suggested a Kubernetes approach or to use another tool which is a packaged installer.

JupyterHub structure and processes

In practice the install is simpler than it looks like! The main downside is that, by default, your JupyterHub will be executed by root. This is something I’m never too comfortable with: I prefer when nothing use root.
The JupyterHub documentation covers all the steps needed to be able to run it as a standard user, which requires to allows sudo privileges for a single command, the one which will start the various JupyterLab instances for the users logging in.

Be default JupyterHub will authenticate users with the users existing locally in the linux environment. This means that only users having a valid linux username and password will be allowed to connect. It’s possible to use external authentications (in a future post I will explain how you can use Oracle IDCS) or even developer a custom authenticator, but the default is by using the local users.

Install JupyterHub in an OCI Compute instance

You maybe have read that I had to setup an environment for a hands-on lab and it was using 16 compute instances setup in the same identical way. For the lab I had to provide a JupyterLab instance for up to 55 users, a perfect use case for JupyterHub.
That’s why I wrote a simple script which does the whole JupyterHub install. Starting from the required Python (only Python 3 is supported), installing the various components needed, creating the required users and groups and, when everything is done, creating a service to automatically start JupyterHub with the compute instance and opening the port in the firewall.

I start with a new Compute instance using Oracle Linux 7.8 where I upload the scrip and execute it.

a new OCI instance for JupyterHub
Create a fresh new OCI Compute instance using Oracle Linux 7.8 image. Oracle Linux 7.7 also works exactly the same.

The script is the following:

I’m not going to explain every step as it would be like duplicating the JupyterHub documentation. The important part is to configure the 3 variables on top based on your needs/wishes:

  • JUPYTERHUB_USER : the name of the user executing JupyterHub (instead of ‘root’ in a default install)
  • HUB_USERS_GROUP : the name of the group whose members will be allowed to login in JupyterHub (to not allow any user existing in the linux environment)
  • SHADOW_GROUP : the name of the group which will be set as owner of the /etc/shadow file, by default in Oracle Linux the group is ‘root’, but the JupyterHub user must be allowed to read this file to authenticate users.

JupyterHub will be installed in /opt/jupyterhub (edit the script if that location doesn’t suit you).

upload the script and execute it
Upload / create the script, make it executable and run it.
JupyterHub install script executed
The script is over (doesn’t take long). Everything has been setup.

Once the install is done you can do some tests to see if everything has been created properly.

test the JupyterHub service
You can test if the JupyterHub service is running.
test the firewall ports
You can also verify that the port (TCP 8000) is open in the firewall.

If everything is correct and you also allowed the connection to port TCP 8000 in the security list of the virtual cloud network, point your browser to the instance address port 8000, http://xxx.xxx.xxx.xxx:8000 .

JupyterHub login screen
By default, JupyterHub doesn’t use HTTPS, which isn’t a nice thing as the message says.

As said by default it will authenticate only local users with linux username and password defined and being part of the group configured in the script, hub-users if you didn’t change it.
If you want a user not allowed to login by SSH to the instance, but still with a valid login for JupyterHub you can use this kind of commands to create the local users in your linux:

If you want your user to be able to use the “Terminal” in JupyterLab you will need to use another shell than /sbin/nologin, like for example the default /bin/bash.

After the login the normal JupyterLab is available
After the login in JupyterHub the user sees the typical JupyterLab screen.

As simple as that: install JupyterHub in an OCI Compute instance by executing a single script.

Share This