Install TP-Link Omada Controller on CasaOS as a persistent Docker service and preserve its data, work, and logs directories. The old 2023 tutorial remains conceptually useful, but the maintained mbentley/omada-controller image has evolved and current deployments must expose several TCP and UDP ports for discovery, adoption, management, and captive-portal functions.
Do not treat Omada as a single-port web app. The web UI can open successfully while discovery and device adoption fail because UDP or management ports are missing.
Use a Maintained Omada Docker Image
The current Omada Controller Docker image is actively maintained and includes current upgrade guidance.
Persist All Three Main Data Paths
The image documents persistent volumes for:
/opt/tplink/EAPController/data/opt/tplink/EAPController/work/opt/tplink/EAPController/logs
Map those to CasaOS AppData folders so upgrades do not wipe controller state.
Expose the Required Ports
Omada uses more than the management UI. Current container documentation includes ports such as:
- 8043/TCP for HTTPS management;
- 8088/TCP for HTTP management;
- 8843/TCP for HTTPS portal;
- 27001/UDP and 29810/UDP for discovery;
- 29811–29817/TCP for device management in current releases.
Only publish the services your deployment needs, but do not omit discovery/adoption ports and then diagnose the controller as broken.
Bridge Mode Usually Works
Omada devices can communicate with a container through published host ports. You do not automatically need host networking or a dedicated macvlan address.
If device discovery fails across VLANs, that becomes a routed discovery/network-design issue rather than a CasaOS installation issue.
How to Install as a CasaOS Custom App
- Create a custom Docker app.
- Use the current
mbentley/omada-controllerimage/tag. - Map the persistent data/work/log directories.
- Publish required TCP and UDP ports.
- Set a restart policy such as
unless-stopped. - Start the container and open the HTTPS management port.
Back Up the Controller Before Major Upgrades
Omada controller upgrades can include database changes. Export a controller backup before changing major versions, especially around releases that require migration steps.
Do Not Expose Management Ports Publicly
Keep the controller on a trusted LAN or private VPN. Use the Docker deployment guide for the same container-deployment principles.
Use a Stable Controller Address
Omada devices need to keep finding the controller after reboots. Give the CasaOS server a stable LAN address through a DHCP reservation or carefully managed static IP. If the host address changes, previously adopted devices can continue trying to reach the old controller address.
Discovery Across VLANs May Need Additional Network Design
Local broadcast discovery works best when the controller and new Omada devices are on the same layer-2 network. If your access points and controller sit on different VLANs, simply publishing Docker ports may not make discovery broadcasts cross the router.
In that case, use TP-Link's supported layer-3 adoption/inform process or configure routing/firewall rules intentionally. Do not solve a VLAN routing problem by repeatedly reinstalling the container.
Check Java Memory on Small CasaOS Hosts
Omada is a Java application and can consume substantially more memory than lightweight DNS or dashboard containers. The maintained image exposes memory-related settings, and resource-constrained deployments should leave enough RAM for CasaOS, Docker, and other services.
If the container restarts under load, inspect logs and memory pressure before assuming the database is corrupt.
Verify Device Adoption After Every Upgrade
After a major Omada update, confirm the controller UI opens, adopted devices remain connected, and discovery/adoption ports are still published. A container that is “running” is not sufficient proof that the network-management plane is healthy.
FAQ
Why can I open Omada but devices are not discovered?
The web port can work while UDP discovery or TCP management ports are missing. Check every required published port.
Do I need host mode?
No. Bridge mode with correct published ports works for many deployments.
What should I back up?
Persist the documented data/work/log directories and also use Omada's own controller backup before major upgrades.
Can I expose Omada directly to the internet?
Avoid doing so. Keep the management UI behind LAN or private remote access.
