diff --git a/README.md b/README.md index fb5d9ae3..9635f9ab 100644 --- a/README.md +++ b/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) + +[![PyPI](https://img.shields.io/pypi/v/jupyterhub.svg)](https://pypi.python.org/pypi/jupyterhub) +[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest) [![Build Status](https://travis-ci.org/jupyterhub/jupyterhub.svg?branch=master)](https://travis-ci.org/jupyterhub/jupyterhub) [![Circle CI](https://circleci.com/gh/jupyterhub/jupyterhub.svg?style=shield&circle-token=b5b65862eb2617b9a8d39e79340b0a6b816da8cc)](https://circleci.com/gh/jupyterhub/jupyterhub) -[![codecov.io](https://codecov.io/github/jupyterhub/jupyterhub/coverage.svg?branch=master)](https://codecov.io/github/jupyterhub/jupyterhub?branch=master) -" -[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest) -" -[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter) +[![codecov.io](https://codecov.io/github/jupyterhub/jupyterhub/coverage.svg?branch=master)](https://codecov.io/github/jupyterhub/jupyterhub?branch=master) +[![Google Group](https://img.shields.io/badge/google-group-blue.svg)](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)** \ No newline at end of file