mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
Break up installation document
This commit is contained in:
Carol Willing
29
docs/source/config-basics.md
Normal file
29
docs/source/config-basics.md
Normal file
@@ -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)
|
||||
@@ -36,6 +36,7 @@ Contents
|
||||
|
||||
* :doc:`quickstart`
|
||||
* :doc:`getting-started`
|
||||
* :doc:`quickstart-docker`
|
||||
|
||||
|
||||
**Configuration Reference**
|
||||
|
||||
44
docs/source/quickstart-docker.rst
Normal file
44
docs/source/quickstart-docker.rst
Normal file
@@ -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/
|
||||
@@ -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
|
||||
@@ -43,11 +43,12 @@ 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.
|
||||
|
||||
@@ -5,4 +5,6 @@ Installation Guide
|
||||
:maxdepth: 3
|
||||
|
||||
quickstart
|
||||
quickstart-docker
|
||||
config-basics
|
||||
getting-started
|
||||
|
||||
Reference in New Issue
Block a user