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.

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

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


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