Docker Swarm Stack File Builder

A Docker Swarm stack file builder that generates a docker stack deploy-ready compose v3.8 file. Each service gets a full deploy block — replicas, placement constraints, a safe rolling-update policy, restart rules, and resource limits — plus external secret references and an overlay network tying the cluster together.

How it works

A stack file looks like a compose file but adds a deploy section that only Swarm interprets. For every service the builder emits replicas, an optional placement.constraints list, and an update_config using order: start-first with failure_action: rollback so deploys add capacity before removing it and self-heal on failure. A restart_policy retries failed tasks, and a resources block sets CPU and memory limits and reservations.

Secrets you list per service are referenced under each service and collected into a top-level secrets: block marked external: true — meaning you create them once in the cluster with docker secret create and never store their values in the file. All services join a single top-level overlay network so they can reach each other by name across nodes.

Tips and notes

• Run docker stack deploy on a manager node. Workers cannot deploy stacks, and the overlay network requires Swarm mode to be active.
• Create secrets first: echo "value" | docker secret create db_password -. The external: true reference will fail to deploy if the secret does not already exist.
• Keep update_config.parallelism at 1 for stateful services so you never take down more than one replica at a time; raise it for stateless services to deploy faster.
• Placement constraints are AND-ed together. Use node labels (docker node update --label-add tier=app node1) to target specific hardware tiers cleanly.

Anatomy of a generated stack file

The builder produces a file structured like this:

version: "3.8"

services:
  web:
    image: myrepo/web:latest
    deploy:
      replicas: 3
      placement:
        constraints:
          - node.role == worker
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first
        failure_action: rollback
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
      resources:
        limits:
          cpus: "0.50"
          memory: 256M
        reservations:
          memory: 128M
    ports:
      - "80:80"
    secrets:
      - db_password
    networks:
      - overlay_net

secrets:
  db_password:
    external: true

networks:
  overlay_net:
    driver: overlay

Each field has a specific purpose. replicas tells the Swarm scheduler how many task copies to run — it will spread them across healthy worker nodes. order: start-first starts the new version before draining the old, keeping capacity constant during a deploy. failure_action: rollback returns to the previous image if too many tasks fail to start, without requiring manual intervention.

Deploying and updating

Copy the generated file to a Swarm manager node and run:

docker stack deploy -c stack.yml mystack

To update the stack after pushing a new image, just re-run the same command. Swarm compares the new spec against the running one and performs a rolling update only for services whose spec changed. To check the rolling update status:

docker service ls
docker service ps mystack_web

To roll back manually to the previous image:

docker service rollback mystack_web

Secrets management before deploying

External secrets must already exist in the cluster before you deploy. Create them with:

echo "mysecretvalue" | docker secret create db_password -

List current secrets: docker secret ls. Remove one: docker secret rm db_password. Secrets are mounted read-only into containers at /run/secrets/<name> — read them from that path in your application rather than from environment variables, which are easier to leak.