Infrastructure/docs/omada-controller-migration.md

Migrating the Omada Controller: desktop → homeserver

Done 2026-10-04 — the controller now runs on the OptiPlex (192.168.30.20, see 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 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.