Jupyter

This project serves as a template to run jupyterhub with jupyterlab/r/verse in docker containers using docker compose.
ℹ️ For JupyterHub on a cloud/on-premise k8s environment, see Jupyter's Zero to JupyterHub with Kubernetes.

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: Code - OSS in the browser.
  • 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
• 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
• 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
• Support
• License
• Trademarks

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

  Details

  ImmuniWeb® Community Edition: Website Security Test
  
  Target: https://demo.jupyter.b-data.ch
  IP Address: Not specified
  
  Test completed
  
  Source URL: https://demo.jupyter.b-data.ch
  Tested URL: https://demo.jupyter.b-data.ch/hub/login?next=%2Fhub%2F
  Tested IP Address: 51.154.68.67
  Completed: June 10, 2024 10:35:25
  
  ╭───────────────────╮ ╭───────────╮ ╭───────────────────────────────╮
  │                   │ │  PCI DSS  │ │    Software Security Test     │
  │        /\         │ ╰───────────╯ ╰───────────────────────────────╯
  │       /  \        │ ╭───────────╮ ╭───────────────────────────────╮
  │      / /\ \       │ │  EU GDPR  │ │     Headers Security Test     │
  │     / ____ \      │ ╰───────────╯ ╰───────────────────────────────╯
  │    /_/    \_\     │ ╭───────────╮
  │                   │ │    CSP    │
  ╰───────────────────╯ ╰───────────╯
  
  Grade: A
  PCI DSS Compliance Test: 2 Issues Found
  EU GDPR Compliance Test: 3 Issues Found
  Content Security Policy Test: No Major Issues Found
  Software Security Test: 1 Issue Found
  Headers Security Test: No Major Issues Found
  
  HTTP Headers Security Notes:
  [Misconfiguration or Weakness] Some HTTP headers related to security and privacy are missing or misconfigured.
  
  Cookies Security Notes:
  [Misconfiguration or Weakness] Some cookies have missing secure flags or attributes.
  

• SSL Security Test

  Details

  ImmuniWeb® Community Edition: SSL Security Test
  
  Target: demo.jupyter.b-data.ch:443
  IP Address: Not specified
  
  Test completed
  
  Tested Hostname: demo.jupyter.b-data.ch
  Tested Port: 443
  Tested IP Address: 51.154.68.67
  Completed: June 10, 2024 07:37:55
  
  ╭───────────────────╮ ╭───────────╮ ╭───────────────────────────────╮
  │                   │ │   HIPAA   │ │    Industry Best Practices    │
  │       /\    _     │ ╰───────────╯ ╰───────────────────────────────╯
  │      /  \ _| |_   │ ╭───────────╮
  │     / /\ \_   _|  │ │    NIST   │
  │    / ____ \|_|    │ ╰───────────╯
  │   /_/    \_\      │ ╭───────────╮
  │                   │ │  PCI DSS  │
  ╰───────────────────╯ ╰───────────╯
  
  Grade: A+
  HIPAA Compliance Test: No Major Issues Found
  NIST Compliance Test: No Major Issues Found
  PCI DSS Compliance Test: Compliant
  Industry Best Practices: No Issues Found
  
  Notes:
  [Good configuration] The server supports the most recent and secure TLS protocol version of TLS 1.3.0
  

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.

Support

Community support: Open a new disussion here.

Commercial support: Contact b-data by email.

Trademarks

RStudio® is a trademark of Posit Software, PBC, all rights reserved, and may be registered in the United States Patent and Trademark Office and in other countries.

The use of the trademarked term RStudio® and the distribution of the RStudio binaries through the images hosted on b-data's GitLab Container Registry (glcr.b-data.ch) has been granted by explicit permission of Posit Software, PBC. Please review Posit’s Trademark Guidelines and address inquiries about further distribution to permissions@posit.co.