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; eachmmdchanges 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.
mmhas no scheduler: a service runs on the nodes itsplacementnames, 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 planshows what each node will start, change, and stop, andmm deploy applytakes 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 Swarm | In mm |
|---|---|
docker swarm init, join, and join tokens | List the hosts under targets.<name>.nodes, then run mm target setup. See set up the nodes. |
| Manager and worker roles | None. Every node is the same. |
docker node ls | mm target nodes |
| Node labels and placement constraints | placement: on the service: a node, a group from cluster.groups, all, or a list. |
docker stack deploy | mm deploy plan, then mm deploy apply with the plan's hash |
| A stack | A stack: an entry under stacks: that names Compose files. |
| A replicated service | replicas: on the service: a count of containers over its placement. |
| A global service | placement: all |
docker service scale | Change replicas and deploy, or let autoscale: follow the load. |
| An overlay network | A network under networks: in mm.yaml. It spans the nodes that run a service on it. |
| An encrypted overlay network | Always on: traffic between nodes travels inside WireGuard. |
| A service's virtual IP | None. 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 mesh | A port is published on the nodes that run the service. Point a load balancer or DNS at those nodes. |
update_config | update: {order, parallelism, failure} on the service in mm.yaml |
docker service update --rollback | Automatic when a rollout fails. mm deploy rollback returns from one that finished. |
docker service ls and docker service ps | mm service status |
docker service logs | mm 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 storage | shared-volumes: on the stack, for files that replicas share. Use local volumes for databases: see the limits. |
docker node update --availability drain | Change 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 key | Write instead |
|---|---|
deploy.mode: global | placement: all on the service in mm.yaml. |
deploy.mode: replicated | Nothing. Remove the key. |
deploy.replicas above 1 | replicas: 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_mode | Nothing. 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_configanddeploy.rollback_configare not read bymm. Setupdate:on the service inmm.yaml; see rolling deploys and rollback.- Networks with
driver: overlaycannot be created outside a Swarm. Remove the driver from the Compose file and declare the network undernetworks:inmm.yaml, then list it on the services that use it. See connect services across nodes. depends_onbetween 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 withafter:.
Move a project
- Add
mmto the project so that it deploys on one machine first: add mm to a project. Your Compose files stay. - List the hosts under
nodes:and give each service aplacement. Runmm config validateand change each key it names, using the tables above. - Use new hosts, or free the existing ones: remove the stack and take each
host out of the Swarm (
docker stack rm, thendocker swarm leave --forceon every node) before you runmm target setup. A Swarm's own networks andmmshould not manage the same engine. - Set up the nodes and deploy: run a cluster.
- Move the data.
mmcreates 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.drivertodocker-compose. - List former
members:undertargets.<name>.nodes, each with anameand ahost. - Rename
targets.<name>.swarm:tocluster:.private-network.wireguardbecomesmesh, andprivate-network.interfacebecomesmesh.interface.storageandgroupskeep their names. Dropaddress-pool,address-pool-mask, andingress. - Delete
environments.<env>.tls. - In
placement:, use a node name, a group name,all, or a list.managersandanyare 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.