33 lines
3.2 KiB
Markdown
33 lines
3.2 KiB
Markdown
# 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).
|