This chapter is for contributors and maintainers.

Caddy Reverse Proxy

Caddy is the edge proxy and security gateway for the NeuralDrive appliance. It handles TLS termination, URL routing, and authentication for API endpoints.

The Caddyfile

The routing logic is defined in /etc/neuraldrive/Caddyfile. This file is loaded by the neuraldrive-caddy.service.

Key Routing Rules

NeuralDrive uses two separate server blocks — one for the web dashboard and one for the API gateway:

:443 {
    # TLS termination for the Web UI
    tls /etc/neuraldrive/tls/server.crt /etc/neuraldrive/tls/server.key

    # All requests proxy to Open WebUI
    reverse_proxy localhost:3000
}

:8443 {
    # TLS termination for the API gateway
    tls /etc/neuraldrive/tls/server.crt /etc/neuraldrive/tls/server.key

    # Ollama Inference API (/v1/* and /api/*)
    # Requires Bearer token matching NEURALDRIVE_API_KEY
    @api_authenticated {
        path /v1/* /api/*
        header Authorization "Bearer {env.NEURALDRIVE_API_KEY}"
    }
    handle @api_authenticated {
        reverse_proxy localhost:11434
    }
    # Unauthenticated API requests get 401
    handle @api_routes {
        respond 401
    }

    # GPU Monitoring
    handle /monitor/* {
        reverse_proxy localhost:1312
    }

    # System Management API
    handle /system/* {
        reverse_proxy localhost:3001
    }

    # Health Check (public)
    handle /health {
        respond "OK" 200
    }
}

The dual-port architecture keeps the user-facing web UI separate from the machine-to-machine API gateway, allowing each to be managed independently.

Security Features

TLS Management

Caddy uses the certificates generated by neuraldrive-certs.service. By default, these are self-signed RSA 4096-bit certificates. Caddy is configured to only allow modern TLS protocols (1.2 and 1.3).

API Authentication

For requests to /v1/* and /api/*, Caddy can be configured to enforce Bearer token authentication. The valid API key is sourced from the NEURALDRIVE_API_KEY environment variable, which is populated from /etc/neuraldrive/caddy.env.

Capabilities

The neuraldrive-caddy.service uses AmbientCapabilities=CAP_NET_BIND_SERVICE. This allows the non-root neuraldrive-caddy user to bind to privileged ports like 443.

Environment Variables (caddy.env)

• NEURALDRIVE_API_KEY: The master 32-character key for the appliance.
• DOMAIN_NAME: (Optional) Used for ACME/Let's Encrypt integration if the user provides a public domain.

Customizing Routes

To add a new service to the NeuralDrive stack:

1. Assign it a local port (e.g., 8080).
2. Add a handle_path block to the Caddyfile.
3. Re-build the image or restart the neuraldrive-caddy service.

Tip: Use caddy validate --config /etc/neuraldrive/Caddyfile to check for syntax errors before restarting the service.