Docker Swarm Stack Deployment Guide

Docker Swarm is Docker's built-in orchestration mode for running multi-container applications across multiple hosts. A stack is a group of services defined in a Docker Compose file and deployed as a unit to a Swarm cluster.

This guide covers the practical workflow: initializing a Swarm, deploying a stack, and managing it remotely via docker context.

Initialize a Swarm

On the machine you want as the manager node:

docker swarm init

This outputs a join token. To add worker nodes:

# Get the worker join token (run on the manager)
docker swarm join-token worker

# Run the outputted command on each worker node
docker swarm join --token <token> <manager-ip>:2377

Deploy a Stack

A stack uses a Docker Compose file. Deploy with:

docker stack deploy -c docker-compose.yml mystack

If you're pulling from a private registry and need to pass credentials:

docker stack deploy -c docker-compose.yml mystack --with-registry-auth

Deploying Remotely with Docker Context

Instead of SSH-ing into your server to run Docker commands, create a context that points to the remote host:

# Create a context for a remote server
docker context create production --docker "host=ssh://deploy@your-server.com"

# Switch to that context
docker context use production

# All subsequent docker commands run on the remote server
docker stack deploy -c docker-compose.yml mystack

# Switch back to local
docker context use default

Managing Stacks and Services

docker stack ls                           # list all stacks
docker stack services mystack             # list services in a stack
docker stack ps mystack                   # list tasks (containers) in a stack
docker stack rm mystack                   # remove a stack

docker service ls                         # list all services
docker service logs mystack_web -f        # stream logs for a service
docker service inspect mystack_web        # detailed service info

Scaling Services

# Scale a service to 3 replicas
docker service scale mystack_web=3

# Or update the service
docker service update --replicas 3 mystack_web

Rolling Updates and Rollbacks

Docker Swarm performs rolling updates by default when you redeploy:

docker stack deploy -c docker-compose.yml mystack   # redeploy with updated image

Roll back to the previous version:

docker service rollback mystack_web

Managing Secrets

Docker secrets store sensitive values (passwords, API keys) securely and inject them into containers as files:

# Create a secret from a string
printf 'your-db-password' | docker secret create db_password -

# Create a secret from a file
docker secret create ssl_cert ./cert.pem

# List secrets
docker secret ls

Use secrets in your Compose file:

version: "3.8"
services:
  db:
    image: postgres:15
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    external: true

The secret is mounted at /run/secrets/db_password inside the container.

Setting Up a Dedicated Deploy User

For secure remote deployments, create a restricted user on the server that can only run Docker commands:

# On the server
adduser deploy
usermod -aG docker deploy

# Switch to deploy user
su - deploy

# Set up SSH
mkdir -p .ssh
chmod 700 .ssh

Add your public key to ~/.ssh/authorized_keys. To restrict the key to Docker-only access, prefix it with a command directive:

command="docker system dial-stdio" ssh-ed25519 AAAA... your-key-comment

Generate a deploy key on your CI/CD machine:

ssh-keygen -t ed25519 -C "deploy@your-server.com" -f ~/.ssh/deploy_key

Conclusion

Docker Swarm is a straightforward path to multi-host container deployment without the complexity of Kubernetes. Use docker context to manage remote Swarms from your local machine, Swarm secrets for sensitive configuration, and rolling updates to deploy without downtime. For larger multi-team deployments with more advanced scheduling needs, Kubernetes is the natural next step.