Docker Compose: Nginx as a reverse proxy

A reverse proxy puts a single front door in front of one or more apps: the client talks to Nginx and Nginx forwards the request to the right service over the internal network. This guide sets up the minimum to understand it (Nginx in front of an app) and spends most of the time on the hard part: diagnosing a 502.

compose.yaml: app behind Nginx

The app does not publish a port: it only exposes it to the internal network. Nginx is the only one that publishes a port to the host, and bound to loopback.

services:
  app:
    build: .
    restart: unless-stopped
    expose:
      - "3000"
  nginx:
    image: nginx:1.27-alpine
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost/ || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

And the nginx.conf we mount at conf.d/default.conf (a single server block; the image already ships the http wrapper):

server {
    listen 80;

    location / {
        proxy_pass http://app:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The key: proxy_pass to the service name

proxy_pass http://app:3000; is what does the proxying. app is the service name in the compose, and 3000 the internal port it listens on. It is not localhost: inside the Nginx container, localhost would be Nginx itself. The X-Forwarded-* headers tell your app who the original client was and whether it came over HTTP or HTTPS.

Diagnosing a 502 Bad Gateway

A 502 means Nginx is alive but cannot talk to the app. Work through it in order:

• Are the name and port right? proxy_pass must point at the exact service name and the internal port (app:3000), not the host-published port.
• Is the app up? docker compose ps and docker compose logs app. If it crashed or is still starting, Nginx has nothing to forward to.
• Does the app listen on 0.0.0.0? If your app listens on 127.0.0.1 inside the container, it only accepts itself; Nginx cannot get in. It must listen on 0.0.0.0 (all container interfaces).
• Test from inside: docker compose exec nginx wget -qO- http://app:3000 tells you whether Nginx reaches the app over the internal network.

TLS and when to switch tools

Here we serve plain HTTP: TLS (certificates, 443 redirect, renewal) is out of scope. Hand-written Nginx is transparent and great for learning or a simple proxy. If you manage many dynamic services or want automatic HTTPS without fighting config, look at Caddy (automatic TLS, minimal config) or Traefik(dynamic label-based discovery). The choice depends on how much automation you need, not on one being "better" in the abstract.

Next steps

Get the starting Nginx service in the Docker Compose generator and head back to the examples index to see how it fits with your app or database.