Skip to content
Tutorials Center
My learning

Topics

Lesson 66 of 111 ยท Docker Compose

Project: A Full-Stack App with Compose

Build a four-service stack with Compose: nginx, a Python API, PostgreSQL and Redis, with healthchecks, networks, a named volume and a .env file. Every step tested.

This project puts the whole Compose section to work. You will build a small "notes" application made of four services: an nginx front door, a Python API, a PostgreSQL database and a Redis cache. Along the way you wire up healthchecks and startup order, two networks, a named volume, a .env file for configuration, and a non-root image for the API. At the end you will prove that the data survives docker compose down and that the database is not reachable from the proxy.

Everything shown here was built and run on Docker 29 with Compose v5. The files are complete; you can copy them into an empty folder and run the commands in order.

TEXT
          browser
             |  127.0.0.1:18102
        +----v-----+
        |   web    |  nginx: static page + reverse proxy
        +----+-----+
             |  network "front"
        +----v-----+
        |   api    |  Python, port 8000, non-root
        +--+----+--+
           |    |    network "back" (internal: no outside access)
     +-----v-+ +v------+
     |  db   | | cache |
     |  PG17 | | Redis |
     +---+---+ +-------+
         |
     volume "dbdata"

The project layout

TEXT
notes/
  compose.yaml
  .env
  api/
    Dockerfile
    requirements.txt
    app.py
  web/
    default.conf
    index.html

Step 1: The API

The API is deliberately small: it uses only the standard library's HTTP server plus two drivers, so you can read all of it. It offers four routes: GET /health (checks both backends), GET /hits (counts visits in Redis), GET /notes and POST /notes (stored in PostgreSQL).

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

import psycopg
import redis

DATABASE_URL = os.environ["DATABASE_URL"]
cache = redis.Redis.from_url(os.environ["REDIS_URL"], decode_responses=True)


def init_db() -> None:
    with psycopg.connect(DATABASE_URL) as conn:
        conn.execute(
            "CREATE TABLE IF NOT EXISTS notes ("
            "id serial PRIMARY KEY, body text NOT NULL, "
            "created_at timestamptz NOT NULL DEFAULT now())"
        )


class Handler(BaseHTTPRequestHandler):
    def send_json(self, status: int, payload) -> None:
        body = json.dumps(payload).encode()
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self) -> None:
        if self.path == "/health":
            with psycopg.connect(DATABASE_URL) as conn:
                conn.execute("SELECT 1")
            cache.ping()
            self.send_json(200, {"status": "ok"})
        elif self.path == "/hits":
            self.send_json(200, {"hits": cache.incr("hits")})
        elif self.path == "/notes":
            with psycopg.connect(DATABASE_URL) as conn:
                rows = conn.execute("SELECT id, body FROM notes ORDER BY id").fetchall()
            self.send_json(200, [{"id": r[0], "body": r[1]} for r in rows])
        else:
            self.send_json(404, {"error": "not found"})

    def do_POST(self) -> None:
        if self.path != "/notes":
            self.send_json(404, {"error": "not found"})
            return
        length = int(self.headers.get("Content-Length", 0))
        body = json.loads(self.rfile.read(length) or b"{}").get("body", "")
        with psycopg.connect(DATABASE_URL) as conn:
            row = conn.execute(
                "INSERT INTO notes (body) VALUES (%s) RETURNING id", (body,)
            ).fetchone()
        self.send_json(201, {"id": row[0], "body": body})

    def log_message(self, fmt, *args) -> None:
        print("api:", fmt % args, flush=True)


if __name__ == "__main__":
    init_db()
    print("api: listening on 8000", flush=True)
    ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()

Two design choices are worth noticing. The connection strings come from environment variables, so the same image runs anywhere (Configuring Containers). And the table is created on startup with CREATE TABLE IF NOT EXISTS, a simple stand-in for migrations that is safe to run every time.

TEXT
# api/requirements.txt
psycopg[binary]==3.3.6
redis==6.2.0

The Dockerfile follows the habits from Dockerfile Best Practices: dependencies first for caching, then the code, then a non-root user.

DOCKERFILE
# api/Dockerfile
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1
WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY app.py .

RUN useradd --system --uid 10001 app
USER app

EXPOSE 8000
CMD ["python", "app.py"]

I first tried the moving tag python:3-slim with a pinned psycopg 3.2.9 and the build failed: No matching distribution found for psycopg-binary==3.2.9. The newest Python had no prebuilt wheel for that older driver release. Pinning the interpreter (3.13-slim) together with the library versions is what makes a build reproducible. See Choosing a Base Image.

Step 2: The web tier

nginx serves one static page and forwards everything under /api/ to the API. Inside the Compose network, api is simply a host name (Containers Talking to Each Other).

NGINX
# web/default.conf
server {
    listen 80;

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

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

The trailing slash in proxy_pass http://api:8000/; matters: it makes nginx strip the /api/ prefix, so /api/notes reaches the API as /notes.

HTML
<!-- web/index.html -->
<!doctype html>
<title>Notes</title>
<h1>Notes</h1>
<p>Try <a href="/api/notes">/api/notes</a> and <a href="/api/hits">/api/hits</a>.</p>

Step 3: Configuration in .env

Compose automatically reads a file called .env next to compose.yaml and uses it to fill ${...} placeholders in the Compose file.

INI
# .env  (never commit real secrets)
POSTGRES_PASSWORD=change-me-locally
WEB_PORT=18102

Add .env to .gitignore and commit a .env.example with fake values instead. The lesson Environment, Variables and Secrets covers this in depth, and Managing Secrets explains why a plain environment variable is only acceptable for local work.

Step 4: The Compose file

YAML
# compose.yaml
name: tcd-b10-fs

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:${WEB_PORT:-8080}:80"
    volumes:
      - ./web/default.conf:/etc/nginx/conf.d/default.conf:ro
      - ./web/index.html:/usr/share/nginx/html/index.html:ro
    depends_on:
      api:
        condition: service_healthy
    networks:
      - front
    restart: unless-stopped

  api:
    build: ./api
    environment:
      DATABASE_URL: postgresql://notes:${POSTGRES_PASSWORD}@db:5432/notes
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=2)"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 5s
    networks:
      - front
      - back
    restart: unless-stopped

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: notes
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: notes
    volumes:
      - dbdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U notes -d notes"]
      interval: 5s
      timeout: 3s
      retries: 10
    networks:
      - back
    restart: unless-stopped

  cache:
    image: redis:alpine
    command: ["redis-server", "--save", "", "--appendonly", "no"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - back
    restart: unless-stopped

networks:
  front:
  back:
    internal: true

volumes:
  dbdata:

Read it from the bottom up, because the design is in the details:

  • Two networks. web is only on front; db and cache are only on back; api is the bridge between them. The proxy therefore cannot even resolve the database's name. back is internal: true, so nothing on it can reach the outside world either (Networks and Volumes in Compose).
  • Only one published port, and it is bound to 127.0.0.1, so the stack is not exposed on your LAN. ${WEB_PORT:-8080} uses the value from .env and falls back to 8080.
  • Healthchecks plus condition: service_healthy build a startup chain: the database and cache must be healthy before the API starts, and the API must be healthy before the proxy starts (Startup Order and Health). The API's check uses Python itself because the slim image has no curl.
  • A named volume dbdata keeps PostgreSQL's files outside the container.
  • Redis has persistence turned off (--save "" --appendonly no): this is a cache, and losing it must be harmless. We will see the consequence below.
  • restart: unless-stopped brings services back after a crash or a Docker restart.

Step 5: Validate and start

Check the file before starting anything:

CONSOLE
$ docker compose config --quiet; echo "exit code: $?"
exit code: 0

Now build and start the stack. The first run downloads images and installs the Python packages, so it takes a minute.

CONSOLE
$ docker compose up -d --build
 Volume tcd-b10-fs_dbdata Created
 Network tcd-b10-fs_back Created
 Network tcd-b10-fs_front Created
 Container tcd-b10-fs-cache-1 Created
 Container tcd-b10-fs-db-1 Created
 Container tcd-b10-fs-api-1 Created
 Container tcd-b10-fs-web-1 Created
 Container tcd-b10-fs-cache-1 Started
 Container tcd-b10-fs-db-1 Started
 Container tcd-b10-fs-cache-1 Healthy
 Container tcd-b10-fs-db-1 Healthy
 Container tcd-b10-fs-api-1 Started
 Container tcd-b10-fs-api-1 Healthy
 Container tcd-b10-fs-web-1 Started

Read the order: cache and database start first, wait until Healthy, then the API starts, becomes Healthy, and only then does the web container start. That is depends_on with health conditions doing its job.

CONSOLE
$ docker compose ps
NAME                 IMAGE                COMMAND                  SERVICE   CREATED          STATUS                    PORTS
tcd-b10-fs-api-1     tcd-b10-fs-api       "python app.py"          api       13 seconds ago   Up 6 seconds (healthy)    8000/tcp
tcd-b10-fs-cache-1   redis:alpine         "docker-entrypoint.sโ€ฆ"   cache     13 seconds ago   Up 12 seconds (healthy)   6379/tcp
tcd-b10-fs-db-1      postgres:17-alpine   "docker-entrypoint.sโ€ฆ"   db        13 seconds ago   Up 12 seconds (healthy)   5432/tcp
tcd-b10-fs-web-1     nginx:alpine         "/docker-entrypoint.โ€ฆ"   web       12 seconds ago   Up 1 second               127.0.0.1:18102->80/tcp

Only web shows a published port (127.0.0.1:18102->80/tcp); the 8000/tcp, 5432/tcp and 6379/tcp entries are just ports the images declare, reachable inside the networks only.

Step 6: Use it

Everything goes through nginx on port 18102:

CONSOLE
$ curl -s http://127.0.0.1:18102/api/health
{"status": "ok"}
$ curl -s http://127.0.0.1:18102/api/hits
{"hits": 1}
$ curl -s http://127.0.0.1:18102/api/hits
{"hits": 2}
$ curl -s -X POST -d '{"body":"buy milk"}' http://127.0.0.1:18102/api/notes
{"id": 1, "body": "buy milk"}
$ curl -s -X POST -d '{"body":"write lesson"}' http://127.0.0.1:18102/api/notes
{"id": 2, "body": "write lesson"}
$ curl -s http://127.0.0.1:18102/api/notes
[{"id": 1, "body": "buy milk"}, {"id": 2, "body": "write lesson"}]

The counter lives in Redis; the notes live in PostgreSQL. Read the combined logs of the API to see the requests arrive:

CONSOLE
$ docker compose logs --no-log-prefix --tail 4 api
api: "GET /hits HTTP/1.1" 200 -
api: "POST /notes HTTP/1.1" 201 -
api: "POST /notes HTTP/1.1" 201 -
api: "GET /notes HTTP/1.1" 200 -

The paths are /hits and /notes, without /api: nginx removed the prefix. You can also ask the database directly:

CONSOLE
$ docker compose exec db psql -U notes -c 'SELECT count(*) FROM notes'
 count
-------
     2
(1 row)

Step 7: Prove the design

Restarts and down keep the data

Restart only the API and read the notes again; then remove the whole stack with down (no -v) and bring it back:

CONSOLE
$ docker compose restart api
$ curl -s http://127.0.0.1:18102/api/notes
[{"id": 1, "body": "buy milk"}, {"id": 2, "body": "write lesson"}]
$ docker compose down
 Network tcd-b10-fs_back Removed
 Network tcd-b10-fs_front Removed
$ docker compose up -d
$ curl -s http://127.0.0.1:18102/api/notes
[{"id": 1, "body": "buy milk"}, {"id": 2, "body": "write lesson"}]
$ curl -s http://127.0.0.1:18102/api/hits
{"hits": 1}

The notes survived because they sit on the dbdata volume. The hit counter, however, restarted at 1: Redis kept it only in memory and its container was replaced. That is exactly what we configured, and it is the right trade-off for a cache. If you cannot afford to lose something, it belongs in the database.

(The new containers need a few seconds to become healthy after up -d; wait for docker compose ps to show healthy before sending requests, or add --wait to up.)

The network boundaries hold

From inside the proxy, the database does not even have a name:

CONSOLE
$ docker compose exec web sh -c 'wget -qO- -T2 http://db:5432 ; echo rc=$?'
wget: bad address 'db:5432'
rc=1

And the internal network is flagged as such:

CONSOLE
$ docker network inspect tcd-b10-fs_back --format '{{.Internal}}'
true

The API sits on both networks, and front is a normal network, so the API can reach the internet (a request to example.com from inside it returned status 200). internal: true only isolates db and cache. If your API should not call out, put it on internal networks only and give the proxy a path to it, or add egress rules at the firewall.

A dependency failure is visible

Stop the database and call the API:

CONSOLE
$ docker compose stop db
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18102/api/notes
502

nginx answers 502 Bad Gateway because the API crashed the request when it could not connect and closed the socket. After about 25 seconds (five failed checks at five-second intervals) docker compose ps marks the API unhealthy, which monitoring can alert on. Start the database again with docker compose up -d and everything recovers by itself. This is the benefit of healthchecks and restart policies working together.

Where to take it next

A real project would add more pieces. None of them changes the shape you just built:

  • Development comfort: a compose.override.yaml with bind mounts and docker compose watch for hot reload (Compose for Development).
  • Production: no source bind mounts, pinned image tags or digests, secrets from files instead of .env (Managing Secrets), a reverse proxy with TLS (Deploying on a Single Host).
  • Migrations: a one-off docker compose run --rm api <migrate command> before up (Compose Commands).
  • Backups: dump the database with docker compose exec db pg_dump or archive the volume (Backup and Restore).

Clean up

When you are finished, -v removes the volume too and --rmi local removes the image Compose built:

CONSOLE
$ docker compose down -v --rmi local
 Network tcd-b10-fs_front Removed
 Network tcd-b10-fs_back Removed

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is the web service attached only to the front network?

    A service only sees names on the networks it is attached to. With web on front alone, the proxy cannot reach db or cache, which limits the damage if the proxy is compromised.
  2. 2. What guarantees that the database accepts connections before the API starts?

    File order does not matter. depends_on with service_healthy makes Compose wait until the healthcheck (pg_isready) passes.
  3. 3. After docker compose down and docker compose up -d, the notes are still there but the hit counter restarted at 1. Why?

    The dbdata named volume survives down. Redis ran with --save "" --appendonly no, so its in-memory counter vanished with the container.
  4. 4. What does the trailing slash in proxy_pass http://api:8000/; do?

    When proxy_pass has a URI part (even just /), nginx substitutes the matched location prefix with it. Without the slash the full /api/notes path would be forwarded.
  5. 5. Which command removes the containers, networks AND the database volume of the project?

    down leaves named volumes in place. Only down -v deletes them, along with the data inside.

Summary

  • A full stack is a few services, two or three networks, one named volume and a .env file; Compose turns it into one docker compose up -d.
  • Put each tier on the networks it needs: proxy on front, API on both, data stores on an internal back network.
  • Healthchecks with depends_on: condition: service_healthy give you a reliable startup order.
  • Publish as little as possible, and bind published ports to 127.0.0.1 unless you really want LAN access.
  • Named volumes survive down; only down -v deletes them. Keep caches disposable and real data in the database.
  • Pin interpreter and library versions together, run as a non-root user, and validate the file with docker compose config --quiet.

Next: Container Security Basics