Skip to main content

Reverse Proxy & Caddy

Lioran S3 does not terminate TLS natively; it delegates SSL/TLS termination and public ingress to a production reverse proxy. The canonical reference configuration uses Caddy 2.

1. Canonical Caddyfile Reference​

The following Caddyfile is configured for high-throughput unbuffered streaming:

Caddyfile
{
    # Disable Caddy admin API inside the container
    admin off
}

# Bind to configured BASTION_DOMAIN (e.g. s3.example.com or localhost)
{$BASTION_DOMAIN:s3.example.com} {
    # Modern compression for textual API payloads (skips pre-compressed media)
    encode zstd gzip

    # Production security headers
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        -Server
    }

    # Restrict Prometheus metrics endpoints to private/loopback networks
    @metrics {
        path /metrics /api/v1/metrics
    }
    handle @metrics {
        @internal remote_ip 127.0.0.1 ::1 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
        handle @internal {
            reverse_proxy bastion:27118
        }
        respond "Forbidden" 403
    }

    # Public health check endpoints
    @health {
        path /health /api/v1/health
    }
    handle @health {
        reverse_proxy bastion:27118
    }

    # Primary Storage API Gateway & High-Throughput Streaming Reverse Proxy
    handle {
        reverse_proxy bastion:27118 {
            # Immediate chunk flushing for real-time video playback and streaming uploads
            flush_interval -1

            # Upstream HTTP transport configuration
            transport http {
                dial_timeout 10s
                response_header_timeout 600s
                idle_timeout 60s
                max_idle_conns_per_host 100
            }
        }
    }

    # Structured JSON access logging to container stdout
    log {
        output stdout
        format json
    }
}

2. Key Reverse Proxy Directives​

flush_interval -1 (Unbuffered Streaming)​

By default, some reverse proxies buffer chunks in memory before forwarding them to the client. Setting flush_interval -1 forces Caddy to forward chunks immediately as they arrive from bastion-server, enabling real-time streaming, video playback, and low-latency chunked uploads.

Transport Timeouts​

  • response_header_timeout 600s: Accommodates multi-gigabyte atomic multipart assembly operations without timing out.
  • max_idle_conns_per_host 100: Maintains high-concurrency connection pools between proxy and server.

Metrics Protection​

Prometheus metrics (/metrics and /api/v1/metrics) are shielded by CIDR checks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.1), preventing unauthorized external access to runtime telemetry.