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#
Some familiarity with the command line.
A server running Ubuntu 18.04 where you have root access.
At least 1GB of RAM on your server.
Ability to
ssh
into the server & run commands from the prompt.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#
Using a terminal program, SSH into your server. This should give you a prompt where you can type commands.
Make sure you have
python3
,python3-dev
,curl
andgit
installed.sudo apt install python3 python3-dev git curl
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.
Press
Enter
to start the installation process. This will take 5-10 minutes, and will sayDone!
when the installation process is complete.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.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.
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!
Open the Control Panel by clicking the control panel button on the top right of your JupyterHub.
In the control panel, open the Admin link in the top left.
This opens up the JupyterHub admin page, where you can add / delete users, start / stop peoples’ servers and see who is online.
Click the Add Users button.
A Add Users dialog box opens up.
Type the names of users you want to add to this JupyterHub in the dialog box, one per line.
You can tick the Admin checkbox if you want to give admin rights to all these users too.
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
.
Log in as an admin user and open a Terminal in your Jupyter Notebook.
Install gdal from conda-forge.
sudo -E conda install -c conda-forge gdal
The
sudo -E
is very important!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.