Skip to content
Klutch.sh Docs

Deploying a Jupyter Notebook App

Introduction

Jupyter Notebook lets you run interactive Python notebooks with rich outputs. Deploying Jupyter with a Dockerfile on Klutch.sh provides reproducible environments, managed secrets, and persistent storage for notebooks and data—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure notebook access.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository with your notebooks and dependencies (GitHub is the only supported git source)
  • Docker familiarity and Python 3.10+ knowledge
  • Optional: GPU-enabled runtime if you plan to use CUDA-accelerated workloads

For platform onboarding, see the Quick Start.

Architecture and ports

  • Jupyter serves HTTP; set the internal container port to 8888.
  • If you run supporting databases or caches, deploy them as separate Klutch.sh TCP apps exposed on port 8000 and connect on their native ports.
  • Persistent storage is recommended for notebooks, data, and virtual environments.

Repository layout

jupyter-notebook/
├── notebooks/              # Your .ipynb files (mount as volume)
├── requirements.txt        # Python dependencies
├── start.sh                # Launch script
├── Dockerfile              # Must be at repo root for auto-detection
└── .env.example            # Template only; no secrets

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub:

Terminal window
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
exec jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser

Make it executable with chmod +x start.sh.

Dockerfile for Jupyter Notebook (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM python:3.11-slim


WORKDIR /app


COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt


COPY . /app


ENV PORT=8888


EXPOSE 8888
CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--NotebookApp.token="]

Notes:

  • For GPU, switch to a CUDA-enabled base image compatible with your dependencies.
  • Set a secure token or password in production; the example disables token for simplicity.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • PORT=8888
  • NOTEBOOK_DIR=/app/notebooks
  • JUPYTER_TOKEN=<secure-token> (recommended)
  • PYTHONUNBUFFERED=1

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=pip install -r requirements.txt
  • NIXPACKS_START_CMD=jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser
  • NIXPACKS_PYTHON_VERSION=3.11

These keep Jupyter compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /app/notebooks — required for notebooks and outputs.
  • /app/.venv — optional if you want to persist the virtual environment.
  • /app/data — optional for datasets or checkpoints.

Ensure these paths are writable inside the container.

Deploy Jupyter Notebook on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Jupyter.
  3. Set the internal port to 8888.
  4. Add the environment variables above (including a secure token and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/notebooks (and /app/.venv or /app/data if used), selecting sizes that fit your workload.
  6. Deploy. Your Jupyter Notebook server will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Health checks and production tips

  • Use a reverse proxy health check on /api/status or similar.
  • Enforce HTTPS at the edge; forward HTTP to port 8888 internally.
  • Set strong tokens/passwords; avoid disabling authentication in production.
  • Monitor volume usage for notebooks/data and resize before they fill.
  • Keep dependencies pinned and test with the Docker image for reproducible environments.

Jupyter Notebook on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8888 for the app (8000 externally for any TCP companions), you can deliver secure, collaborative notebooks without extra YAML or workflow overhead.