Nginx como reverse proxy para contenedores Docker: guía práctica

Crea la red proxy-net:

docker network create proxy-net

Esto aparece en docker network ls con driver bridge. Puedes verificar con docker network inspect proxy-net — estará vacía por ahora.

Crea el directorio de trabajo del 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 los server blocks por dominio. certs es donde vivirán los certificados emitidos. vhost permite override por host. html sirve el ACME challenge de Let’s Encrypt.

Crea /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 le dice a Compose que la red ya existe (la creamos en el paso 01) — sin esto, crea una nueva con prefijo del nombre del proyecto y tu Nginx no ve los backends.

Crea un server block default en 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 es el código no-estándar de Nginx que cierra la conexión sin respuesta — útil para rechazar requests con Host desconocido (bots escaneando IP directamente).

Levanta Nginx:

docker compose up -d
docker compose logs nginx

Los logs deben mostrar start worker processes sin error. Si aparece bind() to 0.0.0.0:80 failed, algo en el host está en el puerto — vuelve atrás e investiga antes de continuar.

Agrega proxy-net al compose de cada backend. Ejemplo para una API:

services:
  api:
    image: mi-api:latest
    container_name: api-backend
    restart: unless-stopped
    networks:
      - default
      - proxy-net
    # NOTA: sin `ports:` — no publica en el host

networks:
  proxy-net:
    external: true

Recrea el contenedor: docker compose up -d --force-recreate. Mantiene la red default para dependencias internas (base de datos, redis) y agrega proxy-net para ser alcanzable por Nginx.

Valida que Nginx ve el backend por su nombre:

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

Una respuesta con IP 172.x.x.x significa que el DNS de la red funciona. bad address significa que el backend no está en proxy-net — vuelve atrás y revisa el docker network inspect proxy-net.

Crea conf.d/api.ejemplo.com.conf:

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

server {
    listen 80;
    server_name api.ejemplo.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.ejemplo.com;

    ssl_certificate     /etc/nginx/certs/api.ejemplo.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/api.ejemplo.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;
    }
}

El upstream con nombre y keepalive 32 mantiene un pool de conexiones reutilizables hacia el backend — reduce la latencia en 5-15ms por request frente a abrir un nuevo TCP cada vez. proxy_http_version 1.1

• Connection "" son obligatorios para que keepalive funcione.

Emite el certificado para cada dominio:

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.ejemplo.com \
  --email [email protected] \
  --agree-tos --no-eff-email

Los archivos fullchain.pem y privkey.pem aparecen en /opt/nginx-proxy/certs/live/api.ejemplo.com/. Ajusta el ssl_certificate del server block para apuntar a live/ en lugar de la ruta que puse en el ejemplo (que era simplificada).

Valida la config y recarga:

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

nginx -t parsea todo sin aplicar — si aparece un error de sintaxis o un archivo de cert no encontrado, rechaza el reload y mantiene la config anterior corriendo. Cero downtime garantizado.