Docker Swarm in Production: Secrets, Stack Deploy, Portainer

Docker Swarm in Production: Secrets, Stack Deploy, and Portainer

In the first article, we brought up a cluster, got to know manager and worker nodes, ran a service across several nodes at once, and updated it with no downtime through a rolling update. That's already enough for a demo, but not for real production: database passwords there would still have to be passed as plain environment variables, services were deployed one at a time with the docker service create command, and planned node maintenance would mean that node's tasks simply disappeared along with it.

This article closes exactly those gaps. The practical goal: deploy a real stack consisting of the application, the database, and Nginx all at once, with a single docker stack deploy command, with passwords stored as secrets rather than plain text, and look at the result not just through the terminal but through Portainer's web interface too.

2. Docker secrets

2.1 What a secret is

A secret is an encrypted blob of data, stored in the same Raft log that manager nodes use to agree on the state of the whole cluster (section 3.7 of the first article). Unlike an environment variable from the .env file in article 4 of the main series, a secret is only accessible to the containers it was explicitly assigned to when the service was created; the rest of the cluster doesn't even know it exists.

2.2 How a secret gets into the container

A secret is mounted inside the container as a file on the temporary tmpfs filesystem, at the path /run/secrets/<secret_name>. This is a fundamental difference from an ordinary bind mount or named volume from article 2 of the main series: tmpfs lives in RAM, so the secret never lands on the worker node's disk, neither explicitly nor as a side trace in some temporary file.

2.3 How this differs from .env

The .env file from article 4 of the main series sits on disk in plain text: anyone with access to the host's filesystem can simply read it. A secret, by contrast, is encrypted both in transit between cluster nodes and at rest in the Raft log on manager nodes.

2.4 Limitations

The secrets mechanism works only in Swarm mode. A plain docker run outside the cluster doesn't support the --secret flag at all; that's one more reason moving to Swarm isn't just a matter of tacking docker stack deploy on top of an old compose file with no other changes.

3. Docker configs

3.1 What a config is

A config is a mechanism conceptually similar to a secret, but for data that isn't sensitive: nginx.conf, app.ini, and other settings files. Unlike a secret, a config is stored in Raft unencrypted, and that's a deliberate architectural choice, not an oversight: configs get read and inspected far more often than secrets, and encrypting them wouldn't add any real security.

3.2 How a config gets into the container

A config is mounted into the container as an ordinary file at a given path, replacing the bind-mounted host configuration we used in article 3 of the main series for nginx.conf.

3.3 The advantage over a bind mount in a cluster

In article 3, the Nginx config was mounted from a specific path on a specific host; that worked because there was only one host. In Swarm, a service replica can land on any node in the cluster, and keeping an identical copy of nginx.conf on every node by hand is unnecessary, fragile work. A config solves this at the architecture level: the file is stored once for the whole cluster, not separately on every node, and Swarm itself delivers it to wherever the replica actually ends up running.

3.4 Limitations

A config isn't meant for sensitive data. A database password or an API token, even if it would technically fit inside a config, belongs in a secret instead, precisely because a config is stored in Raft without encryption.

4. Secrets vs. Configs vs. .env: When to Use What

The rule is simple: if leaking a value would hurt someone, it's a secret; if not, it's a config. .env stays fine for local development and for single-host Compose from articles 1-5, but in a Swarm cluster, for real passwords, its place is taken by docker secret.

5. docker stack deploy

5.1 The basic command

docker stack deploy -c docker-compose.yml mystack

This command deploys the entire compose file as a single stack in the cluster, unlike docker service create from the first article, which created only one service at a time.

5.2 What a stack is

A stack is a named collection of everything described in one compose file: services, networks, volumes, secrets, and configs together. The name mystack from the command above becomes the prefix for the names of every resource created inside the cluster, much like a project name in Compose (article 2 of the main series) became the prefix for container names on a single host.

5.3 Differences from docker compose up

Two things change right away. First, the build: instruction is completely ignored; Swarm doesn't build images itself, it needs an image that's already in a registry, on the same principle we described for automatic deployment in article 4 of the main series. Second, a new deploy: block appears inside each service; that's exactly what determines how the service behaves within the cluster (section 6).

5.4 Updating an already deployed stack

Calling the same docker stack deploy -c docker-compose.yml mystack command again with an updated file applies the changes automatically through a rolling update, just like docker service update from the first article, only for the whole stack at once rather than one service at a time by hand.

6. The deploy Block in a Compose File

A full example of a stack, the application, the database, and Nginx, with all the key elements of sections 2 through 6 together:

services:
  app:
    image: registry.example.com/myapp:v3
    environment:
      DATABASE_URL_FILE: /run/secrets/db_password
    secrets: [db_password]
    networks: [app-net]
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
        failure_action: rollback
      resources:
        limits:
          memory: 384m
      restart_policy:
        condition: on-failure
        delay: 5s
      placement:
        constraints: [node.role == worker]

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes: [pgdata:/var/lib/postgresql/data]
    networks: [app-net]
    deploy:
      placement:
        constraints: [node.labels.env == prod]

  nginx:
    image: nginx:alpine
    configs:
      - source: nginx_conf
        target: /etc/nginx/conf.d/default.conf
    ports: ["80:80", "443:443"]
    networks: [app-net]
    deploy:
      replicas: 2

secrets:
  db_password:
    external: true

configs:
  nginx_conf:
    external: true

volumes:
  pgdata:

networks:
  app-net:
    driver: overlay

6.1 replicas

A direct continuation of section 7 of the first article: how many replicas of the service Swarm should keep running at once.

6.2 update_config

The same rolling-update parameters from section 9 of the first article (parallelism, delay, failure_action), now written declaratively in a file instead of passed as command flags in the terminal.

6.3 resources.limits

The same memory and CPU limiting mechanism we covered in article 3 of the main series through deploy.resources.limits in plain Compose; here it works identically, just applied to every replica of the service in the cluster.

6.4 restart_policy

The declarative counterpart to --restart-condition from section 10.2 of the first article: under what condition (on-failure, any, none) and with what delay Swarm restarts a task that went down.

6.5 placement.constraints

Placement constraints, something missing from section 10.3 of the first article, where scheduling was described as fully automatic by default. node.role == worker ties a service exclusively to worker nodes, leaving the manager untouched; node.labels.env == prod relies on an arbitrary label set beforehand with docker node update --label-add env=prod <node>, handy for example to keep the database only on nodes with SSD storage marked with that label.

6.6 secrets and configs inside a service

The short form secrets: [db_password] attaches an already created secret to the service; the long form under configs with source and target lets you explicitly set the path the file ends up at inside the container, which is exactly how nginx_conf lands at the familiar /etc/nginx/conf.d/default.conf that Nginx used back in article 3.

6.7 *_FILE variables: a bridge between env and secret

The official postgres image, and most modern applications, support a _FILE suffix on an environment variable's name: instead of the value itself, the application receives a path to a file and reads the password from there. That's exactly how POSTGRES_PASSWORD_FILE: /run/secrets/db_password lets the official PostgreSQL image reconcile the Swarm secret file with its own expectation of a POSTGRES_PASSWORD variable from article 2 of the main series, without the password itself ever appearing in plain text in the process environment.

7. Draining a Node: Maintenance with No Downtime

7.1 The command

docker node update --availability drain <node>

This command puts a node into drain mode: Swarm moves every task that was running on it to other available nodes in the cluster and stops scheduling anything new on it.

7.2 When it's needed

Planned maintenance, an OS update, updating Docker Engine itself, rebooting the server, used to mean every task on that node simply disappeared along with it, relying only on the self-healing from section 10.1 of the first article. Draining lets you do this in a controlled way: first carefully move the load off, then service the node with no impact at all on the running services.

7.3 Bringing it back into rotation

docker node update --availability active <node>

Once maintenance is finished, this command returns the node to rotation; Swarm can schedule new tasks on it again.

7.4 An analogy with Kubernetes

For anyone familiar with the other orchestration ecosystem: draining in Swarm is essentially kubectl cordon and kubectl drain from Kubernetes, combined into a single command instead of two separate steps.

8. Portainer: A Web Interface for the Cluster

8.1 What it is

Portainer is a web interface for managing Docker and Swarm, which deploys itself as an ordinary service inside the cluster.

8.2 What it shows

One interface shows what used to require separate terminal commands: docker node ls from the first article, as a list of nodes; docker service ls and docker service ps, as a list of services and tasks; plus images, volumes, and secrets, all in one place with no switching between SSH sessions on different nodes.

8.3 Why a team needs it

The main practical advantage: not every team member needs direct SSH and CLI access to every node in the cluster just to check the current state. Someone can check whether a rolling update went through successfully just by opening a page in a browser.

8.4 Limitations of the free version

Portainer Community Edition (free) supports only one environment, meaning one Swarm cluster per Portainer instance. Managing several separate clusters from a single interface requires the paid Business Edition.

9. Conclusion and Mini-Series Summary

This article finished what was missing after the first part: database passwords are now passed through docker secret instead of sitting in plain text; the Nginx configuration lives in the cluster as a docker config instead of being copied by hand to every node; the whole stack, the application, the database, Nginx, is deployed and updated with a single docker stack deploy command; planned node maintenance no longer means losing the tasks that were running on it; and the cluster's state can be seen in a browser without SSHing into any of the nodes.

Looking at both articles in the mini-series together: we went from the bare docker swarm init command to a full production cluster with secure secret storage and a convenient web interface for the whole team, all built on the same Docker Engine we first installed back in article 1 of the "Docker on a VPS" main series.

When even this isn't enough, the cluster has outgrown roughly 10-15 nodes, you need horizontal autoscaling driven by actual load, your own CRDs and operators, or strict multi-tenant isolation between teams, the logical next step lies beyond Swarm, toward Kubernetes. But for the vast majority of self-hosted projects on a handful of VPS, Swarm, which we've just learned to run, remains a sufficient and noticeably simpler solution for day-to-day operation.

Frequently Asked Questions