leo-claude-mktplace/plugins/ops-deploy-pipeline/skills/caddy-conventions.md

Caddy Conventions Skill

Caddyfile patterns for reverse proxy configuration in self-hosted environments.

Subdomain Routing

Each service gets a subdomain of the server hostname:

myapp.hotport {
    reverse_proxy app:8080
}

For services on non-standard ports:

myapp.hotport {
    reverse_proxy app:3000
}

Reverse Proxy Directives

Basic Reverse Proxy

subdomain.hostname {
    reverse_proxy container_name:port
}

With Health Checks

subdomain.hostname {
    reverse_proxy container_name:port {
        health_uri /health
        health_interval 30s
        health_timeout 10s
    }
}

Load Balancing (Multiple Instances)

subdomain.hostname {
    reverse_proxy app1:8080 app2:8080 {
        lb_policy round_robin
    }
}

Security Headers

Apply to all sites:

(security_headers) {
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
        -Server
    }
}

Import in site blocks: import security_headers

Rate Limiting

For API endpoints:

subdomain.hostname {
    rate_limit {
        zone api_zone {
            key {remote_host}
            events 100
            window 1m
        }
    }
    reverse_proxy app:8080
}

Docker Network Integration

Caddy must be on the same Docker network as the target service to use container DNS names. The Caddy container needs:

networks:
  - caddy-network
  - app-network  # Join each app's network

CORS Configuration

subdomain.hostname {
    header Access-Control-Allow-Origin "*"
    header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    header Access-Control-Allow-Headers "Content-Type, Authorization"

    @options method OPTIONS
    respond @options 204

    reverse_proxy app:8080
}

Automatic HTTPS

• Caddy provides automatic HTTPS for public domains
• For local .hotport subdomains, use HTTP only (no valid TLS cert)
• For Tailscale access, consider tls internal for self-signed certs

File Server (Static Assets)

files.hotport {
    root * /srv/files
    file_server browse
}