Deployment e HTTPS

3 min di lettura

PgArachne è progettato per svolgere bene un solo compito: API Gateway. Per SSL/TLS (HTTPS), sicurezza degli header e routing pubblico, dovresti posizionare un Reverse Proxy davanti ad esso.

Opzione A: Server Caddy

Ideale per: Deployment di produzione moderni, facilità d’uso.

Caddy è l’unico server web che ottiene e rinnova automaticamente i certificati SSL (Let’s Encrypt) per impostazione predefinita. Richiede quasi zero configurazione.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opzione B: Nginx

Ideale per: Ambienti enterprise, routing complesso.

Nginx è lo standard industriale per il bilanciamento del carico ad alte prestazioni. Usalo se hai già un’infrastruttura Nginx. Dovrai gestire Certbot manualmente.

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

Opzione C: Ngrok

Ideale per: Sviluppo locale, demo, test dei webhook.

Ngrok crea un tunnel sicuro da internet pubblico direttamente al tuo portatile senza configurare firewall. Ideale per mostrare il tuo lavoro ai colleghi all’istante.

./ngrok http 8080

Checklist di produzione

Termina TLS sul reverse proxy e inoltra X-Forwarded-Proto e X-Forwarded-For.
Imposta TRUSTED_PROXIES in PgArachne con i range IP/CIDR dei tuoi proxy.
Disattiva il buffering sulle rotte SSE e usa read timeout sufficientemente lunghi per lo streaming.
Esponi le metriche solo internamente (default 127.0.0.1:9090) e fai scrape dalla rete di monitoraggio.

Esempio hardening Nginx (SSE, download di file, header forwarded)

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;
}

# SSE: /{API_PREFIX}/{database}/sse — long-lived stream, must not be buffered
location ~ ^/db/[^/]+/sse$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 1h;
}

# File downloads: /{API_PREFIX}/{database}/file — large files and ZIP archives
location ~ ^/db/[^/]+/file/?$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

Sostituisci db con il tuo API_PREFIX se lo hai modificato.

Download di grandi dimensioni (`/file`) dietro un reverse proxy

Disattiva il buffering delle risposte (proxy_buffering off in Nginx). Un singolo file viene inviato con Content-Length, un archivio ZIP viene trasmesso in streaming senza. Con il buffering attivo, Nginx scrive prima l’intera risposta in un file temporaneo, ritardando l’inizio del download e consumando spazio su disco.
Aumenta il read timeout (proxy_read_timeout, default 60 s) se la funzione del database che costruisce i file può durare più a lungo — PgArachne non invia nulla finché la funzione non ha restituito tutte le righe.
Non comprimere application/zip né i tipi di media già compressi (gzip su uno ZIP consuma solo CPU).
Limite di memoria: PgArachne tiene in memoria le righe di una risposta (limitate da FILE_MAX_BYTES, default 64 MiB, e FILE_MAX_ENTRIES); dimensiona i limiti in base al numero di download concorrenti previsti. client_max_body_size riguarda solo la piccola richiesta JSON, non il download.
Caddy trasmette le risposte in streaming per impostazione predefinita; non è necessaria alcuna configurazione aggiuntiva.

← Sicurezza e Autenticazione Codici di Errore →

Deployment e HTTPS