Install JupyterHub with Docker
============================================

The JupyterHub `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_ 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.


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 exposes the Jupyter container on port:8000. Navigate to `http://localhost:8000` in a web browser to access the JupyterHub console.

You can stop and resume the container by running `docker stop` and `docker start` respectively.::

    # find the container id
    docker ps

    # stop the running container
    docker stop  <container-id>

    # resume the paused container
    docker start <container-id>


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 <https://docs.docker.com/engine/admin/volumes/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