Skip to main content

​
Prerequisites

Before you begin, make sure you have the following:
  • An organization on Anaconda.com with a current subscription.
  • 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-<VERSION>-<HASH>.tar
2

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):
The self-signed certificates created by the DIY-SSL-CA package can reduce your time to first use of JupyterHub, but should be replaced with valid certificates from a trusted certificate authority as soon as possible. Do not use self-signed certificates in production environments!
# 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.
3

Create a service account

Create a dedicated service account for the JupyterHub services to use to authenticate to your organization members.
  1. Sign in to Anaconda.com.
  2. Navigate to your Organizations page.
  3. Select the organization you want to create a service account for.
  4. Under User Management, select Service Accounts.
  5. Click Add Account.
  6. Name for your service account JupyterHub.
  7. Click Save.
  8. Save the Client ID and Client Secret in a secure location.
4

Add your OAuth callback URL

Submit a request to add your OAuth callback URL to the JupyterHub service account. Complete the request form as follows:
  1. Enter your email address.
  2. Enter “JupyterHub OAuth callback URL” as the subject.
  3. In the description, provide your JupyterHub server’s fully qualified domain name.
    If you have modified your jupyterhub_config.py’s config class variable (c.AnacondaServerAuthenticator.oauth_callback_url), include the modified value in the description.
  4. Select All users as the user impact.
  5. Select Low as the priority.
  6. Select Package Security Manager (Cloud) as the product.
  7. Enter N/A as the product version.
  8. Select Production as the system type.
  9. Select Integration as the ticket type.
  10. Select Submit.
You will receive an email when your request is approved. You can continue with the installation process while you wait for the request to be approved, but users will not be able to log into the JupyterHub server until your request is approved.
5

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 environment variables to the .env file you just created, and populate them with the values you gathered in the previous steps:
# Replace <CLIENT_ID> with your service account client ID
# Replace <CLIENT_SECRET> with your service account client secret
# Replace <PATH_TO_CERT> with the path to your SSL/TLS certificate file
# Replace <PATH_TO_KEY> with the path to your SSL/TLS key file
# Replace <PATH_TO_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.
CLIENT_ID= <CLIENT_ID>
CLIENT_SECRET= <CLIENT_SECRET>
CERT= <PATH_TO_CERT>
KEY= <PATH_TO_KEY>
CA_CERT= <PATH_TO_CA_CERT> 
JUPYTERHUB_SPAWNER_TYPE=<SPAWNER_TYPE>
REPO_CHANNELS= ("org_chan1" "org_chan2" "defaults")
The REPO_CHANNELS variable is a list of that the JupyterHub services will use to install when users build new in Jupyter. The installer configures conda to respect the priority of the channels in the order they are listed in the environment file.
6

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

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

​
SystemD version too old or unavailable, using local spawner

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