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.

Quick Start

Using Nix (Recommended)

# Enter development environment
nix develop

# Set up the environment (first time only)
setup-dev

# Start development server
dev-server

Using Docker

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Start with Docker Compose
docker-compose up

Manual Installation

# 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)

Development

With Nix

The project includes a complete Nix flake for reproducible development:

# 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:

# 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

# 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

# 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:

# 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)

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:

docker-compose logs -f notebook-viewer

License

MIT License - see LICENSE file for details. Architecture

4.2 KiB Raw Blame History