# JupyterHub: A multi-user server for Jupyter notebooks
Questions, comments? Visit our Google Group:
[](https://groups.google.com/forum/#!forum/jupyter)
JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
Three actors:
- multi-user Hub (tornado process)
- configurable http proxy (node-http-proxy)
- multiple single-user IPython notebook servers (Python/IPython/tornado)
Basic principles:
- Hub spawns proxy
- 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 single-user servers
## Dependencies
JupyterHub requires IPython >= 3.0 (current master) and Python >= 3.3.
You will need nodejs/npm, which you can get from your package manager:
sudo apt-get install npm nodejs-legacy
(The `nodejs-legacy` package installs the `node` executable,
which is required for npm to work on Debian/Ubuntu at this point)
Then install javascript dependencies:
sudo npm install -g configurable-http-proxy
### Optional
- Notes on `pip` command used in the below installation sections:
- `sudo` may be needed for `pip install`, depending on filesystem permissions.
- JupyterHub requires Python >= 3.3, so it may be required on some machines to use `pip3` instead
of `pip` (especially when you have both Python 2 and Python 3 installed on your machine).
If `pip3` is not found on your machine, you can get it by doing:
sudo apt-get install python3-pip
## Installation
As usual start with cloning the code:
git clone https://github.com/jupyter/jupyterhub.git
cd jupyterhub
Then you can install the Python package by doing:
pip3 install -r requirements.txt
pip3 install .
If the `pip3 install .` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional javascript dependencies:
npm install
If you plan to run notebook servers locally, you may also need to install the IPython notebook:
pip3 install "ipython[notebook]"
This will fetch client-side javascript dependencies and compile CSS,
and install these files to `sys.prefix`/share/jupyter, as well as
install any Python dependencies.
### Development install
For a development install:
pip3 install -r dev-requirements.txt -e .
In which case you may need to manually update javascript and css after some updates, with:
python3 setup.py js # fetch updated client-side js (changes rarely)
python3 setup.py css # recompile CSS from LESS sources
## Running the server
To start the server, run the command:
jupyterhub
and then visit `http://localhost:8000`, and sign in with your unix credentials.
If you want multiple users to be able to sign into the server, you will need to run the
`jupyterhub` command as a privileged user, such as root.
The [wiki](https://github.com/jupyter/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges) describes how to run the server
as a less privileged user, which requires more configuration of the system.
## Getting started
see the [getting started doc](docs/getting-started.md) for some of the basics of configuring your JupyterHub deployment.
### Some examples
generate a default config file:
jupyterhub --generate-config
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:
- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyter/oauthenticator)
- Spawning single-user servers with docker, using the [DockerSpawner](https://github.com/jupyter/dockerspawner)
# Getting help
We encourage you to ask questions on the mailing list:
[](https://groups.google.com/forum/#!forum/jupyter)
but you can participate in development discussions or get live help on Gitter:
[](https://gitter.im/jupyter/jupyterhub?utm_source=badge&utm_medium=badge)
Questions, comments? Visit our Google Group:
[](https://groups.google.com/forum/#!forum/jupyter)
JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
Three actors:
- multi-user Hub (tornado process)
- configurable http proxy (node-http-proxy)
- multiple single-user IPython notebook servers (Python/IPython/tornado)
Basic principles:
- Hub spawns proxy
- 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 single-user servers
## Dependencies
JupyterHub requires IPython >= 3.0 (current master) and Python >= 3.3.
You will need nodejs/npm, which you can get from your package manager:
sudo apt-get install npm nodejs-legacy
(The `nodejs-legacy` package installs the `node` executable,
which is required for npm to work on Debian/Ubuntu at this point)
Then install javascript dependencies:
sudo npm install -g configurable-http-proxy
### Optional
- Notes on `pip` command used in the below installation sections:
- `sudo` may be needed for `pip install`, depending on filesystem permissions.
- JupyterHub requires Python >= 3.3, so it may be required on some machines to use `pip3` instead
of `pip` (especially when you have both Python 2 and Python 3 installed on your machine).
If `pip3` is not found on your machine, you can get it by doing:
sudo apt-get install python3-pip
## Installation
As usual start with cloning the code:
git clone https://github.com/jupyter/jupyterhub.git
cd jupyterhub
Then you can install the Python package by doing:
pip3 install -r requirements.txt
pip3 install .
If the `pip3 install .` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional javascript dependencies:
npm install
If you plan to run notebook servers locally, you may also need to install the IPython notebook:
pip3 install "ipython[notebook]"
This will fetch client-side javascript dependencies and compile CSS,
and install these files to `sys.prefix`/share/jupyter, as well as
install any Python dependencies.
### Development install
For a development install:
pip3 install -r dev-requirements.txt -e .
In which case you may need to manually update javascript and css after some updates, with:
python3 setup.py js # fetch updated client-side js (changes rarely)
python3 setup.py css # recompile CSS from LESS sources
## Running the server
To start the server, run the command:
jupyterhub
and then visit `http://localhost:8000`, and sign in with your unix credentials.
If you want multiple users to be able to sign into the server, you will need to run the
`jupyterhub` command as a privileged user, such as root.
The [wiki](https://github.com/jupyter/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges) describes how to run the server
as a less privileged user, which requires more configuration of the system.
## Getting started
see the [getting started doc](docs/getting-started.md) for some of the basics of configuring your JupyterHub deployment.
### Some examples
generate a default config file:
jupyterhub --generate-config
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:
- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyter/oauthenticator)
- Spawning single-user servers with docker, using the [DockerSpawner](https://github.com/jupyter/dockerspawner)
# Getting help
We encourage you to ask questions on the mailing list:
[](https://groups.google.com/forum/#!forum/jupyter)
but you can participate in development discussions or get live help on Gitter:
[](https://gitter.im/jupyter/jupyterhub?utm_source=badge&utm_medium=badge)
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
jupyterhub-0.2.0.zip
(854.7 kB
view details)
jupyterhub-0.2.0.tar.gz
(801.8 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
jupyterhub-0.2.0-py3-none-any.whl
(848.2 kB
view details)
File details
Details for the file jupyterhub-0.2.0.zip.
File metadata
- Download URL: jupyterhub-0.2.0.zip
- Upload date:
- Size: 854.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
db19472929d893c9f58d497021f2a7cf9a6b6ce735372385ee9a9892e644e393
|
|
| MD5 |
267f886b83c4e3374957894f736674f4
|
|
| BLAKE2b-256 |
d7e8b7ec1326108b33a61e1143384b7ad43b8382a6d9c43e1e838607f3ddb006
|
File details
Details for the file jupyterhub-0.2.0.tar.gz.
File metadata
- Download URL: jupyterhub-0.2.0.tar.gz
- Upload date:
- Size: 801.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eac6a625aa23f0a74afe367ca4e10cd2cf829db766817577dc96ef33b6709dcc
|
|
| MD5 |
52c352ec927d798d1dbefad2818891e9
|
|
| BLAKE2b-256 |
3a97f27b5d8fe640f920fbe34809e80a8c3b89886568ae08642b121c70f6f401
|
File details
Details for the file jupyterhub-0.2.0-py3-none-any.whl.
File metadata
- Download URL: jupyterhub-0.2.0-py3-none-any.whl
- Upload date:
- Size: 848.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6d38ffe5ccf9c7f1c33e3d0fbdfa61c122b500fc800954bb55def2ee122c3e92
|
|
| MD5 |
992fa3d9e064a81e2648163bc1526d2b
|
|
| BLAKE2b-256 |
0e9bf1b130e860faa1f16c4639d6fd774ed1fe10ed960a5b7718b300460a59c9
|
