From b961925bbccc2dc714a99f9b90cec42cbb18c98b Mon Sep 17 00:00:00 2001 From: ikeadeoyin Date: Mon, 10 Oct 2022 08:48:43 +0100 Subject: [PATCH] improved the quickstart docker guide --- docs/source/quickstart-docker.rst | 77 ++++++++++++++++++------------- 1 file changed, 44 insertions(+), 33 deletions(-) diff --git a/docs/source/quickstart-docker.rst b/docs/source/quickstart-docker.rst index d4153a14..21cb67f5 100644 --- a/docs/source/quickstart-docker.rst +++ b/docs/source/quickstart-docker.rst @@ -1,49 +1,60 @@ -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 version 4 or greater must be installed. .. important:: + We strongly recommend that you follow the `Zero to JupyterHub`_ tutorial to + install JupyterHub. + + +Prerequisites +------------------------------- +You should have `Docker Desktop`_ 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 +Run the Docker Image ------------------------------- -The JupyterHub docker image can be started with the following command:: - +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 `_ +persist and stores the data generated by the docker container, even when you stop the container. +The persistent data can be stored outside the host system. + + +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 Desktop: https://www.docker.com/products/docker-desktop