diff --git a/docs/source/quickstart-docker.rst b/docs/source/quickstart-docker.rst index d4153a14..6ecacf3b 100644 --- a/docs/source/quickstart-docker.rst +++ b/docs/source/quickstart-docker.rst @@ -1,49 +1,62 @@ -Using Docker -============ +Install JupyterHub with Docker +============================== + +The JupyterHub `docker image `_ is the fastest way to set up Jupyterhub in your local development environment. + +The ``JupyterHub`` docker image runs the Hub service only. It does not provide 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 or Jupyter Lab must be installed. .. important:: + We strongly recommend that you follow the `Zero to JupyterHub`_ tutorial to + install JupyterHub. + + +Prerequisites +------------- +You should have `Docker`_ installed on a Linux/Unix based system. - We highly recommend following the `Zero to JupyterHub`_ tutorial for - installing JupyterHub. -Alternate installation using Docker ------------------------------------ - -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:: +Run the Docker Image +-------------------- +To pull the latest JupyterHub image and start the `jupyterhub` container, run this command in your terminal. +:: + docker run -d -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub jupyterhub -This command will create a container named ``jupyterhub`` that you can -**stop and resume** with ``docker stop/start``. +This command exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console. -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**. +You can stop and resume the container by running `docker stop` and `docker start` respectively. +:: -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 + # find the container id + docker ps + + # stop the running container + docker stop + + # resume the paused container + docker start + + +If you are running Docker on a computer that has a public IP address, you 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 +`Mounting volumes `_ +enables you to persist and store the data generated by the docker container, even when you stop the container. +The persistent data can be stored on the host system, outside the container. + + +Create System Users +------------------- + +Spawn a root shell in your docker container by running this command in the terminal.:: + + docker exec -it jupyterhub bash + +The created accounts will be used for authentication in JupyterHub's default configuration. .. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/ +.. _Docker: https://www.docker.com/