Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Projects and Practice

Project: Deploy a Complete Web Stack on Swarm

Build and deploy a three-tier stack on Docker Swarm: proxy, API and PostgreSQL with secrets, configs, health checks, placement and a validated stack file, step by step.

In this project you assemble everything from the chapters on secrets, stacks and updates into one production-style deployment: a reverse proxy, a stateless API with several replicas, and a PostgreSQL database with a persistent volume. You will write the stack file, validate it with a small checker, and follow a deployment checklist.

Swarm cannot run on this site. The commands and YAML are therefore read-only, and I show no command output, since I cannot guarantee it. The runnable blocks are Python stand-ins: a stack-file validator and a readiness checklist you can reuse for your own projects.

The goal

flowchart LR
  U["Users"] --> P["proxy (nginx)<br/>3 replicas, port 80"]
  P --> A["api<br/>4 replicas"]
  A --> D["db (postgres)<br/>1 replica, pinned node"]
  A -. "secret db_password" .-> D

Only the proxy publishes a port; the API and database are reachable through overlay networks only.

Requirements:

  • Only the proxy is reachable from outside.
  • The database password is a Swarm secret, never an environment value.
  • The API has a health check and rolls out with start-first.
  • The database runs on exactly one node with a labelled disk and a named volume.
  • Everything is reproducible from one file plus a few commands.

Step 1: prepare the cluster

Terminal
docker node update --label-add role=db node-2
printf 'Ch4nge-Me-Please' | docker secret create db_password_v1 -
docker config create proxy_conf_v1 ./nginx.conf

The proxy configuration forwards to http://api:8080. Because both services are on the same overlay network, Swarm DNS resolves api to the service's virtual IP (Compose Files for Stacks).

Step 2: the stack file

YAML
services:
  proxy:
    image: nginx:1.27
    ports:
      - "80:80"
    networks: [edge]
    configs:
      - source: proxy_conf
        target: /etc/nginx/nginx.conf
    deploy:
      replicas: 3
      update_config: { parallelism: 1, delay: 10s, order: start-first }

  api:
    image: registry.example.com/shop/api:${TAG:?set TAG}
    networks: [edge, data]
    secrets: [db_password]
    environment:
      DB_HOST: db
      DB_PASSWORD_FILE: /run/secrets/db_password
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 20s
    deploy:
      replicas: 4
      resources:
        reservations: { cpus: "0.25", memory: 256M }
        limits: { memory: 512M }
      update_config:
        parallelism: 2
        delay: 10s
        order: start-first
        failure_action: rollback
        monitor: 30s

  db:
    image: postgres:17
    networks: [data]
    secrets: [db_password]
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    deploy:
      replicas: 1
      placement:
        constraints: [node.labels.role == db]
      update_config:
        order: stop-first

networks:
  edge:
  data:

volumes:
  pgdata:

configs:
  proxy_conf:
    external: true
    name: proxy_conf_v1

secrets:
  db_password:
    external: true
    name: db_password_v1

Points worth noticing:

  • The logical name (db_password) stays the same in the file; the name: key maps it to the versioned object, which makes rotation a one-line change.
  • The database uses stop-first, because two PostgreSQL processes must never share one data directory.
  • The data network is not attached to the proxy, so the proxy cannot talk to the database even if compromised.
  • The database image creates the data directory and role on the first start; changing POSTGRES_PASSWORD_FILE afterwards does not change the stored password. Change it with SQL (ALTER ROLE) as part of a rotation.

Step 3: deploy

Terminal
TAG=1.0.0 docker stack deploy -c stack.yml --with-registry-auth shop
docker stack services shop
docker stack ps shop --no-trunc
docker service logs shop_api

If shop_db stays pending, the node label is missing or misspelled. If shop_api tasks are rejected, read the error in docker stack ps: usually a pull failure (Private Registries) or a missing secret.

Step 4: verify

  1. docker stack services shop shows 3/3, 4/4 and 1/1.
  2. Request the proxy on port 80 from any node, because the routing mesh answers on all of them.
  3. Stop one API container on a node (docker kill) and watch Swarm replace it.
  4. Scale the API to six replicas and back (Scaling).
  5. Ship version 1.0.1 with a new TAG and watch the rolling update.

Stand-in: validate the stack

Python Stand-in: a stack-file validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: readiness checklist with a failing item

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Extensions to try

  • Add a Redis cache on the data network with a memory limit.
  • Replace the proxy with a global service so every node answers locally.
  • Add a log-agent global service (Monitoring and Logging).
  • Rotate the database password and verify the application reconnects.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why does the database use update order stop-first?

    Starting a second instance on the same data would risk corruption, so the old one stops first.
  2. 2. Why is the data network not attached to the proxy?

    Least privilege for networks: only the API can reach the database.
  3. 3. What does the name key on an external secret provide?

    The service keeps using db_password while you change which object it maps to.

Summary

  • A realistic stack separates edge and data networks, publishes only the proxy and gives the API health checks and start-first updates.
  • The database is pinned, single-replica and updated stop-first, with its password supplied as a secret.
  • Versioned external secrets and configs make rotation a small, reviewable change.
  • Validate the stack file and checklist before every production deploy.

Next: Project: A Zero-Downtime Release Process