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

1. Download and unpack the installer

   1. Log in to your Linux server as a root user.

   2. Download the installer by running the following command:

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

   3. Unpack the installer tarball:

      Example

      tar -xvf jupyterhub-#.#.#-<hash>.tar
      

2. Create a CA certificate

   If necessary, create a CA certificate and make self-signed certificates off of that using the DIY-SSL-CA package:

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

   Make note of the the CERT, KEY, and CA_CERT values.

3. 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.

4. 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:

   ANACONDA_SERVER=
   CLIENT_SECRET=
   CERT=
   KEY=
   CA_CERT=
   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.

5. Run the installer

   Run the installer with the following command:

   sudo ENV_FILE=/home/<user>/.env ./jupyterhub-#.#.#-<hash>.sh -b
   

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

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

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