Installing on your own server#

Follow this guide if your cloud provider doesn’t have a direct tutorial, or you are setting this up on a bare metal server.

Warning

Do not install TLJH directly on your laptop or personal computer! It will most likely open up exploitable security holes when run directly on your personal computer.

Note

Running TLJH inside a docker container is not supported, since we depend on systemd. If you want to run TLJH locally for development, see Setting up Development Environment.

Goal#

By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want installed running on a server you have access to.

Pre-requisites#

  1. Some familiarity with the command line.

  2. A server running Ubuntu 18.04 where you have root access.

  3. At least 1GB of RAM on your server.

  4. Ability to ssh into the server & run commands from the prompt.

  5. An IP address where the server can be reached from the browsers of your target audience.

If you run into issues, look at the specific troubleshooting guide for custom server installations.

Step 1: Installing The Littlest JupyterHub#

  1. Using a terminal program, SSH into your server. This should give you a prompt where you can type commands.

  2. Make sure you have python3, python3-dev, curl and git installed.

    sudo apt install python3 python3-dev git curl

  3. Copy the text below, and paste it into the terminal. Replace <admin-user-name> with the name of the first admin user for this JupyterHub. Choose any name you like (don’t forget to remove the brackets!). This admin user can log in after the JupyterHub is set up, and can configure it to their needs. Remember to add your username!

    curl -L https://tljh.jupyter.org/bootstrap.py | sudo -E python3 - --admin <admin-user-name>

    Note

    See What does the installer do? if you want to understand exactly what the installer is doing. Customizing the Installer documents other options that can be passed to the installer.

  4. Press Enter to start the installation process. This will take 5-10 minutes, and will say Done! when the installation process is complete.

  5. Copy the Public IP of your server, and try accessing http://<public-ip> from your browser. If everything went well, this should give you a JupyterHub login page.

    JupyterHub log-in page

  6. Login using the admin user name you used in step 3. You can choose any password that you wish. Use a strong password & note it down somewhere, since this will be the password for the admin user account from now on.

  7. Congratulations, you have a running working JupyterHub!

Step 2: Adding more users#

Most administration & configuration of the JupyterHub can be done from the web UI directly. Let’s add a few users who can log in!

  1. Open the Control Panel by clicking the control panel button on the top right of your JupyterHub.

    Control panel button in notebook, top right

  2. In the control panel, open the Admin link in the top left.

    Admin button in control panel, top left

    This opens up the JupyterHub admin page, where you can add / delete users, start / stop peoples’ servers and see who is online.

  3. Click the Add Users button.

    Add Users button in the admin page

    A Add Users dialog box opens up.

  4. Type the names of users you want to add to this JupyterHub in the dialog box, one per line.

    Adding users with add users dialog

    You can tick the Admin checkbox if you want to give admin rights to all these users too.

  5. Click the Add Users button in the dialog box. Your users are now added to the JupyterHub! When they log in for the first time, they can set their password - and use it to log in again in the future.

Congratulations, you now have a multi user JupyterHub that you can add arbitrary users to!

Step 3: Install conda / pip packages for all users#

The User Environment is a conda environment that is shared by all users in the JupyterHub. Libraries installed in this environment are immediately available to all users. Admin users can install packages in this environment with sudo -E.

  1. Log in as an admin user and open a Terminal in your Jupyter Notebook.

    New Terminal button under New menu

  2. Install gdal from conda-forge.

    sudo -E conda install -c conda-forge gdal

    The sudo -E is very important!

  3. Install there with pip

    sudo -E pip install there

The packages gdal and there are now available to all users in JupyterHub. If a user already had a python notebook running, they have to restart their notebook’s kernel to make the new libraries available.

See Install conda, pip or apt packages for more information.

Step 4: Setup HTTPS#

Once you are ready to run your server for real, and have a domain, it’s a good idea to proceed directly to Enable HTTPS.