Migrate from Rancher (non-Kubernetes)

This guide is for users running Rancher 1.x (Cattle) or Rancher 2.x managing pure Docker hosts (not Kubernetes). If your Rancher manages Kubernetes clusters, dockmesh is not a 1:1 replacement — use k3s + Rancher Desktop or Lens instead.

When dockmesh is the right fit

You’re on Rancher 1.x and need to leave before EOL (already past)
You use Rancher’s Docker host management but don’t need K8s
Your Rancher setup is ~3-50 Docker hosts running Compose stacks
You want simpler ops, smaller server footprint

When dockmesh is the wrong fit

You rely on Kubernetes primitives (Pods, Services, Ingress, HPA)
Your stacks require network policies across the cluster
You run persistent volume claims with dynamic provisioning
You use Rancher’s app catalog with Helm

For those, stick with Rancher + k3s/RKE.

Before migrating

Export from Rancher:

Stack definitions (docker-compose.yml files)
Environment variables per stack
List of hosts with their labels
Service accounts / users with Rancher permissions (for RBAC mapping)

Step 1 — Install dockmesh

On a new VM or one of your Rancher-managed hosts:

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

Step 2 — Migrate hosts

Rancher agents and dockmesh agents can coexist on the same Docker daemon. Install dockmesh agents on each Rancher-managed host without removing the Rancher agent first — zero downtime.

For each host:

In dockmesh UI: Hosts → Add host, get enrollment token
On the host: run the install command
Host appears online in dockmesh within seconds
Both Rancher and dockmesh now see the same Docker socket

Match Rancher host labels → dockmesh tags:

Rancher label env=prod → dockmesh tag prod
Rancher label role=web → dockmesh tag web

Step 3 — Migrate stacks

Rancher 1.x (Cattle)

In Rancher 1.x UI: Stacks → [stack] → Download Config
You get docker-compose.yml + rancher-compose.yml
The docker-compose.yml is almost dockmesh-compatible — remove any Rancher-specific labels: (io.rancher.*)
Import into dockmesh: Stacks → New stack → paste

Rancher 2.x (Docker hosts)

Export compose file for each stack
Remove io.rancher.* labels
Remove Rancher-specific scheduler directives (dockmesh uses host tags instead)
Import into dockmesh

Step 4 — Handle networking

Rancher 1.x Cattle used an overlay network across hosts (managed IP ranges like 10.42.x.x). dockmesh doesn’t replicate this — containers live on host-local networks.

Cross-host communication options:

Reverse proxy — publish via dockmesh’s Caddy or Traefik
WireGuard mesh — flat network across hosts
Public endpoints — use external DNS + TLS for “internal” traffic

Most Rancher 1.x users over-used the overlay network; migrating is a good chance to simplify.

Step 5 — RBAC

Rancher’s RBAC is more granular than dockmesh’s, but the basics map cleanly:

Rancher	dockmesh
Environment member	Operator role scoped to a host tag
Environment admin	Admin role scoped to a host tag
Restricted user	Viewer role
Full admin	Admin role, all hosts

Create roles in Settings → Roles, assign via SSO group mapping or manually per user.

Step 6 — Decommission Rancher

Once all stacks run on dockmesh:

Rancher 1.x:

# On each host, remove Rancher agent
docker rm -f rancher-agent rancher-agent-state
# On manager, stop rancher/server
docker rm -f rancher-server

Rancher 2.x:

Follow Rancher’s removal docs. The rancher-system-agent systemd service needs manual removal.

What’s different / what you’ll notice

No catalog/apps — use dockmesh stack templates or community compose files
No environment concept — dockmesh has host tags instead
Simpler UI — fewer tabs, less clutter
Single server vs Rancher’s HA cluster — dockmesh has a planned HA mode but currently runs single-node