Nginx reverse proxy for Docker containers: a practical guide

Create the proxy-net network:

docker network create proxy-net

This shows up in docker network ls as a bridge driver. You can check it with docker network inspect proxy-net — it will be empty for now.

Create the reverse proxy working directory:

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 holds the server blocks per domain. certs is where issued certificates will live. vhost allows per-host override. html serves the Let’s Encrypt ACME challenge.

Create /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 tells Compose the network already exists (we created it in step 01) — without it, Compose creates a new one prefixed with the project name and your Nginx won’t see the backends.

Create a default server block at 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 is Nginx’s non-standard code that closes the connection without a response — useful for rejecting requests with unknown Host (bots scanning the IP directly).

Bring up Nginx:

docker compose up -d
docker compose logs nginx

The logs should show start worker processes without errors. If bind() to 0.0.0.0:80 failed appears, something on the host is on the port — go back and investigate before continuing.

Add proxy-net to each backend’s compose. Example for an API:

services:
  api:
    image: my-api:latest
    container_name: api-backend
    restart: unless-stopped
    networks:
      - default
      - proxy-net
    # NOTE: no `ports:` — does not publish on the host

networks:
  proxy-net:
    external: true

Recreate the container: docker compose up -d --force-recreate. Keep the default network for internal dependencies (database, redis) and add proxy-net to be reachable by Nginx.

Validate that Nginx sees the backend by name:

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

A response with IP 172.x.x.x means the network DNS is working. bad address means the backend isn’t on proxy-net — go back and check docker network inspect proxy-net.

Create conf.d/api.example.com.conf:

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

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

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

A named upstream with keepalive 32 maintains a pool of reusable connections to the backend — it reduces latency by 5-15ms per request compared to opening a new TCP every time. proxy_http_version 1.1 + Connection "" is mandatory for keepalive to work.

Issue the certificate for each domain:

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

The fullchain.pem and privkey.pem files appear at /opt/nginx-proxy/certs/live/api.example.com/. Adjust the ssl_certificate in the server block to point to live/ instead of the path I used in the example (which was simplified).

Validate the config and reload:

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

nginx -t parses everything without applying — if a syntax error or a missing cert file appears, it refuses the reload and keeps the previous config running. Zero downtime guaranteed.