Déploiement & HTTPS

3 min de lecture

Déploiement & HTTPS

PgArachne est conçu pour faire une seule tâche bien : API Gateway. Pour le SSL/TLS (HTTPS), la sécurité des en-têtes et le routage public, il convient de placer un reverse proxy devant.

Option A : Serveur Caddy

Idéal pour : Déploiements de production modernes, facilité d’utilisation.

Caddy est le seul serveur web qui obtient et renouvelle les certificats SSL (Let’s Encrypt) automatiquement par défaut. Il ne nécessite presque aucune configuration.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Option B : Nginx

Idéal pour : Environnements d’entreprise, routage complexe.

Nginx est la norme industrielle pour l’équilibrage de charge (load balancing) haute performance. Utilisez-le si vous avez déjà une infrastructure Nginx. Vous devrez gérer Certbot manuellement.

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

Option C : Ngrok

Idéal pour : développement local, démonstrations, tests de webhook.

Ngrok crée un tunnel sécurisé depuis l’internet public directement vers votre ordinateur portable sans configurer de pare-feu. Idéal pour montrer votre travail à des collègues instantanément.

./ngrok http 8080

Checklist de production

Terminez TLS sur le reverse proxy et transférez X-Forwarded-Proto et X-Forwarded-For.
Définissez TRUSTED_PROXIES dans PgArachne avec les plages IP/CIDR de vos proxies.
Désactivez le buffering sur les routes SSE et utilisez des délais de lecture (read timeouts) suffisamment longs pour le streaming.
Exposez les métriques uniquement en interne (défaut 127.0.0.1:9090) et collectez-les depuis le réseau de supervision.

Exemple de durcissement Nginx (SSE, téléchargements de fichiers, en-têtes transférés)

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

Remplacez db par votre API_PREFIX si vous l’avez modifié.

Gros téléchargements (`/file`) derrière un reverse proxy

Désactivez la mise en tampon des réponses (proxy_buffering off dans Nginx). Un fichier seul est envoyé avec un Content-Length, une archive ZIP est transmise en flux sans celui-ci. Avec la mise en tampon activée, Nginx écrit d’abord toute la réponse dans un fichier temporaire, ce qui retarde le début du téléchargement et consomme de l’espace disque.
Augmentez le délai de lecture (proxy_read_timeout, 60 s par défaut) si la fonction de base de données qui construit les fichiers peut s’exécuter plus longtemps — PgArachne n’envoie rien tant que la fonction n’a pas renvoyé toutes les lignes.
Ne compressez pas application/zip ni les autres types de médias déjà compressés (gzip sur un ZIP ne fait que consommer du CPU).
Limite mémoire : PgArachne garde en mémoire les lignes d’une réponse (plafonnées par FILE_MAX_BYTES, 64 MiB par défaut, et FILE_MAX_ENTRIES) ; dimensionnez les limites selon le nombre de téléchargements simultanés attendus. client_max_body_size ne concerne que la petite requête JSON, pas le téléchargement.
Caddy transmet les réponses en flux par défaut ; aucune configuration supplémentaire n’est nécessaire.

← Sécurité & Authentification Codes d’erreur →

Déploiement & HTTPS