{"id":32524009,"url":"https://github.com/ucphhpc/jupyter_service","last_synced_at":"2026-02-23T02:35:41.091Z","repository":{"id":50902038,"uuid":"108971437","full_name":"ucphhpc/jupyter_service","owner":"ucphhpc","description":"A docker swarm of Jupyter Notebooks","archived":false,"fork":false,"pushed_at":"2025-09-11T12:34:28.000Z","size":277,"stargazers_count":5,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-11T15:46:46.559Z","etag":null,"topics":["docker-swarm-cluster","jupyterhub-deployment","jupyterhub-swarmspawner-deployment"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ucphhpc.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-10-31T09:10:36.000Z","updated_at":"2025-09-11T12:34:32.000Z","dependencies_parsed_at":"2025-06-10T09:22:08.156Z","dependency_job_id":"4a16714d-731f-4c05-85fb-ffe810c22608","html_url":"https://github.com/ucphhpc/jupyter_service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ucphhpc/jupyter_service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fjupyter_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fjupyter_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fjupyter_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fjupyter_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ucphhpc","download_url":"https://codeload.github.com/ucphhpc/jupyter_service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fjupyter_service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29735759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T02:24:00.660Z","status":"ssl_error","status_checked_at":"2026-02-23T02:22:56.087Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-swarm-cluster","jupyterhub-deployment","jupyterhub-swarmspawner-deployment"],"created_at":"2025-10-28T08:32:47.380Z","updated_at":"2026-02-23T02:35:41.074Z","avatar_url":"https://github.com/ucphhpc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"===============\njupyter_service\n===============\n\nA jupyter notebook docker swarm setup that consists of a customised JupyterHub service that spawns individual notebooks for\nindividual users.\n\n- `UCPHHPC Jupyterhub \u003chttps://github.com/ucphhpc/docker-JupyterHub.git\u003e`_\n\n------------\nArchitecture\n------------\n\nThe stack is made of a 2 layered docker swarm stack, i.e. any external\nrequest is received by the JupyterHub proxy service, which redirects requests to the JupyterHub service where an authenticated user is allowed to start a notebook.\n\nThe authentication is defined by `Authenticators \u003chttps://JupyterHub.readthedocs.io/en/stable/\nreference/authenticators.html\u003e`_ where Jupyterhub allows for a custom\nauthenticator to be selected based on the local requirements.\nHence how a user should be authenticated before they are able to launch notebooks via the JupyterHub web interface.\nThe authenticator itself is selected by defining the ``authenticator_class`` variable as shown in\nthe ``example/non_ssl/basic_jupyterhub_config.py`` configuration file.\n\nBeyond authentication, JupyterHub also allows for a custom `Spawner \u003chttps://JupyterHub.readthedocs.io/en/stable/reference/spawners.html\u003e`_\nscheme to be overloaded.\nThe default ``spawner_class`` in the ``example/non_ssl/basic_jupyterhub_config.py`` configuration file\nis defined with the `jhub-swarmspawner \u003chttps://github.com/ucphhpc/SwarmSpawner\u003e`_ which enables the deployment of\njupyter notebooks on a `Docker Swarm Cluster \u003chttps://github.com/docker/swarmkit\u003e`_\ncluster whenever a user requests a new notebook.\n\n-------------\nPrerequisites\n-------------\n\nAs a prerequisite the JupyterHub service is able to launch separate notebook services,\nJupyterHub needs access to the hosts docker daemon process. This access can\nbe gained in a number of ways, one of which is to mount the ``/var/run/docker\n.sock`` file inside the JupyterHub service as a volume and then ensuring that\nthe user that executes the ``deploy`` command is part of the ``docker`` system\ngroup. This is the default approach as defined in the docker-compose.yml file.\n\nAnother approach would be to expose the docker daemon remotely on port 2376\nwith TLS verification as explained @ `Docker Docs \u003chttps://docs.docker\n.com/engine/reference/commandline/dockerd/#description\u003e`_ under \"Daemon\nsocket option\".\n\nIn addition it requires that the JupyterHub service is deployed on a swarm manager node.\nSee `Create a swarm \u003chttps://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm\u003e`_.\nHence the restriction set in the docker-compose file that the JupyterHub service is restricted to a manager node.\n\nUpon launching the ``example/basic_docker-compose.yml`` stack also provides an `docker-image-updater \u003chttps://github.com/ucphhpc/docker-image-updater\u003e`_ service.\nThis service provides a continuously monitor whether new versions of the specified notebook image is available,\nand if so pulls it to every swarm node and prunes previous versions when no other running notebook depends on that particular version.\n\n-------------\nConfiguration\n-------------\n\nBefore the stack can be deployed, the ``docker-compose.yml``, ``jupyterhub_config.py``, and ``.env`` files needs to be prepared. This can be achived by using the ``make init`` target to generate the nessesary environment for your deployment.\nBy default, the Makefile will select the non-SSL configuration in the ``example/non_ssl`` directory, and the `defaults.env` environment file will be produced and linked by the `.env` file.\n\nThis non-SSL version is configured to publish the JupyterHub service on port 8080. Furthermore, the example JupyterHub configuration file examples in \n`example/*` uses an **insecure default password ``dummy`` that should not be used in a production environment**. This can be changed by altering the\nfollowing option in the default ``example/non_ssl/basic_jupyterhub_config.py`` file before it is copied into the ``hub/jupyterhub`` directory before calling the ``make init`` target.::\n\n    # Authenticator\n    c.JupyterHub.authenticator_class = \"jhubauthenticators.DummyAuthenticator\"\n    c.DummyAuthenticator.password = \"dummy\"\n\nOnce the selected ``jupyterhub_config.py`` file has been properly prepared, the configuration can be prepared by calling::\n\n    make init\n\nAn alternative to this is to setup the ``docker-compose.yml`` and ``hub/jupyterhub/jupyterhub_config.py`` files yourself before launching the stack.\n\nFinally, ``make clean`` can be called if you want to remove the various configuration and environment files that have been prepared by the ``init`` call.\n\n---------------------\nLaunching the Service\n---------------------\n\nOnce the Configuration has been completed, the service can be launched by executing the following command inside the repository directory::\n\n    make daemon\n\nTo verify that the stack is now deployed and the services are being spawned\ndo::\n\n    docker stack ls\n    docker service ls\n\nThe ``stack`` command should return that the jupyter-service stacks is running with 3 services, i.e. the JupyterHub, the proxy, and the image-updater services.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucphhpc%2Fjupyter_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucphhpc%2Fjupyter_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucphhpc%2Fjupyter_service/lists"}