Deployment e HTTPS

3 min de leitura

O PgArachne foi projetado para fazer uma coisa bem: API Gateway. Para SSL/TLS (HTTPS), segurança de cabeçalhos e roteamento público, você deve colocar um Proxy Reverso na frente dele.

Opção A: Caddy Server

Melhor para: Deployments de produção modernos, facilidade de uso.

Caddy é o único servidor web que obtém e renova certificados SSL (Let's Encrypt) automaticamente por padrão. Requer quase zero configuração.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opção B: Nginx

Melhor para: Ambientes corporativos, roteamento complexo.

Nginx é o padrão da indústria para balanceamento de carga de alta performance. Utilize esta opção se você já possui uma infraestrutura Nginx. Será necessário gerenciar o Certbot manualmente.

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

Opção C: Ngrok

Melhor para: Desenvolvimento local, demos, testes de webhook.

Ngrok cria um túnel seguro da internet pública diretamente para o seu computador local sem configurar firewalls. Ideal para apresentar seu trabalho aos colegas instantaneamente.

./ngrok http 8080

Checklist de produção

Encerre o TLS no proxy reverso e encaminhe X-Forwarded-Proto e X-Forwarded-For.
Defina TRUSTED_PROXIES no PgArachne com os intervalos IP/CIDR dos seus proxies.
Desative o buffering nas rotas SSE e use timeouts de leitura suficientemente longos para streaming.
Exponha as métricas apenas internamente (padrão 127.0.0.1:9090) e faça scrape pela rede de monitoramento.

Exemplo de hardening Nginx (SSE, downloads de arquivos, cabeçalhos encaminhados)

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

Substitua db pelo seu API_PREFIX caso o tenha alterado.

Downloads grandes (`/file`) atrás de um reverse proxy

Desative o buffering de respostas (proxy_buffering off no Nginx). Um único arquivo é enviado com Content-Length; um arquivo ZIP é transmitido em streaming sem ele. Com o buffering ativado, o Nginx primeiro grava toda a resposta em um arquivo temporário, o que atrasa o início do download e consome espaço em disco.
Aumente o timeout de leitura (proxy_read_timeout, padrão 60 s) se a função do banco de dados que gera os arquivos puder demorar mais — o PgArachne não envia nada até que a função tenha retornado todas as linhas.
Não comprima application/zip nem tipos de mídia já comprimidos (gzip em um ZIP apenas gasta CPU).
Limite de memória: o PgArachne mantém em memória as linhas de uma resposta (limitadas por FILE_MAX_BYTES, padrão 64 MiB, e FILE_MAX_ENTRIES); dimensione os limites conforme o número de downloads simultâneos esperado. client_max_body_size diz respeito apenas à pequena requisição JSON, não ao download.
Caddy transmite as respostas em streaming por padrão; nenhuma configuração adicional é necessária.

← Segurança e Autenticação Códigos de Erro →

Deployment e HTTPS