mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-18 07:23:00 +00:00
Merge pull request #958 from willingc/add-badges
Edit README content and update formatting
This commit is contained in:
Min RK
199
README.md
199
README.md
@@ -1,82 +1,71 @@
|
||||
**[Technical overview](#technical-overview)** |
|
||||
**[Prerequisites](#prerequisites)** |
|
||||
**[Technical Overview](#technical-overview)** |
|
||||
**[Installation](#installation)** |
|
||||
**[Running the Hub Server](#running-the-hub-server)** |
|
||||
**[Configuration](#configuration)** |
|
||||
**[Docker](#docker)** |
|
||||
**[Contributing](#contributing)** |
|
||||
**[License](#license)** |
|
||||
**[Getting help](#getting-help)**
|
||||
**[Help and Resources](#help-and-resources)**
|
||||
|
||||
|
||||
# [JupyterHub](https://github.com/jupyterhub/jupyterhub)
|
||||
|
||||
|
||||
[](https://pypi.python.org/pypi/jupyterhub)
|
||||
[](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
|
||||
[](https://travis-ci.org/jupyterhub/jupyterhub)
|
||||
[](https://circleci.com/gh/jupyterhub/jupyterhub)
|
||||
[](https://codecov.io/github/jupyterhub/jupyterhub?branch=master)
|
||||
"
|
||||
[](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
|
||||
"
|
||||
[](https://groups.google.com/forum/#!forum/jupyter)
|
||||
[](https://groups.google.com/forum/#!forum/jupyter)
|
||||
|
||||
With [JupyterHub](https://jupyterhub.readthedocs.io) you can create a
|
||||
**multi-user Hub** which spawns, manages, and proxies multiple instances of the
|
||||
single-user [Jupyter notebook *(IPython notebook)* ](https://jupyter-notebook.readthedocs.io) server.
|
||||
single-user [Jupyter notebook (IPython notebook)](https://jupyter-notebook.readthedocs.io)
|
||||
server.
|
||||
|
||||
JupyterHub provides **single-user notebook servers to many users**. For example,
|
||||
JupyterHub could serve notebooks to a class of students, a corporate
|
||||
workgroup, or a science research group.
|
||||
|
||||
by [Project Jupyter](https://jupyter.org)
|
||||
|
||||
----
|
||||
[Project Jupyter](https://jupyter.org) created JupyterHub to support many
|
||||
users. The Hub can offer notebook servers to a class of students, a corporate
|
||||
data science workgroup, a scientific research project, or a high performance
|
||||
computing group.
|
||||
|
||||
## Technical overview
|
||||
|
||||
Three main actors make up JupyterHub:
|
||||
|
||||
- multi-user **Hub** (tornado process)
|
||||
- configurable http **proxy** (node-http-proxy)
|
||||
- multiple **single-user Jupyter notebook servers** (Python/IPython/tornado)
|
||||
|
||||
JupyterHub's basic principles for operation are:
|
||||
Basic principles for operation are:
|
||||
|
||||
- Hub spawns a 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 the single-user servers
|
||||
- Hub spawns a 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 the single-user notebook
|
||||
servers.
|
||||
|
||||
JupyterHub also provides a
|
||||
[REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
|
||||
for administration of the Hub and users.
|
||||
for administration of the Hub and its users.
|
||||
|
||||
----
|
||||
## Installation
|
||||
|
||||
## Prerequisites
|
||||
Before installing JupyterHub, you need:
|
||||
###Check prerequisites
|
||||
|
||||
- [Python](https://www.python.org/downloads/) 3.3 or greater
|
||||
|
||||
An understanding of using [`pip`](https://pip.pypa.io/en/stable/) for installing
|
||||
Python packages is recommended.
|
||||
|
||||
- [nodejs/npm](https://www.npmjs.com/)
|
||||
|
||||
[Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node), which is available from your
|
||||
package manager. For example, install on Linux (Debian/Ubuntu) using:
|
||||
- [nodejs/npm](https://www.npmjs.com/) Install a recent version of
|
||||
[nodejs/npm](https://docs.npmjs.com/getting-started/installing-node)
|
||||
For example, install it on Linux (Debian/Ubuntu) using:
|
||||
|
||||
sudo apt-get install npm nodejs-legacy
|
||||
|
||||
(The `nodejs-legacy` package installs the `node` executable and is currently
|
||||
required for npm to work on Debian/Ubuntu.)
|
||||
The `nodejs-legacy` package installs the `node` executable and is currently
|
||||
required for npm to work on Debian/Ubuntu.
|
||||
|
||||
- TLS certificate and key for HTTPS communication
|
||||
|
||||
- Domain name
|
||||
|
||||
Before running the single-user notebook servers (which may be on the same system as the Hub or not):
|
||||
### Install packages
|
||||
|
||||
- [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html) version 4 or greater
|
||||
|
||||
## Installation
|
||||
JupyterHub can be installed with `pip`, and the proxy with `npm`:
|
||||
|
||||
```bash
|
||||
@@ -85,84 +74,107 @@ pip3 install jupyterhub
|
||||
```
|
||||
|
||||
If you plan to run notebook servers locally, you will need to install the
|
||||
Jupyter notebook:
|
||||
[Jupyter notebook](https://jupyter.readthedocs.io/en/latest/install.html)
|
||||
package:
|
||||
|
||||
pip3 install --upgrade notebook
|
||||
|
||||
## Running the Hub server
|
||||
### Run the Hub server
|
||||
|
||||
To start the Hub server, run the command:
|
||||
|
||||
jupyterhub
|
||||
|
||||
Visit `https://localhost:8000` in your browser, and sign in with your unix credentials.
|
||||
Visit `https://localhost:8000` in your browser, and sign in with your unix
|
||||
PAM credentials.
|
||||
|
||||
To allow multiple users to sign into the server, you will need to
|
||||
*Note*: To allow multiple users 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/jupyterhub/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.
|
||||
|
||||
----
|
||||
describes how to run the server as a *less privileged user*, which requires
|
||||
more configuration of the system.
|
||||
|
||||
## Configuration
|
||||
The [getting started document](docs/source/getting-started.md) contains the
|
||||
basics of configuring a JupyterHub deployment.
|
||||
|
||||
The JupyterHub **tutorial** provides a video and documentation that explains and illustrates the fundamental steps for installation and configuration. [Repo](https://github.com/jupyterhub/jupyterhub-tutorial)
|
||||
| [Tutorial documentation](http://jupyterhub-tutorial.readthedocs.io/en/latest/)
|
||||
The [Getting Started](docs/source/getting-started.md) section of the
|
||||
documentation explains the common steps in setting up JupyterHub.
|
||||
|
||||
#### Generate a default configuration file
|
||||
Generate a default config file:
|
||||
The [**JupyterHub tutorial**](https://github.com/jupyterhub/jupyterhub-tutorial)
|
||||
provides an in-depth video and sample configurations of JupyterHub.
|
||||
|
||||
### Create a configuration file
|
||||
|
||||
To generate a default config file with settings and descriptions:
|
||||
|
||||
jupyterhub --generate-config
|
||||
|
||||
#### Customize the configuration, authentication, and process spawning
|
||||
Spawn the server on ``10.0.1.2:443`` with **https**:
|
||||
### Start the Hub
|
||||
|
||||
To start the Hub on a specific url and port ``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:
|
||||
### Authenticators
|
||||
|
||||
- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator)
|
||||
- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner)
|
||||
| Authenticator | Description |
|
||||
| -------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| PAMAuthenticator | Default, built-in authenticator |
|
||||
| [OAuthenticator](https://github.com/jupyterhub/oauthenticator) | OAuth + JupyterHub Authenticator = OAuthenticator |
|
||||
| [ldapauthenticator](https://github.com/jupyterhub/ldapauthenticator) | Simple LDAP Authenticator Plugin for JupyterHub |
|
||||
|
||||
----
|
||||
### Spawners
|
||||
|
||||
| Spawner | Description |
|
||||
| -------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| LocalProcessSpawner | Default, built-in spawner starts single-user servers as local processes |
|
||||
| [dockerspawner](https://github.com/jupyterhub/dockerspawner) | Spawn single-user servers in Docker containers |
|
||||
| [kubespawner](https://github.com/jupyterhub/kubespawner) | Kubernetes spawner for JupyterHub |
|
||||
| [sudospawner](https://github.com/jupyterhub/sudospawner) | Spawn single-user servers without being root |
|
||||
| [systemdspawner](https://github.com/jupyterhub/systemdspawner) | Spawn single-user notebook servers using systemd |
|
||||
| [batchspawner](https://github.com/jupyterhub/batchspawner) | Designed for clusters using batch scheduling software |
|
||||
| [wrapspawner](https://github.com/jupyterhub/wrapspawner) | WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners |
|
||||
|
||||
## Docker
|
||||
A starter [docker image for JupyterHub](https://hub.docker.com/r/jupyterhub/jupyterhub/) gives a baseline deployment of JupyterHub.
|
||||
|
||||
**Important:** This `jupyterhub/jupyterhub` image contains only the Hub itself, with no configuration. In general, one needs
|
||||
to make a derivative image, with at least a `jupyterhub_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 or not, Jupyter Notebook version 4 or greater must be installed.
|
||||
A starter [**docker image for JupyterHub**](https://hub.docker.com/r/jupyterhub/jupyterhub/)
|
||||
gives a baseline deployment of JupyterHub using Docker.
|
||||
|
||||
**Important:** This `jupyterhub/jupyterhub` image contains only the Hub itself,
|
||||
with no configuration. In general, one needs to make a derivative image, with
|
||||
at least a `jupyterhub_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 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 `docker stop/start`.
|
||||
This command will create a container named `jupyterhub` that you can
|
||||
**stop and resume** with `docker stop/start`.
|
||||
|
||||
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**.
|
||||
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.
|
||||
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 by using a ssl enabled proxy.
|
||||
|
||||
[Mounting volumes](https://docs.docker.com/engine/userguide/containers/dockervolumes/) will
|
||||
allow you to **store data outside the docker image (host system) so it will be persistent**, even when you start
|
||||
a new image.
|
||||
|
||||
The command `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 configuration.
|
||||
|
||||
----
|
||||
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 configuration.
|
||||
|
||||
## Contributing
|
||||
If you would like to contribute to the project, please read our [contributor documentation](http://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html) and the [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
For a **development install**, clone the [repository](https://github.com/jupyterhub/jupyterhub) and then install from source:
|
||||
If you would like to contribute to the project, please read our
|
||||
[contributor documentation](http://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html)
|
||||
and the [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
For a **development install**, clone the [repository](https://github.com/jupyterhub/jupyterhub)
|
||||
and then install from source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jupyterhub/jupyterhub
|
||||
@@ -170,41 +182,54 @@ cd jupyterhub
|
||||
pip3 install -r dev-requirements.txt -e .
|
||||
```
|
||||
|
||||
If the `pip3 install` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional JavaScript dependencies:
|
||||
If the `pip3 install` command fails and complains about `lessc` being
|
||||
unavailable, you may need to explicitly install some additional JavaScript
|
||||
dependencies:
|
||||
|
||||
npm install
|
||||
|
||||
This will fetch client-side JavaScript dependencies necessary to compile CSS.
|
||||
|
||||
You may also need to manually update JavaScript and CSS after some development updates, with:
|
||||
You may also need to manually update JavaScript and CSS after some development
|
||||
updates, with:
|
||||
|
||||
```bash
|
||||
python3 setup.py js # fetch updated client-side js
|
||||
python3 setup.py css # recompile CSS from LESS sources
|
||||
```
|
||||
|
||||
We use [pytest](http://doc.pytest.org/en/latest/) for testing. To run tests:
|
||||
We use [pytest](http://doc.pytest.org/en/latest/) for **running tests**:
|
||||
|
||||
```bash
|
||||
pytest jupyterhub/tests
|
||||
```
|
||||
|
||||
----
|
||||
## License
|
||||
|
||||
We use a shared copyright model that enables all contributors to maintain the
|
||||
copyright on their contributions.
|
||||
|
||||
All code is licensed under the terms of the revised BSD license.
|
||||
|
||||
## Getting help
|
||||
We encourage you to ask questions on the [mailing list](https://groups.google.com/forum/#!forum/jupyter),
|
||||
and you may participate in development discussions or get live help on [Gitter](https://gitter.im/jupyterhub/jupyterhub).
|
||||
## Help and resources
|
||||
|
||||
We encourage you to ask questions on the [Jupyter mailing list](https://groups.google.com/forum/#!forum/jupyter).
|
||||
To participate in development discussions or get help, talk with us on
|
||||
our JupyterHub [Gitter](https://gitter.im/jupyterhub/jupyterhub) channel.
|
||||
|
||||
## Resources
|
||||
- [Reporting Issues](https://github.com/jupyterhub/jupyterhub/issues)
|
||||
- JupyterHub tutorial | [Repo](https://github.com/jupyterhub/jupyterhub-tutorial)
|
||||
| [Tutorial documentation](http://jupyterhub-tutorial.readthedocs.io/en/latest/)
|
||||
- [JupyterHub tutorial](https://github.com/jupyterhub/jupyterhub-tutorial)
|
||||
- [Documentation for JupyterHub](http://jupyterhub.readthedocs.io/en/latest/) | [PDF (latest)](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf) | [PDF (stable)](https://media.readthedocs.org/pdf/jupyterhub/stable/jupyterhub.pdf)
|
||||
- [Documentation for JupyterHub's REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
|
||||
- [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) | [PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)
|
||||
- [Project Jupyter website](https://jupyter.org)
|
||||
|
||||
---
|
||||
|
||||
**[Technical Overview](#technical-overview)** |
|
||||
**[Installation](#installation)** |
|
||||
**[Configuration](#configuration)** |
|
||||
**[Docker](#docker)** |
|
||||
**[Contributing](#contributing)** |
|
||||
**[License](#license)** |
|
||||
**[Help and Resources](#help-and-resources)**
|
||||
Reference in New Issue
Block a user