JupyterHub Notebook Viewer

A Flask-based web application for viewing and browsing Jupyter notebooks from a JupyterHub shared directory. Features a responsive web interface with directory navigation, notebook preview, and download capabilities. Features

📁 Directory Navigation - Browse through nested directories with breadcrumb navigation
📄 Notebook Viewing - Convert and display Jupyter notebooks as HTML in the browser
⬇️ Download Support - Direct download of notebook files
🎨 Responsive Design - Bootstrap-based UI that works on desktop and mobile
🔒 Security - Path traversal protection and configurable access controls
🛠️ Configurable - All settings configurable via environment variables
🐳 Docker Support - Ready-to-use Docker containers and compose files
❄️ Nix Development - Complete Nix flake for reproducible development

Quick Start Using Nix (Recommended)

bash

Enter development environment

nix develop

Set up the environment (first time only)

setup-dev

Start development server

dev-server

Using Docker

bash

Copy and configure environment

cp .env.example .env

Edit .env with your settings

Start with Docker Compose

docker-compose up

Manual Installation

bash

Install dependencies

pip install -r requirements.txt

Configure environment

cp .env.example .env

Edit .env with your settings

Start the application

python app.py

Configuration

All configuration is done via environment variables, typically in a .env file: Core Settings

JUPYTERHUB_SHARED_DIR - Path to the shared notebook directory (default: /shared)
APP_TITLE - Application title shown in the interface

Flask Settings

FLASK_HOST - Host to bind to (default: 0.0.0.0)
FLASK_PORT - Port to run on (default: 5000)
FLASK_DEBUG - Enable debug mode (default: True)
FLASK_SECRET_KEY - Secret key for sessions (change in production!)

File Handling

MAX_FILE_SIZE - Maximum file size in bytes (default: 16777216 = 16MB)
NOTEBOOKS_PER_PAGE - Maximum notebooks to show per directory (default: 50)
ALLOWED_EXTENSIONS - Comma-separated list of allowed file extensions (default: .ipynb,.py,.md)

Feature Toggles

ENABLE_DOWNLOAD - Enable file downloads (default: True)
ENABLE_API - Enable JSON API endpoints (default: True)

UI Settings

THEME - UI theme, dark or light (default: dark)

Development With Nix

The project includes a complete Nix flake for reproducible development:

bash

Enter development shell

nix develop

Available commands in the shell:

setup-dev # Set up development environment dev-server # Start development server with auto-reload run-tests # Run basic tests

With Just

If you have just installed:

bash

See all available commands

just

Common commands

just setup # Set up development environment just dev # Start development server just docker-up # Start with Docker just test # Run tests just clean # Clean temporary files

Manual Development

bash

Install dependencies

pip install -r requirements.txt

Set up environment

cp .env.example .env

Create sample content

mkdir -p shared

Add some .ipynb files to shared/

Start development server

python app.py

Docker Deployment Basic Deployment

bash

Build and start

docker-compose up --build

Run in background

docker-compose up -d

View logs

docker-compose logs -f

With Reverse Proxy

The compose file includes an optional nginx reverse proxy:

bash

Start with proxy

docker-compose --profile with-proxy up

Production Considerations

For production deployment:

Change the secret key: Set FLASK_SECRET_KEY to a secure random value
Disable debug mode: Set FLASK_DEBUG=False
Configure volumes: Mount your actual shared directory
Set up SSL: Configure HTTPS in your reverse proxy
Resource limits: Set appropriate CPU and memory limits in Docker

API Endpoints

When ENABLE_API=True, the following JSON API endpoints are available:

GET /api/notebooks?dir=<path> - List notebooks and directories
GET / - Main web interface
GET /view/<path> - View notebook as HTML
GET /download/<path> - Download notebook file (if enabled)

Security Features

Path Traversal Protection - Prevents access outside the configured directory
File Type Validation - Only allows configured file extensions
Configurable Downloads - Downloads can be disabled entirely
Non-root Docker User - Container runs as non-privileged user

Troubleshooting Common Issues

"No notebooks found"
    Check that JUPYTERHUB_SHARED_DIR points to the correct directory
    Ensure the directory contains .ipynb files
    Check file permissions
Notebook won't display
    Verify the notebook file is valid JSON
    Check that nbconvert dependencies are installed
    Look for errors in the application logs
Permission denied
    Ensure the application has read access to the shared directory
    Check Docker volume mounts

Logs

Application logs are printed to stdout. In Docker:

bash

docker-compose logs -f notebook-viewer

Contributing

Fork the repository
Enter the development environment: nix develop
Make your changes
Run tests: run-tests
Submit a pull request

License

MIT License - see LICENSE file for details. Architecture

┌─────────────────────────────────────────────────────────────┐ │ Web Browser │ └─────────────────────┬───────────────────────────────────────┘ │ HTTP ┌─────────────────────▼───────────────────────────────────────┐ │ Flask App │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ │ │ Routes │ │ Templates │ │ Static Assets │ │ │ └─────────────┘ └──────────────┘ └─────────────────────┘ │ └─────────────────────┬───────────────────────────────────────┘ │ File System ┌─────────────────────▼───────────────────────────────────────┐ │ JupyterHub Shared Directory │ │ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐ │ │ │ Notebooks │ │ Directories │ │ Other Files │ │ │ │ (.ipynb) │ │ │ │ (.py, .md) │ │ │ └─────────────┘ └──────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘