{"id":13586395,"url":"https://github.com/jupyterhub/jupyterhub-deploy-docker","last_synced_at":"2025-05-14T21:05:10.204Z","repository":{"id":44860405,"uuid":"56241532","full_name":"jupyterhub/jupyterhub-deploy-docker","owner":"jupyterhub","description":"Reference deployment of JupyterHub with docker","archived":false,"fork":false,"pushed_at":"2025-03-03T20:41:59.000Z","size":418,"stargazers_count":729,"open_issues_count":6,"forks_count":380,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-04-06T14:05:00.740Z","etag":null,"topics":["docker-container","docker-deployment","docker-volumes","jupyter","jupyter-notebook","jupyterhub"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jupyterhub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-14T13:53:14.000Z","updated_at":"2025-04-06T02:37:22.000Z","dependencies_parsed_at":"2022-08-12T11:40:15.457Z","dependency_job_id":"66903c8c-0523-4506-9b98-be17965004da","html_url":"https://github.com/jupyterhub/jupyterhub-deploy-docker","commit_stats":{"total_commits":97,"total_committers":17,"mean_commits":5.705882352941177,"dds":0.7938144329896908,"last_synced_commit":"892ac57d758df0da44ed49aded712fa3fc2cd8b4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Fjupyterhub-deploy-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Fjupyterhub-deploy-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Fjupyterhub-deploy-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyterhub%2Fjupyterhub-deploy-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jupyterhub","download_url":"https://codeload.github.com/jupyterhub/jupyterhub-deploy-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248749762,"owners_count":21155678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-container","docker-deployment","docker-volumes","jupyter","jupyter-notebook","jupyterhub"],"created_at":"2024-08-01T15:05:32.387Z","updated_at":"2025-04-13T16:50:13.453Z","avatar_url":"https://github.com/jupyterhub.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# jupyterhub-deploy-docker\n\n**jupyterhub-deploy-docker** provides a reference\ndeployment of [JupyterHub](https://github.com/jupyterhub/jupyterhub), a\nmulti-user [Jupyter Notebook](https://jupyter.org) environment, on a\n**single host** using [Docker](https://docs.docker.com).\n\nPossible **use cases** include:\n\n- Creating a JupyterHub demo environment that you can spin up relatively\n  quickly.\n- Providing a multi-user Jupyter Notebook environment for small classes,\n  teams or departments.\n\n## Disclaimer\n\nThis deployment is **NOT** intended for a production environment.\nIt is a reference implementation that does not meet traditional\nrequirements in terms of availability, scalability, or security.\n\nIf you are looking for a more robust solution to host JupyterHub, or\nyou require scaling beyond a single host, please check out the\nexcellent [zero-to-jupyterhub-k8s](https://github.com/jupyterhub/zero-to-jupyterhub-k8s)\nproject.\n\n## Technical Overview\n\nKey components of this reference deployment are:\n\n- **Host**: Runs the [JupyterHub components](https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html)\n  in a Docker container on the host.\n\n- **Authenticator**: Uses [Native Authenticator](https://github.com/jupyterhub/nativeauthenticator) to authenticate users.\n  Any user will be allowed to sign up.\n\n- **Spawner**: Uses [DockerSpawner](https://github.com/jupyterhub/dockerspawner)\n  to spawn single-user Jupyter Notebook servers in separate Docker\n  containers on the same host.\n\n- **Persistence of Hub data**: Persists JupyterHub data in a Docker\n  volume on the host.\n\n- **Persistence of user notebook directories**: Persists user notebook\n  directories in Docker volumes on the host.\n\n## Prerequisites\n\n### Docker\n\nThis deployment uses Docker, via [Docker Compose](https://docs.docker.com/compose/), for all the things.\n\n1. Use [Docker's installation instructions](https://docs.docker.com/engine/install/)\n   to set up Docker for your environment.\n\n## Authenticator setup\n\nThis deployment uses [JupyterHub Native Authenticator](https://native-authenticator.readthedocs.io/en/latest/) to authenticate users.\n\n1. An single `admin` user will be enabled by default. Any user will be allowed to sign up.\n\n## Build the JupyterHub Docker image\n\n1. Use [docker compose](https://docs.docker.com/compose/reference/) to build\n   the JupyterHub Docker image:\n\n   ```bash\n   docker compose build\n   ```\n\n## Customisation: Jupyter Notebook Image\n\nYou can configure JupyterHub to spawn Notebook servers from any Docker image, as\nlong as the image's `ENTRYPOINT` and/or `CMD` starts a single-user instance of\nJupyter Notebook server that is compatible with JupyterHub.\n\nTo specify which Notebook image to spawn for users, you set the value of the\n`DOCKER_NOTEBOOK_IMAGE` environment variable to the desired container image.\n\nWhether you build a custom Notebook image or pull an image from a public or\nprivate Docker registry, the image must reside on the host.\n\nIf the Notebook image does not exist on the host, Docker will attempt to pull the\nimage the first time a user attempts to start his or her server. In such cases,\nJupyterHub may timeout if the image being pulled is large, so it is better to\npull the image to the host before running JupyterHub.\n\nThis deployment defaults to the\n[quay.io/jupyter/base-notebook](https://quay.io/repository/jupyter/base-notebook)\nNotebook image, which is built from the `base-notebook`\n[Docker stacks](https://github.com/jupyter/docker-stacks).\n\nYou can pull the image using the following command:\n\n```bash\ndocker pull quay.io/jupyter/base-notebook:latest\n```\n\n## Run JupyterHub\n\nRun the JupyterHub container on the host.\n\nTo run the JupyterHub container in detached mode:\n\n```bash\ndocker compose up -d\n```\n\nOnce the container is running, you should be able to access the JupyterHub console at `http://localhost:8000`.\n\nTo bring down the JupyterHub container:\n\n```bash\ndocker compose down\n```\n\n---\n\n## FAQ\n\n### How can I view the logs for JupyterHub or users' Notebook servers?\n\nUse `docker logs \u003ccontainer\u003e`. For example, to view the logs of the `jupyterhub` container\n\n```bash\ndocker logs jupyterhub\n```\n\n### How do I specify the Notebook server image to spawn for users?\n\nIn this deployment, JupyterHub uses DockerSpawner to spawn single-user\nNotebook servers. You set the desired Notebook server image in a\n`DOCKER_NOTEBOOK_IMAGE` environment variable.\n\nJupyterHub reads the Notebook image name from `jupyterhub_config.py`, which\nreads the Notebook image name from the `DOCKER_NOTEBOOK_IMAGE` environment\nvariable:\n\n```python\n# DockerSpawner setting in jupyterhub_config.py\nc.DockerSpawner.image = os.environ['DOCKER_NOTEBOOK_IMAGE']\n```\n\n### If I change the name of the Notebook server image to spawn, do I need to restart JupyterHub?\n\nYes. JupyterHub reads its configuration, which includes the container image\nname for DockerSpawner. JupyterHub uses this configuration to determine the\nNotebook server image to spawn during startup.\n\nIf you change DockerSpawner's name of the Docker image to spawn, you will\nneed to restart the JupyterHub container for changes to occur.\n\nIn this reference deployment, cookies are persisted to a Docker volume on the\nHub's host. Restarting JupyterHub might cause a temporary blip in user\nservice as the JupyterHub container restarts. Users will not have to login\nagain to their individual notebook servers. However, users may need to\nrefresh their browser to re-establish connections to the running Notebook\nkernels.\n\n### How can I back up a user's notebook directory?\n\nThere are multiple ways to [Back up and restore data](https://docs.docker.com/desktop/backup-and-restore/) in Docker containers.\n\nSuppose you have the following running containers:\n\n```bash\n    docker ps --format \"table {{.ID}}\\t{{.Image}}\\t{{.Names}}\"\n\n    CONTAINER ID        IMAGE                    NAMES\n    bc02dd6bb91b        quay.io/jupyter/minimal-notebook jupyter-jtyberg\n    7b48a0b33389        quay.io/jupyterhub               jupyterhub\n```\n\nIn this deployment, the user's notebook directories (`/home/jovyan/work`) are backed by Docker volumes.\n\n```bash\n    docker inspect -f '{{ .Mounts }}' jupyter-jtyberg\n\n    [{jtyberg /var/lib/docker/volumes/jtyberg/_data /home/jovyan/work local rw true rprivate}]\n```\n\nWe can back up the user's notebook directory by running a separate container that mounts the user's volume and creates a tarball of the directory.\n\n```bash\ndocker run --rm \\\n  -u root \\\n  -v /tmp:/backups \\\n  -v jtyberg:/notebooks \\\n  quay.io/jupyter/minimal-notebook \\\n  tar cvf /backups/jtyberg-backup.tar /notebooks\n```\n\nThe above command creates a tarball in the `/tmp` directory on the host.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterhub%2Fjupyterhub-deploy-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupyterhub%2Fjupyterhub-deploy-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyterhub%2Fjupyterhub-deploy-docker/lists"}