Skip to content

Coming from Docker Swarm

How Swarm concepts, commands, and Compose keys map to an mm cluster.

mm replaces Docker Swarm. It runs a Compose project across several hosts, with encrypted networks and service names that span them, rolling updates that roll back, shared volumes, and one merged log. The nodes run plain Docker Engine, and nothing runs docker swarm init.

This page maps what you know to what you write in mm, lists the Compose keys to change, and gives the order to move a project in. Run a cluster is the guide for the cluster itself.

What works differently

  • No managers, workers, or quorum. Every node is equal. Your machine, or CI, coordinates a deployment and talks to each node's mmd; each mmd changes only its own host. Losing a node never costs the others their ability to deploy.
  • Nothing is rescheduled. A Swarm moves a failed node's tasks elsewhere. mm has no scheduler: a service runs on the nodes its placement names, and a node that goes down comes back with its own services. Place a service on more than one node if it has to survive one.
  • Every change is a plan. mm deploy plan shows what each node will start, change, and stop, and mm deploy apply takes the hash of the plan you read.
  • No routing mesh and no virtual IPs. A service name resolves to the addresses of its healthy containers, and a port is published only on the nodes that run the service.
  • A failed update returns every node. A rollout goes one node at a time, and when a container fails its health check the nodes already changed go back to what they ran before.

Concepts and commands

In a SwarmIn mm
docker swarm init, join, and join tokensList the hosts under targets.<name>.nodes, then run mm target setup. See set up the nodes.
Manager and worker rolesNone. Every node is the same.
docker node lsmm target nodes
Node labels and placement constraintsplacement: on the service: a node, a group from cluster.groups, all, or a list.
docker stack deploymm deploy plan, then mm deploy apply with the plan's hash
A stackA stack: an entry under stacks: that names Compose files.
A replicated servicereplicas: on the service: a count of containers over its placement.
A global serviceplacement: all
docker service scaleChange replicas and deploy, or let autoscale: follow the load.
An overlay networkA network under networks: in mm.yaml. It spans the nodes that run a service on it.
An encrypted overlay networkAlways on: traffic between nodes travels inside WireGuard.
A service's virtual IPNone. The service name resolves to its healthy containers, the ones on the asking node first.
tasks.<service>The same name, with the same meaning: every healthy container of the service.
A port published on every node by the routing meshA port is published on the nodes that run the service. Point a load balancer or DNS at those nodes.
update_configupdate: {order, parallelism, failure} on the service in mm.yaml
docker service update --rollbackAutomatic when a rollout fails. mm deploy rollback returns from one that finished.
docker service ls and docker service psmm service status
docker service logsmm service logs, merged across nodes in time order
docker secret and a service's secrets:Secrets live in mm's secret store, or in OpenBao or Vault that the nodes read, and reach a service when it deploys.
docker config and a service's configs:config-files: on the service: each node writes the file and mounts it read-only.
A volume on shared storageshared-volumes: on the stack, for files that replicas share. Use local volumes for databases: see the limits.
docker node update --availability drainChange the placement of the node's services and deploy.

Compose keys

A Compose file written for a Swarm may place or multiply a service with keys that only a Swarm reads. On a cluster target mm config validate and mm deploy plan fail, and a finding MM_COMPOSE_SWARM_KEY for each key says what to write:

Compose keyWrite instead
deploy.mode: globalplacement: all on the service in mm.yaml.
deploy.mode: replicatedNothing. Remove the key.
deploy.replicas above 1replicas: on the service in mm.yaml, with placement: for its nodes.
deploy.placement (constraints and others)placement: with a node, a group from cluster.groups, all, or a list.
deploy.endpoint_modeNothing. mm has no virtual IPs. Remove the key.

The same Compose file keeps working unchanged in an environment with one host: Compose reads these keys there and placement is not involved.

Three more things to change by hand:

  • deploy.update_config and deploy.rollback_config are not read by mm. Set update: on the service in mm.yaml; see rolling deploys and rollback.
  • Networks with driver: overlay cannot be created outside a Swarm. Remove the driver from the Compose file and declare the network under networks: in mm.yaml, then list it on the services that use it. See connect services across nodes.
  • depends_on between services on different nodes cannot be honoured by the engine. The plan names each one it does not keep (depends_on not kept: app/web depends on db, which runs on db-1); make the service tolerate a dependency that is not up yet, or order the stacks with after:.

Move a project

  1. Add mm to the project so that it deploys on one machine first: add mm to a project. Your Compose files stay.
  2. List the hosts under nodes: and give each service a placement. Run mm config validate and change each key it names, using the tables above.
  3. Use new hosts, or free the existing ones: remove the stack and take each host out of the Swarm (docker stack rm, then docker swarm leave --force on every node) before you run mm target setup. A Swarm's own networks and mm should not manage the same engine.
  4. Set up the nodes and deploy: run a cluster.
  5. Move the data. mm creates its own volumes and does not adopt the ones a Swarm stack created. Restore each database from a dump or a backup into the new volume, and copy shared files into their shared volume.

With new hosts, keep the Swarm running until the new cluster serves traffic, then move DNS.

Projects that used the docker-swarm driver

mm 0.1.0 had a docker-swarm runtime driver, and development builds after it added members: and swarm: to targets. Both are removed. To move such a project:

  • Set runtime.driver to docker-compose.
  • List former members: under targets.<name>.nodes, each with a name and a host.
  • Rename targets.<name>.swarm: to cluster:. private-network.wireguard becomes mesh, and private-network.interface becomes mesh.interface. storage and groups keep their names. Drop address-pool, address-pool-mask, and ingress.
  • Delete environments.<env>.tls.
  • In placement:, use a node name, a group name, all, or a list. managers and any are no longer accepted.

A configuration that still uses a removed key fails to load with a message that names its replacement. The mm target swarm commands are gone: mm target nodes, mm target mesh status, and mm target storage status show the cluster.