Migrate from Docker Swarm

Docker Swarm is officially deprecated. This guide walks through moving from a Swarm cluster to a dockmesh-managed fleet.

Key conceptual differences

Swarm	dockmesh
Manager nodes + workers	Single server + outbound agents
docker service	Stacks (Compose)
docker secret	dockmesh env var secrets or external Vault
Overlay networks	Host-local networks + explicit cross-host via service mesh if needed
Routing mesh	Per-host published ports + reverse proxy
docker stack deploy	Git-backed stacks or dockmesh UI deploy

dockmesh is not Swarm. If you need distributed networking where a container on host A can reach a container on host B via internal DNS, you need Kubernetes or a service mesh — not dockmesh.

For 90% of Swarm use cases (small multi-host fleets with mostly independent stacks), dockmesh is a cleaner fit.

Before migrating

Inventory your Swarm workloads:

docker service ls
docker stack ls

For each stack, note:

• Replicas (will become manual scaling in dockmesh)
• Placement constraints (become host tags)
• Secrets used (need migration plan)
• Overlay network connections (needs special attention)

Step 1 — Install dockmesh on a manager node

Pick one of the Swarm manager nodes as your dockmesh server host. Install dockmesh alongside Swarm — they coexist:

curl -fsSL https://get.dockmesh.dev | bash

Step 2 — Enroll worker nodes as agents

On each Swarm worker, install the dockmesh agent using the enrollment token generated in the dockmesh UI. Agents and Swarm can run side-by-side — both talk to the local Docker daemon but don’t conflict.

Tag each host in dockmesh to match your placement constraints:

• If a Swarm service had constraints: [node.labels.type == web], tag the dockmesh host as web
• Same for region, env, etc.

Step 3 — Convert services to Compose stacks

For each docker stack, export the compose file:

# Swarm doesn't have a direct export, so generate from existing service
docker service inspect <svc> > <svc>.json
# Manually reconstruct compose.yaml

Or if you have the original compose files used for docker stack deploy, use those directly — remove Swarm-specific keys:

services:
  web:
    image: nginx
    # REMOVE these Swarm-only keys:
    # deploy:
    #   replicas: 3
    #   mode: replicated
    #   placement:
    #     constraints: [node.labels.type == web]
    #   restart_policy:
    #     condition: any
    # REPLACE with standard Compose:
    restart: unless-stopped
    deploy:
      replicas: 3  # dockmesh respects this for scaling

Step 4 — Handle secrets

Docker Swarm secrets (docker secret create) are file-mounted. dockmesh has three options:

1. Inline env vars — for less-sensitive values, paste into dockmesh env vars (encrypted at rest)
2. File-based — mount a host file as a volume:

   volumes:
     - /opt/secrets/db-password:/run/secrets/db-password:ro

3. External secret manager — Vault, AWS Secrets Manager via a sidecar init container

Plan the move before deploy. Pasting secrets into env vars is the fastest path.

Step 5 — Routing mesh replacement

Swarm’s routing mesh means a request to any node’s exposed port reaches the correct container. dockmesh doesn’t have this — containers are bound to specific hosts.

Options:

• Reverse proxy (recommended) — run Caddy/Traefik on one host as the public entrypoint, reverse proxy to wherever the container lives
• Per-host published ports — accept that the app lives on one host; use a load balancer (HAProxy, cloud LB) in front if you need redundancy
• Service discovery — Consul + Fabio, or Envoy — for apps that need dynamic discovery

Step 6 — Overlay networks

Swarm’s overlay network lets containers on different nodes share a network. dockmesh doesn’t create overlay networks automatically.

Replacements:

• Single-host co-location — move the communicating services to the same host
• Public HTTP APIs — expose via reverse proxy, use that URL (even internally)
• WireGuard / Tailscale mesh — create a flat network between hosts, let containers use host-level IPs

Migrating away from overlay networks often requires architectural changes. Plan carefully.

Step 7 — Deploy in dockmesh

For each converted stack:

1. Stacks → New stack in dockmesh
2. Paste the converted compose.yaml
3. Set env vars
4. Deploy

Test each stack side-by-side with its Swarm counterpart before retiring the Swarm service.

Step 8 — Retire Swarm

Once everything runs on dockmesh:

# On each node, one at a time
docker swarm leave --force
# On the manager
docker swarm leave --force

Your containers now run under plain Docker, managed by dockmesh.

What you lose

• Native overlay networks (workarounds above)
• Routing mesh (replaced by reverse proxy)
• docker service update --image zero-downtime (dockmesh has Stack Migration which is different)
• Built-in service health + auto-reschedule (dockmesh alerts + manual redeploy)

What you gain

• Simpler operational model
• Web UI with logs, terminal, metrics
• RBAC + SSO without paying for Portainer Business
• Compose-native (no more Swarm-specific YAML keys)
• Actively maintained (Swarm isn’t)

See also

• Multi-Host — how dockmesh handles fleets
• Reverse Proxy — replacement for routing mesh
• Stack Migration — moving stacks between hosts post-migration