Jupyter

This project serves as a template to run jupyterhub with jupyterlab/r/verse in docker containers using docker compose.

Features

• JupyterHub: A multi-user Hub which spawns, manages, and proxies multiple instances of the single-user JupyterLab server.
  • PostgreSQL database to store information about users, services, and other data needed for operating the Hub.
• JupyterLab: A web-based interactive development environment for Jupyter notebooks, code, and data. The custom Docker image includes
  • code-server: VS Code in the browser without MS branding/telemetry/licensing.
  • Git: A distributed version-control system for tracking changes in source code.
  • Pandoc: A universal markup converter.
  • Quarto: An open-source scientific and technical publishing system built on Pandoc. (amd64 only)
  • R: A language and environment for statistical computing and graphics.
  • radian: An alternative console for R with multiline editing and rich syntax highlight.
  • TinyTeX: A lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live.
  • Zsh: A shell designed for interactive use, although it is also a powerful scripting language.
• Pre-configured to run at a subdomain (jupyter) of your own domain.
• Use of environment files for variable substitution in the Compose file.

The following extensions are pre-installed for code-server:

• .gitignore Generator
• Git Graph
• GitLab Workflow
• GitLens — Git supercharged
• Excel Viewer
• Jupyter
• LaTeX Workshop
• Path Intellisense
• Project Manager
• Python
• Quarto (amd64 only)
• R
• YAML

About

• JupyterHub
  • Homepage: https://jupyter.org/hub
  • Documentation: https://jupyterhub.readthedocs.io/en/stable/
• JupyterLab
  • Homepage: https://jupyter.org
  • Documentation: https://jupyterlab.readthedocs.io/en/stable/
• code-server
  • Homepage: https://github.com/cdr/code-server
  • Documentation: https://code.visualstudio.com/Docs
• Git
  • Homepage: https://git-scm.com
  • Documentation: https://git-scm.com/docs
• Pandoc
  • Homepage: https://pandoc.org
  • Manual: https://pandoc.org/MANUAL.html
• Quarto
  • Homepage: https://quarto.org
  • Reference: https://quarto.org/docs/reference/
• R
  • Homepage: https://www.r-project.org
  • Manuals: https://cran.r-project.org/manuals.html
• radian
  • Homepage: https://github.com/randy3k/radian
• TinyTeX
  • Homepage: https://yihui.org/tinytex/
• Zsh
  • Homepage: http://zsh.sourceforge.net
  • Documentation: http://zsh.sourceforge.net/Doc/Release/zsh_toc.html

Prerequisites

The following is required:

• Docker Deployments of
  • Træfik
  • GitLab CE
• A DNS record for subdomain jupyter pointing to this host.

Setup

1. Create an external docker network named "jupyter":

   docker network create jupyter

2. Make a copy of all sample. files and folders:

   for file in sample.*; do cp -r "$file" "${file#sample.}"; done;

3. Update environment variables JH_DOMAIN, GL_DOMAIN and JH_CERTRESOLVER_NAME in '.env':
   • Replace mydomain.com with your own domain that serves the subdomain.
   • Replace mydomain-com with a valid certificate resolvers name of Træfik.
4. Set environment variable JH_COOKIE_SECRET in '.env':
   Generate random cookie secret:

   openssl rand -hex 32

5. Add JupyterHub as an OAuth application in GitLab CE:

   Name: JupyterHub
   Redirect URL: https://jupyter.mydomain.com/hub/oauth_callback

   → Replace mydomain.com with your own domain that serves the subdomains.
   • Tick "Trusted"
   • Scopes:
     • Tick "api"
   • Click "Submit" and copy "Application ID" and "Secret"
6. Update environment variables JH_GITLAB_APPLICATION_ID and JH_GITLAB_SECRET in '.env' accordingly.
7. Update the following environment variable in 'db.env':
   • POSTGRES_PASSWORD: Superuser password for PostgreSQL (default: password)
8. Start the container in detached mode:

   docker compose up -d

The image for service jupyterhub will be built now, because it does not exist yet. This souldn't take long...
→ To rebuild the image you must use docker compose build or docker compose up --build.

Test

Wait a moment and visit https://jupyter.mydomain.com to confirm everything went fine.

Further reading

JupyterHub

• Authenticators
• DockerSpawner API
• The Hub's Database

JupyterLab

• ServerProxy

Contributing

PRs accepted.

This project follows the Contributor Covenant Code of Conduct.

License

MIT © 2020 b-data GmbH

Third party code

This project was inspired by the JupyterHub deployment in use at Université de Versailles by Luca De Feo.

See LICENSE-THIRD-PARTY for details.