Docker Swarm Stack Generator

Docker Swarm stack generator - a manifest ready for review

The Docker Swarm stack generator creates a stack.yml file for one replicated service. Enter an image with an explicit tag or digest, ports and node constraints, and the tool assembles deploy, a rolling update with rollback, resources, external secrets and an optional overlay network.

The stack uses Compose 3.8 syntax because docker stack deploy still consumes the legacy Compose v3 format. This is not a local docker compose up file: Swarm interprets replicas, placement and the routing mesh across a cluster. For a development environment, start with the Docker Compose generator.

What goes into the generated YAML

Image tags and a non-root user

docker stack deploy does not build an image from a build field. Build it in CI, push it to a registry, then enter a full reference such as registry.example.com/api:1.4.2. The generator rejects a missing tag, latest, whitespace and attempts to append another YAML line. For immutable releases, replace a tested tag with @sha256:....

A Swarm manifest cannot set the Dockerfile USER instruction. The process inside the image should run under an unprivileged account and copied artifacts should belong to that account. Create a secure image baseline with the Dockerfile generator.

Deploying the stack step by step

1. Label every node referenced by constraints, for example docker node update --label-add env=production worker-1.
2. Create the secrets named at the end of the YAML. Never commit the source password files.
3. Authenticate nodes to a private registry, or pass --with-registry-auth during deployment.
4. Save the output as stack.yml and check indentation in the YAML validator.
5. Run docker stack deploy --with-registry-auth -c stack.yml myapp, then inspect docker stack services myapp and docker service ps myapp_myapp.

Ingress ports, overlay networking and internal services

A published port greater than zero creates long syntax with ingress mode. The routing mesh accepts traffic on every node and forwards it to an available replica. A zero value omits ports completely; there is no misleading expose, because services sharing the overlay can already reach the container port.

The overlay network connects tasks on different hosts. The generator does not make it attachable, so standalone containers cannot join without a reason. In a larger system, separate frontend and backend networks instead of putting every service in one communication domain.

Healthcheck, rolling update and rollback

The probe runs wget against 127.0.0.1 and /health. Change the path if the application uses another endpoint, or disable it for a worker or database. Valid YAML cannot guarantee a valid probe: the binary must exist in the image and the endpoint should not depend on a remote service.

An update starts one new replica at a time, observes it for 30 seconds and enters rollback after the first failure. The start-first order temporarily needs capacity for old and new tasks. Reservations guide scheduling, while limits prevent one container from consuming a whole host.

Secret and placement security

The generator declares secrets as external: true. It never places their values in environment variables, labels or image layers. The application reads the appropriate file from /run/secrets/<name>. To rotate one, create a new versioned secret and update the service because a secret object is immutable.

Every constraint must be a single key == value or key != value expression. The tool quotes each value in YAML and rejects extra instructions. Constraints do not replace capacity monitoring: an overly narrow label set leaves tasks pending. To compare orchestrators, open the Kubernetes Deployment generator.

Frequently asked questions