Installing JupyterHub

Prerequisites

Before you begin, make sure you have the following:

A working installation of Package Security Manager version 6.4.0 or later.
A Linux server that meets the system requirements.

Installing JupyterHub

Download and unpack the installer

Download the installer by running the following command:

# Replace <INSTALLER_LOCATION> with the provided location of your installer
curl -O <INSTALLER_LOCATION>

Unpack the installer tarball:

Example

tar -xvf jupyterhub-<VERSION>-<HASH>.tar

Gather your SSL/TLS certificate information

Locate your SSL/TLS .crt and .key files and note their paths for later use.If you don’t have valid SSL/TLS certificates, you can proceed by using the DIY-SSL-CA package (included with the installer):

# Replace <HOSTNAME> with your JupyterHub server hostname
cd DIY-SSL-CA
bash create_noprompt.sh <HOSTNAME>

The create_noprompt.sh script generates the files that you’ll reference later as environment variables at the following directory locations:

DIY-SSL-CA/CA/ca.crt
DIY-SSL-CA/out/<HOSTNAME>/<HOSTNAME>-bundle.crt
DIY-SSL-CA/out/<HOSTNAME>/<HOSTNAME>.key

<HOSTNAME> is your JupyterHub server hostname.

Create a service account

The installer comes with a keycloak.py script. Use it to programmatically create a dedicated client for the JupyterHub services to authenticate users via Keycloak:

# Replace <KC_ADMIN> with the username for the Keycloak admin user
# Replace <KC_PASSWORD> with the password for the Keycloak admin user
# Replace <PSM_FQDN> with the fully qualified domain name of your Package Security Manager server
# Replace <CLIENT_ID> with the client ID for the JupyterHub service account
# Replace <JHUB_FQDN> with the fully qualified domain name of your JupyterHub server
python keycloak.py create -u <KC_ADMIN> -p <KC_PASSWORD> --protocol https --domain <PSM_FQDN> --clientid <CLIENT_ID> --baseurl https://<JHUB_FQDN>

Save the Client ID and Client Secret in a secure location.

Create an environment file

Create an environment file named .env in your /home/<username>/ directory.

If you already have an .env file in your home directory, you can name your new file something else, like .env_jhub_anaconda.

Add the following information to the .envfile you just created, including the actual values:

# Replace <ANACONDA_SERVER> with the fully qualified domain name of your Package Security Manager server
# Replace <CLIENT_SECRET> with the client secret for the JupyterHub service account
# Replace <CERT> with the path to your SSL/TLS certificate file
# Replace <KEY> with the path to your SSL/TLS key file
# Replace <CA_CERT> with the path to your CA certificate file (self-signed certificates only)
# Replace <SPAWNER_TYPE> with your JupyterHub spawner type: local|systemd. Defaults to systemd if not supplied.
ANACONDA_SERVER= <ANACONDA_SERVER>
CLIENT_SECRET= <CLIENT_SECRET>
CERT= <CERT>
KEY= <KEY>
CA_CERT= <CA_CERT>
JUPYTERHUB_SPAWNER_TYPE=<SPAWNER_TYPE> 
REPO_CHANNELS=("psm_chan1" "psm_chan2" "psm_chan3")

ANACONDA_SERVER= is the fully qualified domain name of your Package Security Manager server.

The CA Cert is only required if you are using self-signed certificates.

The REPO_CHANNELS variable is a list of channels that the JupyterHub services will use to install packages when users build new environments in Jupyter. The installer configures conda to respect the order of the channels as they are listed in the environment file.

Run the installer

Run the installation command:

# Replace <PATH_TO_ENV_FILE> with the path to the environment file you just created
# Replace <VERSION> with your installer version
# Replace <HASH> with your installer hash
sudo ENV_FILE=<PATH_TO_ENV_FILE> ./jupyterhub-<VERSION>-<HASH>.sh -b

Troubleshooting

I am receiving a `libcrypt.so.1` error post installation

Cause

Amazon Linux does not include libxcrypt-compat, which causes nginx services to error when starting.

Solution

If you receive a libcrypt.so.1 error post installation, install the libxcrypt-compat package on your JupyterHub server:

sudo yum install libxcrypt-compat

After installing the package, restart the nginx service:

sudo systemctl restart nginx.service

SystemD version too old or unavailable, using local spawner

Cause

This warning occurs when JupyterHub is installed on a Linux system running systemd < 245. In this case, JupyterHub defaults to using the local spawner instead of systemdSpawner, and resource management is not enabled.

Solution

JupyterHub requires systemd >= 245 or later for full resource management support.Verify your systemd version by running the following command:

systemctl --version

If necessary, update your operating system to a Linux distribution that provides systemd >= 245.

​Prerequisites

​Installing JupyterHub

​Troubleshooting

​I am receiving a libcrypt.so.1 error post installation

​SystemD version too old or unavailable, using local spawner

Prerequisites

Installing JupyterHub

Troubleshooting

I am receiving a `libcrypt.so.1` error post installation

SystemD version too old or unavailable, using local spawner