Repository files navigation

Technical Overview |Installation |Configuration |Docker |Contributing |License |Help and Resources

WithJupyterHub you can create amulti-user Hub that spawns, manages, and proxies multiple instances of thesingle-userJupyter notebookserver.

Project Jupyter created JupyterHub to support manyusers. The Hub can offer notebook servers to a class of students, a corporatedata science workgroup, a scientific research project, or a high-performancecomputing group.

Three main actors make up JupyterHub:

• multi-userHub (tornado process)
• configurable httpproxy (node-http-proxy)
• multiplesingle-user Jupyter notebook servers (Python/Jupyter/tornado)

Basic principles for operation are:

• Hub launches a proxy.
• The Proxy forwards all requests to Hub by default.
• Hub handles login and spawns single-user servers on demand.
• Hub configures proxy to forward URL prefixes to the single-user notebookservers.

JupyterHub also provides aREST APIfor administration of the Hub and its users.

• A Linux/Unix based system

• Python 3.8 or greater

• nodejs/npm

  • If you are usingconda, the nodejs and npm dependencies will be installed foryou by conda.

  • If you are usingpip, install a recent version (at least 12.0) ofnodejs/npm.

• If using the default PAM Authenticator, apluggable authentication module (PAM).

• TLS certificate and key for HTTPS communication

• Domain name

To install JupyterHub along with its dependencies including nodejs/npm:

conda install -c conda-forge jupyterhub

If you plan to run notebook servers locally, install JupyterLab or Jupyter notebook:

conda install jupyterlabconda install notebook

JupyterHub can be installed withpip, and the proxy withnpm:

npm install -g configurable-http-proxypython3 -m pip install jupyterhub

If you plan to run notebook servers locally, you will need to installJupyterLab or Jupyter notebook:

python3 -m pip install --upgrade jupyterlabpython3 -m pip install --upgrade notebook

To start the Hub server, run the command:

jupyterhub

Visithttp://localhost:8000 in your browser, and sign in with your system username and password.

Note: To allow multiple users to sign in to the server, you will need torun thejupyterhub command as aprivileged user, such as root.Thewikidescribes how to run the server as aless privileged user, which requiresmore configuration of the system.

TheGetting Started section of thedocumentation explains the common steps in setting up JupyterHub.

TheJupyterHub tutorialprovides an in-depth video and sample configurations of JupyterHub.

To generate a default config file with settings and descriptions:

jupyterhub --generate-config

To start the Hub on a specific url and port10.0.1.2:443 withhttps:

jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert

A starterdocker image for JupyterHubgives a baseline deployment of JupyterHub using Docker.

Important: Thisquay.io/jupyterhub/jupyterhub image contains only the Hub itself,with no configuration. In general, one needs to make a derivative image, withat least ajupyterhub_config.py setting up an Authenticator and/or a Spawner.To run the single-user servers, which may be on the same system as the Hub ornot, Jupyter Notebook version 4 or greater must be installed.

The JupyterHub docker image can be started with the following command:

docker run -p 8000:8000 -d --name jupyterhub quay.io/jupyterhub/jupyterhub jupyterhub

This command will create a container namedjupyterhub that you canstop and resume withdocker stop/start.

The Hub service will be listening on all interfaces at port 8000, which makesthis a good choice fortesting 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 dockerconfiguration or by using an ssl enabled proxy.

Mounting volumes willallow you tostore data outside the docker image (host system) so it will be persistent, even when you starta new image.

The commanddocker exec -it jupyterhub bash will spawn a root shell in your dockercontainer. You canuse the root shell to create system users in the container.These accounts will be used for authentication in JupyterHub's default configuration.

If you would like to contribute to the project, please read ourcontributor documentationand theCONTRIBUTING.md. TheCONTRIBUTING.md fileexplains how to set up a development installation, how to run the test suite,and how to contribute to documentation.

For a high-level view of the vision and next directions of the project, see theJupyterHub community roadmap.

JupyterHub is supported on Linux/Unix based systems.

JupyterHub officiallydoes not support Windows. You may be able to useJupyterHub on Windows if you use a Spawner and Authenticator that work onWindows, but the JupyterHub defaults will not. Bugs reported on Windows will notbe accepted, and the test suite will not run on Windows. Small patches that fixminor Windows compatibility issues (such as basic installation)may be accepted,however. For Windows-based systems, we would recommend running JupyterHub in adocker container or Linux VM.

Additional Reference: Tornado's documentation on Windows platform support

We use a shared copyright model that enables all contributors to maintain thecopyright on their contributions.

All code is licensed under the terms of therevised BSD license.

We encourage you to ask questions and share ideas on theJupyter community forum.You can also talk with us on our JupyterHubGitter channel.

• Reporting Issues
• JupyterHub tutorial
• Documentation for JupyterHub
• Documentation for JupyterHub's REST API
• Documentation for Project Jupyter
• Project Jupyter website
• Project Jupyter community

JupyterHub follows the JupyterCommunity Guides.

Technical Overview |Installation |Configuration |Docker |Contributing |License |Help and Resources