Awesome

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.

Screenshot

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.
- Neovim: Vim-fork focused on extensibility and usability.
- 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
:information_source: 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
Neovim
- Homepage: https://neovim.io
- Manual: https://neovim.io/doc
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

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

Create an external docker network named "jupyter":
```
docker network create jupyter
```

Make a copy of all sample. files and folders:

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

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.
Set environment variable JH_COOKIE_SECRET in '.env':
Generate random cookie secret:
```
openssl rand -hex 32
```
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"
Update environment variables JH_GITLAB_APPLICATION_ID and JH_GITLAB_SECRET in '.env' accordingly.
Update the following environment variable in 'db.env':
- POSTGRES_PASSWORD: Superuser password for PostgreSQL (default: password)
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><summary>Details</summary>

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.

</details>

SSL Security Test

<details><summary>Details</summary>

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

</details>

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

Similar projects

defeo/jupyterhub-docker

Contributing

PRs accepted. Please submit to the GitLab repository.

This project follows the Contributor Covenant Code of Conduct.

License

Distributed under the terms of the MIT License.

Support

Community support: Open a new discussion here.

Commercial support: Contact b-data by email.

Trademarks

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.