How is a Swarm stack file different from a regular docker-compose.yml?

It uses the same Compose file syntax, but only the deploy: key (replicas, update_config, placement, resources) is honored by `docker stack deploy`, while `docker compose up` ignores deploy: on its own. This generator focuses specifically on the deploy: fields Swarm actually reads.

What does update_config's 'order' field control?

'stop-first' stops the old task before starting its replacement (safer for stateful services that can't run two instances at once, but causes a brief gap), while 'start-first' starts the new task before stopping the old one (zero-downtime, but requires your service to tolerate two versions running briefly).

What are placement constraints for?

They restrict which nodes in the Swarm a service's tasks can be scheduled on, expressed as key == value or key != value pairs against node metadata, for example `node.role == worker` to keep a service off manager nodes, or `node.labels.zone == us-east` to pin it to a labeled group of nodes.

Why does the secrets section say 'external: true'?

This generator references secrets that were already created directly in the Swarm (via `docker secret create`) rather than defined inline in the stack file, so the stack references them by name with external: true instead of pointing at a local file.

Docker Swarm Stack Generator - Replicas, Rolling Updates, Placement

Overview

Introduction

Rolling out a service update across a Swarm cluster without downtime depends on getting the deploy: section of a stack file right, parallelism, delay, and update order all affect how much disruption a deployment causes.

This tool generates a docker stack deploy YAML with the deploy: fields Swarm actually reads, replicas, update_config, placement constraints, an overlay network, and secret references, from a simple form.

What Is Docker Swarm Stack Generator?

A generator for the Docker Swarm stack file format used by `docker stack deploy -c stack.yml <stack-name>`, focused on the fields that only Swarm honors: deploy.replicas, deploy.update_config, and deploy.placement.constraints.

It also declares a shared overlay network (Swarm's cross-host networking driver) and references external secrets created ahead of time with `docker secret create`.

How Docker Swarm Stack Generator Works

The service's replica count, update parallelism, update delay, and update order are written under deploy.update_config, matching the exact keys Swarm's scheduler reads when rolling out a new image version.

Placement constraints are rendered as a list of raw strings (e.g. `node.role == worker`) under deploy.placement.constraints, and the overlay network and any secrets are declared at the stack's top level with `driver: overlay` and `external: true` respectively.

When To Use Docker Swarm Stack Generator

Use it when deploying a service to an existing Docker Swarm cluster and you want the update_config and placement fields set up correctly on the first try, since a wrong `order` value can mean unwanted downtime.

It's also useful for documenting a specific deployment strategy (e.g. one-at-a-time rolling updates with a 30-second delay) in a reviewable, versioned stack file.

Often used alongside Docker Compose Generator, Docker Secrets Generator and Docker Healthcheck Generator.

Features

Advantages

Focuses specifically on the deploy: fields Swarm actually reads, rather than the full Compose spec most of which Swarm ignores.
Makes the update order tradeoff (stop-first vs start-first) an explicit choice instead of relying on Swarm's default.
Declares secrets as external references, matching the recommended practice of creating secrets out-of-band rather than inline in a stack file.

Limitations

Assumes the Swarm cluster, overlay network driver, and any referenced secrets already exist; this tool only generates the stack file, not the cluster setup.
Doesn't validate that a placement constraint's key/value actually matches real node labels in your cluster.
Only supports one service per generated file; for multi-service stacks, generate each service and merge the services: blocks by hand.

Examples

A web service with zero-downtime rolling updates

Input

serviceName: web, image: myapp:1.4.0, replicas: 4, updateParallelism: 1, updateDelay: 15s, updateOrder: start-first, constraints: [node.role == worker], overlayNetwork: app-net, secrets: [db_password]

Output

version: "3.8"

services:
  web:
    image: myapp:1.4.0
    deploy:
      replicas: 4
      update_config:
        parallelism: 1
        delay: 15s
        order: start-first
      placement:
        constraints:
          - node.role == worker
    networks:
      - app-net
    secrets:
      - db_password

networks:
  app-net:
    driver: overlay

secrets:
  db_password:
    external: true

start-first ensures new tasks are healthy before old ones stop, avoiding a capacity dip during the rollout.

Best Practices & Notes

Best Practices

Use `start-first` for stateless, horizontally scaled services so a rolling update never drops below full capacity.
Keep update parallelism low (1 or 2) for services with few replicas, updating too many tasks at once can cause a capacity dip if something goes wrong mid-rollout.
Pin image tags to a specific version rather than :latest, so a rollback (docker service rollback) has a known-good previous tag to return to.

Developer Notes

The output targets Compose file version 3.8, the version most widely supported by current Swarm deployments for the deploy: schema used here. Secrets and networks are always declared as `external: true` / overlay respectively, since this generator assumes cluster-level resources are provisioned separately from the stack file, matching how most teams manage Swarm secrets and networks as shared infrastructure rather than per-stack resources.

Docker Swarm Stack Generator Use Cases

Deploying a new service to an existing Swarm cluster with a defined rolling-update strategy
Documenting placement rules that keep a service off manager nodes or pinned to labeled worker nodes
Wiring a service up to an existing overlay network and previously created Swarm secrets

Common Mistakes

Leaving update order at the default (stop-first) for a service that needs zero-downtime deploys, causing brief unavailability on every rollout.
Setting replicas higher than the cluster has capacity for, causing tasks to sit in a pending state instead of running.
Referencing a secret or network name that hasn't actually been created in the cluster yet with `docker secret create` / `docker network create --driver overlay`.

Tips

Use the Docker Secrets Generator to see the exact `docker secret create` command for any secret you reference here.
Pair with the Docker Healthcheck Generator so Swarm's rolling update can actually detect an unhealthy new task before continuing the rollout.

Docker Swarm Stack Generator