diff --git a/docs/source/config-basics.md b/docs/source/config-basics.md new file mode 100644 index 00000000..63bcf46e --- /dev/null +++ b/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) diff --git a/docs/source/index.rst b/docs/source/index.rst index a5d8b9ab..ff674b26 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -36,6 +36,7 @@ Contents * :doc:`quickstart` * :doc:`getting-started` +* :doc:`quickstart-docker` **Configuration Reference** diff --git a/docs/source/quickstart-docker.rst b/docs/source/quickstart-docker.rst new file mode 100644 index 00000000..b6d39a70 --- /dev/null +++ b/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 `_ +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 `_ +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/ diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md index 5a5dd39e..0be930a0 100644 --- a/docs/source/quickstart.md +++ b/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 - 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): +Before running the single-user notebook servers (which may be on the same +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. diff --git a/docs/source/user-guide.rst b/docs/source/user-guide.rst index 0985a974..b883445e 100644 --- a/docs/source/user-guide.rst +++ b/docs/source/user-guide.rst @@ -5,4 +5,6 @@ Installation Guide :maxdepth: 3 quickstart + quickstart-docker + config-basics getting-started