Deployment & HTTPS

2 min read

PgArachne is designed to perform one job well: API Gateway. For SSL/TLS (HTTPS), header security, and public routing, you should place a Reverse Proxy in front of it.

Option A: Caddy Server

Best for: Modern production deployments, ease of use.

Caddy is the only web server that obtains and renews SSL certificates (Let’s Encrypt) automatically by default. It requires almost zero configuration.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Option B: Nginx

Best for: Enterprise environments, complex routing.

Nginx is the industry standard for high-performance load balancing. Use this if you already have an Nginx infrastructure. You will need to manage Certbot manually.

server {
    server_name example.com;
    location / {
        proxy_pass http://localhost:8080;
    }
}

Option C: Ngrok

Best for: Local development, Demos, Webhook testing.

Ngrok creates a secure tunnel from the public internet directly to your laptop without configuring firewalls. Ideal for showing your work to colleagues instantly.

./ngrok http 8080

Production checklist

Terminate TLS on the reverse proxy and forward X-Forwarded-Proto and X-Forwarded-For.
Set TRUSTED_PROXIES in PgArachne to your proxy IP/CIDR ranges.
Disable buffering for SSE routes and keep read timeouts long enough for streaming.
Expose metrics only internally (default 127.0.0.1:9090) and scrape from your monitoring network.

Nginx hardening example (SSE + forwarded headers)

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

location /sse/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_read_timeout 1h;
}

← Security & Authentication Error Codes →