# Migrating the Omada Controller: desktop → homeserver

> **Done 2026-10-04** — the controller now runs on the OptiPlex
> (`192.168.30.20`, see [homeserver.md](homeserver.md)). What actually
> happened: backup exported on the desktop controller (6.3.0.45), restored in
> the new controller's setup wizard (same version), then the controller's
> built-in **device migration** pointed all five devices at `192.168.30.20` —
> no device reboots needed. The desktop instance was stopped with
> `docker compose down`. The guide below is kept for reference (e.g. a future
> hardware swap).

Once a new homeserver is provisioned and set up with Docker,
move the Omada Software Controller there permanently so it doesn't depend on
the desktop being on. This is a **backup/restore** move, not a live migration —
plan for a few minutes of controller downtime (the ER605 itself keeps routing
traffic the whole time; only controller management is briefly unavailable).

## Before you start

- **Note the exact controller version** running on the desktop (`Settings → About` or the version shown in the container image tag, e.g. `mbentley/omada-controller:6.3.0.x`).
- The new host's Compose setup **must run the same major.minor(.patch) version** as the desktop at restore time. TP-Link's controller cannot restore a backup taken by a newer version into an older one — it corrupts the database. If you want to upgrade, upgrade *after* the restore succeeds on matching versions, not before.
- The new host needs to be reachable from the ER605 for adoption to keep working post-migration — either on the same L2 segment, or with the gateway's controller "inform URL" pointed at the new host's address (Omada gateways support setting this manually under the standalone/local management settings if they're ever on different segments).

## Steps

1. **On the desktop controller:** `Settings → Maintenance → Backup` → create a manual backup (or use Auto Backup if one's already scheduled) and download the backup file.
2. **On the new host:** copy [`../docker/omada/compose.yaml`](../docker/omada/compose.yaml) over via the Ansible-managed Docker setup, keeping the **image tag identical** to what the desktop was running.
3. Bring the container up on the new host (`docker compose up -d`), open its controller UI, and go through the setup wizard just far enough to reach the option to restore from a backup instead of creating a new site — this is usually offered right at first login (`Restore` alongside `Create New Controller`).
4. Upload the backup file from step 1 and let it restore. The controller restarts once done.
5. Confirm the ER605 (and anything else already adopted) shows up and reconnects on the new controller. Give discovery a minute — devices need to re-inform to the new controller address.
6. Once confirmed working, stop and remove the desktop instance (`docker compose down`, and clean up the `omada-data`/`omada-logs` volumes there if you're done with them) — don't leave two controllers able to fight over the same devices.
7. If you *do* want to move to a newer controller version, do that now, as a separate step, against the new instance only — bump the image tag, `docker compose up -d`, and let it run its own internal DB migration.

## If versions don't match

If the desktop somehow ended up ahead of what you initially deploy on the new host:

1. Deploy the **exact matching version** on the new host first (adjust the image tag).
2. Restore the backup — this will succeed since versions match.
3. *Then* bump the new host's image tag to the newer version and let it self-upgrade the database in place.

Never try to restore a newer-version backup directly into an older controller — see the note in [status.md](status.md#omada-controller).