hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-17 23:13:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #865 from willingc/doc-tidbits

Browse Source 
Add documentation prior to 0.7 beta
This commit is contained in:
Min RK
2016-11-12 11:40:53 -08:00
committed by GitHub
parent 0ffd53424d dc092186f0
commit 93ac343493
3 changed files with 90 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/changelog.md
View File

@@ -20,7 +20,7 @@ command line for details.
### Changed
- Always install with setuptools but not eggs (effectively require
`pip install .` [\#722](https://github.com/jupyterhub/jupyterhub/pull/722)
`pip install .`) [\#722](https://github.com/jupyterhub/jupyterhub/pull/722)
- Updated formatting of changelog. [\#711](https://github.com/jupyterhub/jupyterhub/pull/711)
### Fixed
@@ -116,4 +116,4 @@ First preview release
[0.4.1]: https://github.com/jupyterhub/jupyterhub/compare/0.4.0...0.4.1
[0.4.0]: https://github.com/jupyterhub/jupyterhub/compare/0.3.0...0.4.0
[0.3]: https://github.com/jupyterhub/jupyterhub/compare/0.2.0...0.3.0
[0.2]: https://github.com/jupyterhub/jupyterhub/compare/0.1.0...0.2.0
[0.2]: https://github.com/jupyterhub/jupyterhub/compare/0.1.0...0.2.0

126
docs/source/getting-started.md
View File

@@ -1,5 +1,17 @@
# Getting started with JupyterHub
This section contains getting started information on the following topics:
- [Technical Overview](getting-started.html#technical-overview)
- [Installation](getting-started.html#installation)
- [Configuration](getting-started.html#configuration)
- [Networking](getting-started.html#networking)
- [Security](getting-started.html#security)
- [Authentication and users](getting-started.html#authentication-and-users)
- [Spawners and single-user notebook servers](getting-started.html#spawners-and-single-user-notebook-servers)
- [External Services](getting-started.html#external-services)
## Technical Overview
JupyterHub is a set of processes that together provide a single user Jupyter
@@ -8,9 +20,9 @@ Notebook server for each person in a group.
### Three subsystems
Three major subsystems run by the `jupyterhub` command line program:
- **Single User Server**: a dedicated, single-user, Jupyter Notebook server is
- **Single-User Notebook Server**: a dedicated, single-user, Jupyter Notebook server is
started for each user on the system when the user logs in. The object that
starts these servers is called a Spawner.
starts these servers is called a **Spawner**.
- **Proxy**: the public facing part of JupyterHub that uses a dynamic proxy
to route HTTP requests to the Hub and Single User Notebook Servers.
- **Hub**: manages user accounts, authentication, and coordinates Single User
@@ -37,14 +49,14 @@ Basic principles of operation:
* Hub handles login, and spawns single-user servers on demand
* Hub configures proxy to forward url prefixes to single-user servers
Different [authenticators](authenticators.html) control access
Different **[authenticators](authenticators.html)** control access
to JupyterHub. The default one (PAM) uses the user accounts on the server where
JupyterHub is running. If you use this, you will need to create a user account
on the system for each user on your team. Using other authenticators, you can
allow users to sign in with e.g. a GitHub account, or with any single-sign-on
system your organization has.
Next, [spawners](spawners.html) control how JupyterHub starts
Next, **[spawners](spawners.html)** control how JupyterHub starts
the individual notebook server for each user. The default spawner will
start a notebook server on the same machine running under their system username.
The other main option is to start each server in a separate container, often
@@ -53,21 +65,25 @@ using Docker.
### Default behavior
**IMPORTANT: You should not run JupyterHub without SSL encryption on a public network.**
See [Security documentation](#security) for how to configure JupyterHub to use SSL,
or put it behind SSL termination in another proxy server, such as nginx.
---
*Deprecation note:* Removed `--no-ssl` in version 0.7.
**Deprecation note:** Removed `--no-ssl` in version 0.7.
JupyterHub versions 0.5 and 0.6 require extra confirmation via `--no-ssl` to
allow running without SSL. `--no-ssl` is not needed anymore in version 0.7.
allow running without SSL using the command `jupyterhub --no-ssl`. The
`--no-ssl` command line option is not needed anymore in version 0.7.
---
To start JupyterHub in its default configuration, type the following at the command line:
```bash
sudo jupyterhub
```
The default Authenticator that ships with JupyterHub authenticates users
with their system name and password (via [PAM][]).
@@ -79,9 +95,8 @@ These servers listen on localhost, and start in the given user's home directory.
By default, the **Proxy** listens on all public interfaces on port 8000.
Thus you can reach JupyterHub through either:
http://localhost:8000
or any other public IP or domain pointing to your system.
- `http://localhost:8000`
- or any other public IP or domain pointing to your system.
In their default configuration, the other services, the **Hub** and **Single-User Servers**,
all communicate with each other on localhost only.
@@ -94,7 +109,7 @@ By default, starting JupyterHub will write two files to disk in the current work
- `jupyterhub_cookie_secret` is the encryption key used for securing cookies.
This file needs to persist in order for restarting the Hub server to avoid invalidating cookies.
Conversely, deleting this file and restarting the server effectively invalidates all login cookies.
The cookie secret file is discussed in the [Cookie Secret documentation](#Cookie secret).
The cookie secret file is discussed in the [Cookie Secret documentation](#cookie-secret).
The location of these files can be specified via configuration, discussed below.
@@ -134,12 +149,16 @@ By default, JupyterHub will look for a configuration file (which may not be crea
named `jupyterhub_config.py` in the current working directory.
You can create an empty configuration file with:
jupyterhub --generate-config
```bash
jupyterhub --generate-config
```
This empty configuration file has descriptions of all configuration variables and their default
values. You can load a specific config file with:
jupyterhub -f /path/to/jupyterhub_config.py
```bash
jupyterhub -f /path/to/jupyterhub_config.py
```
See also: [general docs](http://ipython.org/ipython-doc/dev/development/config.html)
on the config system Jupyter uses.
@@ -147,20 +166,26 @@ on the config system Jupyter uses.
### Command-line arguments
Type the following for brief information about the command-line arguments:
jupyterhub -h
```bash
jupyterhub -h
```
or:
jupyterhub --help-all
```bash
jupyterhub --help-all
```
for the full command line help.
All configurable options are technically configurable on the command-line,
even if some are really inconvenient to type. Just replace the desired option,
c.Class.trait, with --Class.trait. For example, to configure
c.Spawner.notebook_dir = '~/assignments' from the command-line:
`c.Class.trait`, with `--Class.trait`. For example, to configure the
`c.Spawner.notebook_dir` trait from the command-line:
jupyterhub --Spawner.notebook_dir='~/assignments'
```bash
jupyterhub --Spawner.notebook_dir='~/assignments'
```
## Networking
@@ -173,7 +198,9 @@ instead, use of `'0.0.0.0'` is preferred.
Changing the IP address and port can be done with the following command line
arguments:
jupyterhub --ip=192.168.1.2 --port=443
```bash
jupyterhub --ip=192.168.1.2 --port=443
```
Or by placing the following lines in a configuration file:
@@ -217,24 +244,25 @@ c.JupyterHub.hub_port = 54321
## Security
**IMPORTANT:** In its default configuration, JupyterHub requires SSL encryption (HTTPS) to run.
**You should not run JupyterHub without SSL encryption on a public network.**
**IMPORTANT: You should not run JupyterHub without SSL encryption on a public network.**
---
*Deprecation note:* Removed `--no-ssl` in version 0.7.
**Deprecation note:** Removed `--no-ssl` in version 0.7.
JupyterHub versions 0.5 and 0.6 require extra confirmation via `--no-ssl` to
allow running without SSL. `--no-ssl` is not needed anymore in version 0.7.
allow running without SSL using the command `jupyterhub --no-ssl`. The
`--no-ssl` command line option is not needed anymore in version 0.7.
---
Security is the most important aspect of configuring Jupyter. There are three main aspects of the
Security is the most important aspect of configuring Jupyter. There are four main aspects of the
security configuration:
1. SSL encryption (to enable HTTPS)
2. Cookie secret (a key for encrypting browser cookies)
3. Proxy authentication token (used for the Hub and other services to authenticate to the Proxy)
4. Periodic security audits
### SSL encryption
@@ -248,12 +276,22 @@ c.JupyterHub.ssl_key = '/path/to/my.key'
c.JupyterHub.ssl_cert = '/path/to/my.cert'
```
It is also possible to use letsencrypt (https://letsencrypt.org/) to obtain a free, trusted SSL
certificate. If you run letsencrypt using the default options, the needed configuration is (replace `your.domain.com` by your fully qualified domain name):
It is also possible to use letsencrypt (https://letsencrypt.org/) to obtain
a free, trusted SSL certificate. If you run letsencrypt using the default
options, the needed configuration is (replace `mydomain.tld` by your fully
qualified domain name):
```python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/your.domain.com/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/your.domain.com/fullchain.pem'
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'
```
If the fully qualified domain name (FQDN) is `example.com`, the following
would be the needed configuration:
```python
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'
```
Some cert files also contain the key, in which case only the cert is needed. It is important that
@@ -302,7 +340,8 @@ For security reasons, this environment variable should only be visible to the Hu
If you set it dynamically as above, all users will be logged out each time the
Hub starts.
You can also set the secret in the configuration file itself as a binary string:
You can also set the cookie secret in the configuration file itself,`jupyterhub_config.py`,
as a binary string:
```python
c.JupyterHub.cookie_secret = bytes.fromhex('VERY LONG SECRET HEX STRING')
@@ -310,7 +349,11 @@ c.JupyterHub.cookie_secret = bytes.fromhex('VERY LONG SECRET HEX STRING')
### Proxy authentication token
The Hub authenticates its requests to the Proxy using a secret token that the Hub and Proxy agree upon. The value of this string should be a random string (for example, generated by `openssl rand -hex 32`). You can pass this value to the Hub and Proxy using either the `CONFIGPROXY_AUTH_TOKEN` environment variable:
The Hub authenticates its requests to the Proxy using a secret token that
the Hub and Proxy agree upon. The value of this string should be a random
string (for example, generated by `openssl rand -hex 32`). You can pass
this value to the Hub and Proxy using either the `CONFIGPROXY_AUTH_TOKEN`
environment variable:
```bash
export CONFIGPROXY_AUTH_TOKEN=`openssl rand -hex 32`
@@ -318,7 +361,7 @@ export CONFIGPROXY_AUTH_TOKEN=`openssl rand -hex 32`
This environment variable needs to be visible to the Hub and Proxy.
Or you can set the value in the configuration file:
Or you can set the value in the configuration file, `jupyterhub_config.py`:
```python
c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
@@ -328,13 +371,15 @@ If you don't set the Proxy authentication token, the Hub will generate a random
means that any time you restart the Hub you **must also restart the Proxy**. If the proxy is a
subprocess of the Hub, this should happen automatically (this is the default configuration).
Another time you must set the Proxy authentication token yourself is if you want other services, such as [nbgrader](https://github.com/jupyter/nbgrader) to also be able to connect to the Proxy.
Another time you must set the Proxy authentication token yourself is if
you want other services, such as [nbgrader](https://github.com/jupyter/nbgrader)
to also be able to connect to the Proxy.
### Security audits
We recommend that you do periodic reviews of your deployment's security. It's
good practice to keep JupyterHub, configurable-http-proxy, and nodejs up to
date.
good practice to keep JupyterHub, configurable-http-proxy, and nodejs
versions up to date.
A handy website for testing your deployment is
[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html).
@@ -343,8 +388,9 @@ A handy website for testing your deployment is
## Authentication and users
The default Authenticator uses [PAM][] to authenticate system users with their username and password.
The default behavior of this Authenticator is to allow any user with an account and password on the system to login.
The default Authenticator uses [PAM][] to authenticate system users with
their username and password. The default behavior of this Authenticator
is to allow any user with an account and password on the system to login.
### Creating a whitelist of users
@@ -444,20 +490,20 @@ as the environment variable called `JPY_API_TOKEN`.
Currently there are two ways of registering that token with JupyterHub. The first one is to use
the `jupyterhub` command to generate a token for a specific hub user:
```
$ jupyterhub token <username>
```bash
jupyterhub token <username>
```
As of [version 0.6.0](./changelog.html), the preferred way of doing this is to first generate an API token:
```
$ openssl rand -hex 32
```bash
openssl rand -hex 32
```
and then write it to your JupyterHub configuration file (note that the **key** is the token while the **value** is the username):
```
```python
c.JupyterHub.api_tokens = {'token' : 'username'}
```

4
docs/source/index.rst
View File

@@ -28,8 +28,8 @@ JupyterHub's basic flow of operations includes:
- The Hub handles user login and spawns single-user servers on demand
- The Hub configures the proxy to forward URL prefixes to the single-user notebook servers
For convenient administration of the Hub, its users, and services, JupyterHub
also provides a
For convenient administration of the Hub, its users, and :doc:`services`
(added in version 7.0), JupyterHub also provides a
`REST API <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default>`_.