# Migrating the Omada Controller: desktop → NUC

Once the NUC homeserver is provisioned and set up with Docker (via Ansible),
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 NUC'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 NUC 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 NUC'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 NUC:** copy [`../docker/omada-controller/docker-compose.yml`](../docker/omada-controller/docker-compose.yml) 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 NUC (`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 NUC 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 NUC 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 NUC:

1. Deploy the **exact matching version** on the NUC first (adjust the image tag).
2. Restore the backup — this will succeed since versions match.
3. *Then* bump the NUC'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).