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.
  • Git LFS: A Git extension for versioning large files.
  • Pandoc: A universal markup converter.
  • Python: An interpreted, object-oriented, high-level programming language with dynamic semantics.
  • Quarto: A scientific and technical publishing system built on Pandoc.
  • R: A language and environment for statistical computing and graphics.
  • radian: An alternative console for R with multiline editing and rich syntax highlight.
  • RStudio: An integrated development environment (IDE) for R.
  • 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 (default: 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
• EditorConfig for VS Code
• Git Graph
• GitHub Pull Requests and Issues
• GitLab Workflow
• GitLens — Git supercharged
  ℹ️ Pinned to version 11.7.0 due to unsolicited AI content
• Excel Viewer
• Jupyter
• LaTeX Workshop
• markdownlint
• Path Intellisense
• Project Manager
• Python
• Quarto
• 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
• Git LFS
  • Homepage: https://git-lfs.github.com
  • Documentation: https://github.com/git-lfs/git-lfs/tree/main/docs
• Pandoc
  • Homepage: https://pandoc.org
  • Manual: https://pandoc.org/MANUAL.html
• Python
  • Homepage: https://www.python.org
  • Documentation: https://docs.python.org
• 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
• RStudio
  • Homepage: https://posit.co/products/open-source/rstudio-server
  • User Guide: https://docs.posit.co/ide/user/
• TinyTeX
  • Homepage: https://yihui.org/tinytex/
• Zsh
  • Homepage: http://zsh.sourceforge.net
  • Documentation: http://zsh.sourceforge.net/Doc/Release/zsh_toc.html

Table of Contents

• Prerequisites
• Install
• Usage
• Further reading
• Similar projects
• Contributing
• License

Prerequisites

The following is required:

• A DNS record for subdomain (default: jupyter) pointing to this host.

Install

This project depends on the following Docker Deployments:

• Træfik: TLS termination, reverse proxy
• GitLab CE: Authentication

Usage

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 subdomain.

   • 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

Test

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

Reference deployment

Check out the reference deployment at https://demo.jupyter.b-data.ch.

• Security Analysis
• SSL Server Test

Hardened and customised to meet the latest web application security standards.

Further reading

JupyterHub:

• Authenticators
• DockerSpawner API
• The Hub's Database

JupyterLab:

• ServerProxy

Similar projects

• defeo/jupyterhub-docker

Contributing

PRs accepted. Please submit to the GitLab repository.

This project follows the Contributor Covenant Code of Conduct.

License

Copyright © 2020 b-data GmbH

Distributed under the terms of the MIT License.