Break up installation document

docs/source/config-basics.md

@@ -0,0 +1,29 @@
+# Configuration Basics
+
+The [getting started document](docs/source/getting-started.md) contains
+detailed information abouts 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/)
+
+## Generate a default configuration file
+
+Generate a default config file:
+
+    jupyterhub --generate-config
+
+## Customize the configuration, authentication, and process spawning
+
+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, are:
+
+- 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)

docs/source/index.rst

@@ -36,6 +36,7 @@ Contents
 
 * :doc:`quickstart`
 * :doc:`getting-started`
+* :doc:`quickstart-docker`
 
 
 **Configuration Reference**

docs/source/quickstart-docker.rst

@@ -0,0 +1,44 @@
+# Installation with Docker
+
+.. important::
+
+   We highly recommend following the `Zero to JupyterHub`_ tutorial for
+   installing JupyterHub.
+
+A ready to go `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_
+gives a straightforward deployment of JupyterHub.
+
+.. note::
+
+    This ``jupyterhub/jupyterhub`` docker image is only an image for running
+    the Hub service itself. It does not provide the other Jupyter components,
+    such as Notebook installation, which are needed by the single-user servers.
+    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``.
+
+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.
+
+`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.
+
+.. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/

docs/source/quickstart.md

@@ -2,28 +2,28 @@
 
 ## Prerequisites
 
-**Before installing JupyterHub**, you will need a Linux/Unix based system:
+Before installing JupyterHub, you will need:
 
-- [Python](https://www.python.org/downloads/) 3.3 or greater. An understanding
+- a Linux/Unix based system
+- [Python](https://www.python.org/downloads/) 3.4 or greater. An understanding
   of using [`pip`](https://pip.pypa.io/en/stable/) or
   [`conda`](http://conda.pydata.org/docs/get-started.html) for
   installing Python packages is helpful.
-- [nodejs/npm](https://www.npmjs.com/) [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
+- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
   using your operating system's package manager. For example, install on Linux
-  (Debian/Ubuntu) using:
+  Debian/Ubuntu using:
 
   ```bash
   sudo apt-get install npm nodejs-legacy
   ```
 
-  (The `nodejs-legacy` package installs the `node` executable and is currently
+  The `nodejs-legacy` package installs the `node` executable and is currently
-  required for npm to work on Debian/Ubuntu.)
+  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
+Before running the single-user notebook servers (which may be on the same
-system as the Hub or not):
+system as the Hub or not), you will need:
 
 - [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html)
   version 4 or greater
@@ -37,17 +37,18 @@ JupyterHub can be installed with `pip` (and the proxy with `npm`) or `conda`:
 ```bash
 python3 -m pip install jupyterhub
 npm install -g configurable-http-proxy
-python3 -m pip install notebook # needed if running the notebook servers locally
+python3 -m pip install notebook  # needed if running the notebook servers locally
 ```
 
 **conda** (one command installs jupyterhub and proxy):
 
 ```bash
-conda install -c conda-forge jupyterhub
+conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
 conda install notebook  # needed if running the notebook servers locally
 ```
 
-To test your installation:
+Test your installation. If installed, these commands should return the packages'
+help contents:
 
 ```bash
 jupyterhub -h
@@ -65,7 +66,7 @@ jupyterhub
 Visit `https://localhost:8000` in your browser, and sign in with your unix
 credentials.
 
-To allow multiple users to sign into the Hub server, you must start
+To **allow multiple users to sign in** to the Hub server, you must start
 `jupyterhub` as a *privileged user*, such as root:
 
 ```bash
@@ -73,75 +74,5 @@ sudo jupyterhub
 ```
 
 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
+describes how to run the server as a *less privileged user*. This requires
 additional configuration of the system.
-
-----
-
-## Basic Configuration
-
-The [getting started document](docs/source/getting-started.md) contains
-detailed information abouts 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/)
-
-#### Generate a default configuration file
-
-Generate a default config file:
-
-    jupyterhub --generate-config
-
-#### Customize the configuration, authentication, and process spawning
-
-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, are:
-
-- 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)
-
-----
-
-## Alternate Installation using Docker
-
-A ready to go [docker image for JupyterHub](https://hub.docker.com/r/jupyterhub/jupyterhub/)
-gives a straightforward deployment of JupyterHub.
-
-*Note: This `jupyterhub/jupyterhub` docker image is only an image for running
-the Hub service itself. It does not provide the other Jupyter components, such
-as Notebook installation, which are needed by the single-user servers.
-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`.
-
-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.
-
-[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.

docs/source/user-guide.rst

@@ -5,4 +5,6 @@ Installation Guide
    :maxdepth: 3
 
    quickstart
+   quickstart-docker
+   config-basics
    getting-started