Despliegue y HTTPS

3 min de lectura

PgArachne está diseñado para realizar bien una sola tarea: API Gateway. Para SSL/TLS (HTTPS), seguridad de encabezados y enrutamiento público, se recomienda colocar un Proxy Inverso delante de él.

Opción A: Servidor Caddy

Mejor para: Despliegues de producción modernos, facilidad de uso.

Caddy es el único servidor web que obtiene y renueva certificados SSL (Let’s Encrypt) automáticamente por defecto. Requiere casi cero configuración.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opción B: Nginx

Mejor para: Entornos empresariales, enrutamiento complejo.

Nginx es el estándar de la industria para balanceo de carga de alto rendimiento. Utilícelo si ya dispone de una infraestructura Nginx. Será necesario gestionar Certbot manualmente.

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

Opción C: Ngrok

Mejor para: Desarrollo local, demostraciones, pruebas de Webhook.

Ngrok crea un túnel seguro desde internet público directamente al equipo local sin necesidad de configurar firewalls. Ideal para mostrar el trabajo a colegas al instante.

./ngrok http 8080

Checklist de producción

Termine TLS en el reverse proxy y reenvíe X-Forwarded-Proto y X-Forwarded-For.
Configure TRUSTED_PROXIES en PgArachne con los rangos IP/CIDR de los proxies.
Desactive el buffering en rutas SSE y utilice read timeouts suficientemente largos para streaming.
Exponga las métricas solo internamente (por defecto 127.0.0.1:9090) y realice el scrape desde la red de monitoreo.

Ejemplo de hardening Nginx (SSE, descargas de archivos, headers 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;
}

Sustituya db por su API_PREFIX si lo ha cambiado.

Descargas grandes (`/file`) detrás de un reverse proxy

Desactive el buffering de respuestas (proxy_buffering off en Nginx). Un archivo individual se envía con Content-Length; un archivo ZIP se transmite en streaming sin él. Con el buffering activado, Nginx primero vuelca toda la respuesta a un archivo temporal, lo que retrasa el inicio de la descarga y consume espacio en disco.
Aumente el read timeout (proxy_read_timeout, por defecto 60 s) si la función de base de datos que genera los archivos puede tardar más — PgArachne no envía nada hasta que la función ha devuelto todas las filas.
No comprima application/zip ni tipos de medios ya comprimidos (gzip sobre un ZIP solo gasta CPU).
Límite de memoria: PgArachne mantiene en memoria las filas de una respuesta (limitado por FILE_MAX_BYTES, por defecto 64 MiB, y FILE_MAX_ENTRIES); dimensione los límites según el número de descargas simultáneas que espere. client_max_body_size solo afecta a la pequeña petición JSON, no a la descarga.
Caddy transmite las respuestas en streaming por defecto; no se necesita configuración adicional.

← Seguridad y Autenticación Códigos de Error →

Despliegue y HTTPS