Gremoire

Guide to Using Docker Swarm with Docker Stack ​

Docker Swarm offers a lightweight and streamlined approach to container orchestration. When combined with Docker Stack, it becomes a powerful tool for deploying complex applications with configuration, scaling, and service discovery—without the overwhelming complexity of tools like Kubernetes.

This article walks through how to set up Docker Swarm, configure a cluster, deploy services through Docker Stack, and manage configurations and secrets.

1. Initializing Docker Swarm ​

Choose a machine that will act as the manager node.

docker swarm init --advertise-addr <MANAGER-IP>

Docker will output a command allowing other nodes to join the cluster as workers:

docker swarm join --token <token> <MANAGER-IP>:2377

You can verify the cluster state using:

docker node ls

2. Creating an Overlay Network ​

Swarm services communicate over an overlay network. Create one with:

docker network create -d overlay mynet

3. Writing a Docker Stack File ​

A Docker Stack file (similar to a declarative manifest) defines your services, configs, secrets, and networks. Below is an example setup that includes an API service and a MySQL database.

yaml
version: "3.8"

services:
  api:
    image: your-api-image:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 5s
      restart_policy:
        condition: on-failure
    ports:
      - "8080:8080"
    configs:
      - source: api_conf
        target: /app/config.json
    secrets:
      - db_password
    networks:
      - mynet

  db:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_password
      - MYSQL_DATABASE=appdb
    volumes:
      - dbdata:/var/lib/mysql
    secrets:
      - db_password
    networks:
      - mynet

configs:
  api_conf:
    file: ./config.json

secrets:
  db_password:
    file: ./secrets/db_pass.txt

networks:
  mynet:
    external: true

volumes:
  dbdata:

Prepare the needed files:

mkdir secrets
echo "mypassword" > secrets/db_pass.txt
echo '{ "port": 8080 }' > config.json

4. Deploying the Stack ​

Deploy the stack using:

docker stack deploy -c docker-stack.yml mystack

Check deployed services:

docker stack services mystack

Check running tasks:

docker stack ps mystack

5. Scaling Services ​

Adjust service replicas dynamically:

docker service scale mystack_api=5

Docker Swarm spreads replicas across nodes automatically.

6. Updating a Stack ​

Apply updates to your stack (new configs, images, etc.) by re-deploying:

docker stack deploy -c docker-stack.yml mystack

Watch the rolling update:

docker service ps mystack_api

7. Working with Configs and Secrets ​

Docker Swarm mounts configs and secrets as read-only files inside containers.

Configs: Appear where you target them (e.g., /app/config.json).

Secrets: Always appear under /run/secrets/<name>.

8. Removing the Stack ​

To remove deployed services:

docker stack rm mystack

To leave the swarm:

docker swarm leave --force

9. Useful Commands ​

docker stack ls

docker service ls

docker service logs -f mystack_api

docker node ls

10. Workflow Summary ​

A typical Docker Swarm + Stack workflow:

  1. Build your container image.
  2. Push it to a registry.
  3. Define services using a stack file.
  4. Deploy with docker stack deploy.
  5. Allow Swarm to handle rolling updates and scaling.
  6. Monitor and adjust as needed.

This combination offers a clean, efficient orchestration experience suited for small to medium deployments, edge clusters, and developers who want power without complexity.