Nginx como reverse proxy pra containers Docker: guia prático

Crie a network proxy-net:

docker network create proxy-net

Isso aparece em docker network ls como driver bridge. Você pode checar com docker network inspect proxy-net — vai estar vazia por enquanto.

Crie o diretório de trabalho do reverse proxy:

sudo mkdir -p /opt/nginx-proxy/{conf.d,certs,vhost,html}
sudo chown -R $USER:$USER /opt/nginx-proxy
cd /opt/nginx-proxy

conf.d guarda os server blocks por domínio. certs é onde os certificados emitidos vão morar. vhost permite override por host. html serve a ACME challenge do Let’s Encrypt.

Crie /opt/nginx-proxy/docker-compose.yml:

services:
  nginx:
    image: nginx:1.27-alpine
    container_name: nginx-proxy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./certs:/etc/nginx/certs:ro
      - ./vhost:/etc/nginx/vhost.d:ro
      - ./html:/usr/share/nginx/html:ro
    networks:
      - proxy-net

networks:
  proxy-net:
    external: true

external: true diz pro Compose que a network já existe (criamos no passo 01) — sem isso, ele cria uma nova prefixada com nome do projeto e seu Nginx não enxerga os backends.

Crie um server block default em conf.d/default.conf:

server {
    listen 80 default_server;
    server_name _;

    location /.well-known/acme-challenge/ {
        root /usr/share/nginx/html;
    }

    location / {
        return 444;
    }
}

return 444 é o código não-padrão do Nginx que fecha a conexão sem resposta — útil pra rejeitar requests com Host desconhecido (bots scanning IP direto).

Suba o Nginx:

docker compose up -d
docker compose logs nginx

Os logs devem mostrar start worker processes sem erro. Se aparecer bind() to 0.0.0.0:80 failed, alguma coisa no host está na porta — volte e investigue antes de continuar.

Adicione proxy-net ao compose de cada backend. Exemplo pra uma API:

services:
  api:
    image: minha-api:latest
    container_name: api-backend
    restart: unless-stopped
    networks:
      - default
      - proxy-net
    # NOTA: sem `ports:` — não publica no host

networks:
  proxy-net:
    external: true

Recrie o container: docker compose up -d --force-recreate. Mantém a network default pra dependências internas (banco, redis) e adiciona proxy-net pra ser alcançável pelo Nginx.

Valide que o Nginx enxerga o backend pelo nome:

docker exec nginx-proxy ping -c 2 api-backend

Resposta com IP 172.x.x.x significa DNS da network funcionando. bad address significa que o backend não está em proxy-net — volte e confira o docker network inspect proxy-net.

Crie conf.d/api.exemplo.com.conf:

upstream api_backend {
    server api-backend:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name api.exemplo.com;

    location /.well-known/acme-challenge/ {
        root /usr/share/nginx/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name api.exemplo.com;

    ssl_certificate     /etc/nginx/certs/api.exemplo.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/api.exemplo.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    client_max_body_size 50m;

    location / {
        proxy_pass http://api_backend;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection        "";
        proxy_read_timeout 60s;
    }
}

upstream nomeado com keepalive 32 mantém pool de conexões reusáveis pro backend — reduz latência em 5-15ms por request em comparação a abrir TCP novo toda vez. proxy_http_version 1.1 + Connection "" é obrigatório pra keepalive funcionar.

Emita o certificado pra cada domínio:

docker run --rm \
  -v /opt/nginx-proxy/certs:/etc/letsencrypt \
  -v /opt/nginx-proxy/html:/var/www/html \
  certbot/certbot certonly \
  --webroot -w /var/www/html \
  -d api.exemplo.com \
  --email [email protected] \
  --agree-tos --no-eff-email

Os arquivos fullchain.pem e privkey.pem aparecem em /opt/nginx-proxy/certs/live/api.exemplo.com/. Ajuste o ssl_certificate do server block pra apontar pra live/ em vez do path que coloquei no exemplo (que era simplificado).

Valide a config e recarregue:

docker exec nginx-proxy nginx -t
docker exec nginx-proxy nginx -s reload

nginx -t parseia tudo sem aplicar — se aparecer erro de sintaxe ou arquivo de cert não encontrado, ele recusa o reload e mantém a config anterior rodando. Zero downtime garantido.