# 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) ```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= - List notebooks and directories GET / - Main web interface GET /view/ - View notebook as HTML GET /download/ - 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: ```bash docker-compose logs -f notebook-viewer ``` ## License MIT License - see LICENSE file for details. Architecture