Skip to content
dockmesh

Stack Migration

Stack Migration moves a running stack from one host to another, including named volumes, with pre-flight checks, health verification, and automatic rollback on failure.

When to migrate

Section titled “When to migrate”
  • Decommissioning a host
  • Rebalancing load across a fleet
  • Moving from bare metal to a VM (or the other way)
  • Consolidating staging onto fewer hosts to save cost

Running a migration

Section titled “Running a migration”
  1. Open the stack’s detail page
  2. Actions → Migrate to host
  3. Pick the destination host
  4. Review the pre-flight report

dockmesh runs these checks before touching anything:

CheckWhat it validates
Image availabilityDestination host can pull every image referenced
Port conflictsNo static host ports on the destination collide
Volume capacityDestination has enough free disk for each volume
Docker versionDestination runs a compatible Docker version
Network modehost networking works on destination if used

If any check fails, migration is blocked and you see a list of remediation steps.

What happens during migration

Section titled “What happens during migration”
  1. Source stack is stopped (or kept running if --live is checked for read-mostly workloads)
  2. Named volumes are streamed over mTLS from source to destination using tar + chunked transfer
  3. compose.yaml is copied to the destination
  4. Stack is started on the destination
  5. Health checks run for up to 60 seconds (or the configured health check timeout)
  6. On success: source volumes are kept for 24h as a safety window, then pruned
  7. On failure: destination stack is removed, source is restarted, alert is raised

The entire flow is one atomic operation from the user’s perspective — if any step fails, you end up back where you started.

Bind-mount volumes

Section titled “Bind-mount volumes”

Bind-mounted paths (e.g. /opt/data:/app/data) are not migrated automatically — they point to host-specific paths. The pre-flight report flags these and you must either:

  • Ensure the same path exists on the destination (you handle the data copy yourself)
  • Convert the bind mount to a named volume first, then migrate

Rollback

Section titled “Rollback”

Every migration creates a rollback plan that is stored until the safety window expires. From the audit log you can Rollback any migration — dockmesh will stop the new stack and restart the old one from the retained volumes.

See also

Section titled “See also”