Merge pull request #865 from willingc/doc-tidbits

Add documentation prior to 0.7 beta

docs/source/changelog.md

@@ -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

docs/source/getting-started.md

@@ -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
+- `http://localhost:8000`
-
+- or any other public IP or domain pointing to your system.
-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:
 
+```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:
 
+```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:
 
+```bash
 jupyterhub -h
+```
 
 or:
 
+```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.Class.trait`, with `--Class.trait`. For example, to configure the
-c.Spawner.notebook_dir = '~/assignments' from the command-line:
+`c.Spawner.notebook_dir` trait from the command-line:
 
+```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:
 
+```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.
+**IMPORTANT: You should not run JupyterHub without SSL encryption on a public network.**
-**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
+It is also possible to use letsencrypt (https://letsencrypt.org/) to obtain
-certificate. If you run letsencrypt using the default options, the needed configuration is (replace `your.domain.com` by your fully qualified domain name):
+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_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
-c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/your.domain.com/fullchain.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
+good practice to keep JupyterHub, configurable-http-proxy, and nodejs 
-date.
+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 Authenticator uses [PAM][] to authenticate system users with
-The default behavior of this Authenticator is to allow any user with an account and password on the system to login.
+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:
 
-```
+```bash
-$ jupyterhub token <username>
+jupyterhub token <username>
 ```
 
 As of [version 0.6.0](./changelog.html), the preferred way of doing this is to first generate an API token:
 
-```
+```bash
-$ openssl rand -hex 32
+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'}
 ```
 

docs/source/index.rst

@@ -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
+For convenient administration of the Hub, its users, and :doc:`services`
-also provides a
+(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>`_.