JupyShare/README.md

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)        │   │
│  └─────────────┘ └──────────────┘ └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘