Skip to content
Tutorials Center
My learning

Topics

Lesson 104 of 111 ยท Projects

Project: Multiple Apps Behind a Proxy

Put one nginx reverse proxy in front of several containers: path-based and host-based routing, forwarded headers, DNS pitfalls, plus the same setup in Caddy.

A server usually has one public front door, but behind it you may want several applications: a documentation site, an API, an admin panel. A reverse proxy is that front door. It accepts every request on one port and forwards each one to the right container based on the URL path or the host name.

In this project you will build that with nginx and Docker Compose. You will route by path (/docs/, /api/) and by host name (admin.localhost), pass the client information to the backends, learn the DNS trap that makes nginx refuse to start, and see what happens when a backend goes down. At the end the same setup is shown in Caddy. Everything was run on Docker 29 with Compose v5.

TEXT
                          +--> docs   (nginx:alpine, static files)
 browser --> gateway:80 --+--> api    (Python, port 8000)
   127.0.0.1:18153        +--> admin  (nginx:alpine, static files)

 /docs/...             -> docs
 /api/...              -> api
 Host: admin.localhost -> admin

Only gateway publishes a port. The three backends are reachable only through it, on Compose's default network.

The project layout

TEXT
proxy-demo/
  compose.yaml
  nginx.conf
  docs/index.html
  admin/index.html
  api/server.py

Step 1: Three small backends

The two static sites each have a one-page index.html:

HTML
<!-- docs/index.html -->
<!doctype html>
<title>Docs</title>
<h1>Documentation site</h1>
<p>Served by the docs container.</p>
HTML
<!-- admin/index.html -->
<!doctype html>
<title>Admin</title>
<h1>Admin panel</h1>
<p>Served by the admin container.</p>

The API is a few lines of Python that answers every GET request with a JSON description of what it received. This is a handy trick when you build proxies: a backend that tells you what the proxy actually sent.

Python
# api/server.py
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps(
            {
                "service": "api",
                "path": self.path,
                "host": self.headers.get("Host"),
                "x_forwarded_for": self.headers.get("X-Forwarded-For"),
                "x_forwarded_proto": self.headers.get("X-Forwarded-Proto"),
            }
        ).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, fmt, *args):
        pass


ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Step 2: The proxy configuration

NGINX
# nginx.conf
resolver 127.0.0.11 valid=10s;

server {
    listen 80 default_server;
    server_name _;

    location = / {
        default_type text/plain;
        return 200 "gateway: try /docs/ or /api/\n";
    }

    location /docs/ {
        set $docs_upstream http://docs:80;
        rewrite ^/docs/(.*)$ /$1 break;
        proxy_pass $docs_upstream;
    }

    location /api/ {
        set $api_upstream http://api:8000;
        rewrite ^/api/(.*)$ /$1 break;
        proxy_pass $api_upstream;
        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;
    }
}

server {
    listen 80;
    server_name admin.localhost;

    location / {
        set $admin_upstream http://admin:80;
        proxy_pass $admin_upstream;
    }
}

Read it block by block:

  • Two server blocks. nginx picks the block whose server_name matches the request's Host header; default_server catches everything else. That is how one port serves several sites (nginx and Reverse Proxies).
  • location blocks choose by path. /docs/ and /api/ are prefixes: the rewrite ... break line strips the prefix, so /api/items reaches the API as /items.
  • proxy_set_header lines tell the backend who the real client was. Without them the API would see only the proxy's address. X-Forwarded-For carries the client address, X-Forwarded-Proto says whether the visitor used http or https, and Host keeps the original host name.
  • resolver 127.0.0.11 and the set $x http://... variables look odd. They are deliberate and explained in Step 5.

Step 3: The Compose file

YAML
# compose.yaml
name: tcd-b15-proxy

services:
  gateway:
    image: nginx:alpine
    ports:
      - "127.0.0.1:18153:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - docs
      - api
      - admin
    restart: unless-stopped

  docs:
    image: nginx:alpine
    volumes:
      - ./docs:/usr/share/nginx/html:ro

  admin:
    image: nginx:alpine
    volumes:
      - ./admin:/usr/share/nginx/html:ro

  api:
    image: python:3.13-slim
    command: ["python", "/srv/server.py"]
    volumes:
      - ./api/server.py:/srv/server.py:ro
    user: "10001:10001"

No Dockerfile is needed. Stock images plus read-only bind mounts (Bind Mounts) are enough for configuration and static files. Note what is missing: the backends have no ports. They exist only on the project network. The API additionally runs as an unprivileged user via user:.

The nginx image replaces its default site when you mount a file at /etc/nginx/conf.d/default.conf. The mount is :ro, which makes the image's start script print a harmless "can not modify default.conf (read-only file system?)" info line.

Step 4: Start and test

CONSOLE
$ docker compose config --quiet && echo ok
ok
$ docker compose up -d
 Container tcd-b15-proxy-api-1 Started
 Container tcd-b15-proxy-docs-1 Started
 Container tcd-b15-proxy-admin-1 Started
 Container tcd-b15-proxy-gateway-1 Started
$ docker compose ps
NAME                      IMAGE              COMMAND                  SERVICE   CREATED         STATUS         PORTS
tcd-b15-proxy-admin-1     nginx:alpine       "/docker-entrypoint.โ€ฆ"   admin     8 seconds ago   Up 5 seconds   80/tcp
tcd-b15-proxy-api-1       python:3.13-slim   "python /srv/server.โ€ฆ"   api       8 seconds ago   Up 7 seconds
tcd-b15-proxy-docs-1      nginx:alpine       "/docker-entrypoint.โ€ฆ"   docs      8 seconds ago   Up 7 seconds   80/tcp
tcd-b15-proxy-gateway-1   nginx:alpine       "/docker-entrypoint.โ€ฆ"   gateway   8 seconds ago   Up 4 seconds   127.0.0.1:18153->80/tcp

Only the gateway has a 127.0.0.1:...->80/tcp mapping. Now request each route:

CONSOLE
$ curl -s http://127.0.0.1:18153/
gateway: try /docs/ or /api/
$ curl -s http://127.0.0.1:18153/docs/
<!doctype html>
<title>Docs</title>
<h1>Documentation site</h1>
<p>Served by the docs container.</p>
$ curl -s http://127.0.0.1:18153/api/items?x=1
{"service": "api", "path": "/items?x=1", "host": "127.0.0.1", "x_forwarded_for": "172.21.0.1", "x_forwarded_proto": "http"}
$ curl -s -H 'Host: admin.localhost' http://127.0.0.1:18153/
<!doctype html>
<title>Admin</title>
<h1>Admin panel</h1>
<p>Served by the admin container.</p>

The API's reply proves the proxy did its job: the path arrived as /items?x=1 (prefix removed, query kept), the Host header is the one the client sent, and the forwarded headers are set. 172.21.0.1 is the address Docker's network gateway gives to traffic that enters through a published port on Docker Desktop. It is not your real address, and it will differ on your machine. On a Linux server you would normally see the real client address instead.

For the admin site we used -H 'Host: admin.localhost' to select the second server block. In a browser, http://admin.localhost:18153/ works the same way, because browsers resolve *.localhost to your own machine. For real domains you would point DNS records at the server instead.

An unknown path gets the backend's own answer:

CONSOLE
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18153/docs/missing.html
404

That 404 comes from the docs container, passed through the proxy unchanged.

Step 5: The DNS trap

Now the reason for the strange resolver and set $var lines. nginx normally resolves the host names in proxy_pass once, when it starts. If a name cannot be resolved at that moment, nginx refuses to run at all. Here is a simpler configuration that looks natural and is what most examples show:

NGINX
server {
    listen 80;

    location /docs/ {
        proxy_pass http://docs:80/;
    }

    location /api/ {
        proxy_pass http://api:8000/;
    }
}

With all services up it works. But if the docs container is stopped (or not created yet) when the proxy starts, the proxy dies immediately:

CONSOLE
$ docker compose stop docs
$ docker run -d --name tcd-b15-t --network tcd-b15-proxy_default \
    -v "$PWD/nginx-static.conf:/etc/nginx/conf.d/default.conf:ro" nginx:alpine
$ docker logs tcd-b15-t 2>&1 | grep emerg
2026/10/23 15:34:19 [emerg] 1#1: host not found in upstream "docs" in /etc/nginx/conf.d/default.conf:5
nginx: [emerg] host not found in upstream "docs" in /etc/nginx/conf.d/default.conf:5

Even if every backend is up at start-up, there is a second problem: nginx caches the address it found. If a backend container is recreated and gets a new IP, the proxy keeps talking to the old one and answers 502 Bad Gateway until you reload it.

The cure is what our configuration does. When the target is a variable (set $api_upstream http://api:8000; then proxy_pass $api_upstream;), nginx resolves it at request time using the resolver. Docker's embedded DNS server for user-defined networks always lives at 127.0.0.11 (Docker Networking, User-Defined Bridge Networks). A variable in proxy_pass also means nginx no longer rewrites the URI for you, so we remove the prefix ourselves with the rewrite ... break line.

See the difference when a backend dies and comes back:

CONSOLE
$ docker compose stop api
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18153/api/x
502
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18153/docs/
200
$ docker compose start api
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18153/api/x
200

While the API was down, only its route failed. The proxy kept serving /docs/, and when the API returned, the proxy found it again without a restart. The error log tells you why requests fail:

CONSOLE
$ docker compose logs --no-log-prefix --tail 4 gateway
2026/10/23 15:31:31 [error] 21#21: *15 api could not be resolved (3: Host not found), client: 172.21.0.1, server: _, request: "GET /api/x HTTP/1.1", host: "127.0.0.1:18153"
172.21.0.1 - - [23/Oct/2026:15:31:31 +0000] "GET /api/x HTTP/1.1" 502 157 "-" "curl/8.22.0" "-"
172.21.0.1 - - [23/Oct/2026:15:31:31 +0000] "GET /docs/ HTTP/1.1" 200 101 "-" "curl/8.22.0" "-"
172.21.0.1 - - [23/Oct/2026:15:31:36 +0000] "GET /api/x HTTP/1.1" 200 115 "-" "curl/8.22.0" "-"

A stopped container disappears from Docker's DNS, so nginx reports "Host not found". Use this when you debug a 502: check that the service is running and healthy first (Troubleshooting Networks).

The valid=10s option makes nginx re-ask Docker's DNS every ten seconds instead of using the record's TTL. Lower numbers react faster to replaced containers, higher numbers save lookups. Ten seconds is a sensible default for a small stack.

Step 6: Change the config without downtime

Edit nginx.conf, test the new file, and tell nginx to reload it. A reload starts new workers with the new configuration and lets the old ones finish their requests, so no connection is dropped.

CONSOLE
$ docker compose exec gateway nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
$ docker compose exec gateway nginx -s reload

If nginx -t reports an error, do not reload: fix the file first. A reload with a broken file is refused and the old configuration stays active, but a container restart with a broken file leaves you with no proxy at all.

From inside the gateway you can also test a backend directly, bypassing the routing rules, which separates "the backend is broken" from "my routing is wrong":

CONSOLE
$ docker compose exec gateway wget -qO- http://api:8000/hello
{"service": "api", "path": "/hello", "host": "api:8000", "x_forwarded_for": null, "x_forwarded_proto": null}

Notice x_forwarded_for is null here: no proxy was involved in that request, which confirms the header in the earlier answer came from nginx.

The same thing in Caddy

Caddy is a web server whose configuration is much shorter and which obtains HTTPS certificates automatically for real domain names. Here is the same routing as a Caddyfile:

TEXT
:80 {
	handle_path /docs/* {
		reverse_proxy docs:80
	}
	handle_path /api/* {
		reverse_proxy api:8000
	}
	handle {
		respond "gateway: try /docs/ or /api/" 200
	}
}

http://admin.localhost {
	reverse_proxy admin:80
}

handle_path removes the matched prefix, like our rewrite. Caddy resolves backend names when a request arrives, so it does not suffer from the start-up trap above, and it sets X-Forwarded-For and X-Forwarded-Proto by itself. Run it on the same network, mounting the file at /etc/caddy/Caddyfile:

CONSOLE
$ docker run -d --name tcd-b15-caddy --network tcd-b15-proxy_default \
    -p 127.0.0.1:18154:80 -v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro" caddy:alpine
$ curl -s http://127.0.0.1:18154/api/items
{"service": "api", "path": "/items", "host": "127.0.0.1:18154", "x_forwarded_for": "172.21.0.1", "x_forwarded_proto": "http"}

The result is identical for the client. In Compose you would simply replace the gateway service's image with caddy:alpine and the mount with the Caddyfile. Traefik is a third popular choice: it reads routing rules from container labels, so adding a service needs no proxy config file (nginx and Reverse Proxies).

Production notes

This local setup leaves out several things a public server needs. Treat this list as a checklist (Deploying on a Single Host):

  • TLS. Terminate HTTPS at the proxy: certificates from Let's Encrypt (automatic in Caddy, via certbot or similar for nginx), listen 443 ssl, and a redirect from port 80.
  • Publish deliberately. The proxy publishes 80 and 443 on all interfaces; every backend stays unpublished. Check with docker compose ps that nothing else shows a host port (Publishing Ports).
  • Trust forwarded headers carefully. X-Forwarded-For can be forged by a client. Applications should only trust it when it was set by their proxy.
  • Limits and timeouts. Set client_max_body_size, proxy_read_timeout and rate limits to match your apps.
  • Health. Add healthchecks to the backends and depends_on conditions so the proxy starts after them (Startup Order and Health).

Clean up

CONSOLE
$ docker compose down --rmi local
 Network tcd-b15-proxy_default Removed

The stack used stock images only, so there was nothing to delete beyond the containers and the network.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of the request does nginx use to choose between two server blocks on the same port?

    Name-based virtual hosting: nginx compares the request's Host header with each block's server_name, and falls back to the default_server block.
  2. 2. A config with a plain proxy_pass http://docs:80/; makes nginx exit at start-up with host not found in upstream. When does that happen?

    nginx resolves fixed host names in proxy_pass once, at start-up. A missing name is a fatal error. Using a variable plus resolver 127.0.0.11 moves the lookup to request time.
  3. 3. What is 127.0.0.11 in the nginx resolver directive?

    Containers on user-defined networks (including Compose's default network) send DNS queries to the embedded server at 127.0.0.11, which knows the service names.
  4. 4. Why does the gateway set X-Forwarded-For and X-Forwarded-Proto?

    From the backend's point of view every connection comes from the proxy. These headers carry the information the proxy knows about the real client.
  5. 5. Which of these statements about the backends in this project is true?

    Only the gateway has a ports entry. The other services are reachable on the Compose network by service name, but not from outside.

Summary

  • A reverse proxy gives many containers one public entry point and routes by URL path or by Host header.
  • Publish only the proxy's port, bound to 127.0.0.1 locally; keep backends unpublished on the project network.
  • Pass client information with Host, X-Real-IP, X-Forwarded-For and X-Forwarded-Proto, and make backends trust those headers only from their own proxy.
  • nginx resolves fixed upstream names once at start-up. Use resolver 127.0.0.11 with a variable in proxy_pass so that missing or recreated containers cause a 502 for one route instead of a dead proxy.
  • Test a config with nginx -t and apply it with nginx -s reload; use a backend that echoes requests to see what the proxy really sends.
  • Caddy does the same job in fewer lines and handles HTTPS certificates for you; Traefik routes from container labels.

Next: Project: A Tiny Go Image