Quickstart - Installation¶
Before installing JupyterHub, you will need:
Python 3.3 or greater
Install nodejs/npm, using your operating system’s package manager. For example, install on Linux (Debian/Ubuntu) using:
sudo apt-get install npm nodejs-legacy
nodejs-legacypackage installs the
nodeexecutable and is currently required for npm to work on Debian/Ubuntu.)
TLS certificate and key for HTTPS communication
Before running the single-user notebook servers (which may be on the same system as the Hub or not):
- Jupyter Notebook version 4 or greater
JupyterHub can be installed with
conda and the proxy with
python3 -m pip install jupyterhub npm install -g configurable-http-proxy
conda (one command installs jupyterhub and proxy):
conda install -c conda-forge jupyterhub
To test your installation:
jupyterhub -h configurable-http-proxy -h
If you plan to run notebook servers locally, you will need also to install Jupyter notebook:
python3 -m pip install notebook
conda install notebook
Start the Hub server¶
To start the Hub server, run the command:
https://localhost:8000 in your browser, and sign in with your unix
To allow multiple users to sign into the Hub server, you must start
jupyterhub as a privileged user, such as root:
The wiki describes how to run the server as a less privileged user, which requires additional configuration of the system.
The getting started document contains detailed information abouts configuring a JupyterHub deployment.
Generate a default configuration file¶
Generate a default config file:
Customize the configuration, authentication, and process spawning¶
Spawn the server on
10.0.1.2:443 with https:
jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
The authentication and process spawning mechanisms can be replaced, which should allow plugging into a variety of authentication or process control environments. Some examples, meant as illustration and testing of this concept, are:
Alternate Installation using Docker¶
A ready to go docker image for JupyterHub gives a straightforward deployment of JupyterHub.
jupyterhub/jupyterhub docker image is only an image for running
the Hub service itself. It does not provide the other Jupyter components, such
as Notebook installation, which are needed by the single-user servers.
To run the single-user servers, which may be on the same system as the Hub or
not, Jupyter Notebook version 4 or greater must be installed.
Starting JupyterHub with docker¶
The JupyterHub docker image can be started with the following command:
docker run -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
This command will create a container named
jupyterhub that you can
stop and resume with
The Hub service will be listening on all interfaces at port 8000, which makes this a good choice for testing JupyterHub on your desktop or laptop.
If you want to run docker on a computer that has a public IP then you should (as in MUST) secure it with ssl by adding ssl options to your docker configuration or using a ssl enabled proxy.
Mounting volumes will allow you to store data outside the docker image (host system) so it will be persistent, even when you start a new image.
docker exec -it jupyterhub bash will spawn a root shell in your
docker container. You can use the root shell to create system users in the container.
These accounts will be used for authentication in JupyterHub’s default