docker-omada-controller: TP-Link's Omada controller, packaged for containers

A community wrapper around vendor software you cannot inspect

docker-omada-controller is a Docker image for the TP-Link Omada Software Controller, also known as the TP-Link Omada Network Application, so that you can centrally manage TP-Link Omada hardware from a container. The disclaimer at the top of the README sets the ground rules: the author is not in any way affiliated with TP-Link, and is a community member who has packaged TP-Link's free software as a Docker image for easier management and consumption. That framing explains the whole repository. It is a packaging and operations project, not a port, and the work involved is the unglamorous part of containerising a Java application with a MongoDB database, a web portal and a discovery protocol on its side. The support guidance follows the same split. If the problem is about running the controller in Docker, the author asks you to open a Help discussion on the repository, while if the problem is with the actual software, the README suggests the TP-Link community forums or TP-Link's support team, because the author does not have access to the source code to debug those issues. If you are unsure which side of the line you are on, the author offers to help decide. The older v3 and v4 controllers are handled separately, with their own README and a snapshot tag, `archive_v3_v4`, holding the code that still contains those artifacts, since they were removed as of 2 July 2024.

The tag policy is the most useful thing in the README

The image tagging scheme is explained in detail, and the guidance is unusually emphatic. There is a major version tag, such as `5` or `6`, for people who want to set it and forget it, which the README says should be mostly safe from non-breaking changes. There is a major.minor tag, such as `6.3`, which the README recommends for most people as the safest option, and which can almost certainly be considered non-breaking when a new image version is available. Then there is the warning, in capitals, that using the `latest` tag is a bad idea and should not be done, because you may upgrade to a version your devices do not support, and TP-Link can put in breaking changes at any time. There are also tags for beta and testing releases, archived tags for older versions, and tags with Chromium, which are needed if you want to create PDF reports from the controller. The current published releases illustrate the beta emphasis, with tags v6.3.0.111-beta, v6.3.0.110-beta and v6.3.0.108-beta appearing in the release list. The reason for the strictness is a property of the upstream product rather than of the container: you are consuming vendor binaries, and the vendor decides when a configuration stops working.

Your CPU has to pass a check before v6 will run

The quickstart guide has a step that most Docker guides would not have, which is verifying that the CPU supports the features required for the v6 image and above. The reason given is the MongoDB 8 system requirements, which require specific CPU features. The repository ships a shell script, `mongodb8_cpu_support_check.sh`, that can be executed to test for them, and the README asks you to run it before picking an image tag. If the script says your CPU is not supported, the README points at a known issues section that covers clean installs and upgrades separately, because the workaround differs between the two. The same theme runs through the known issues list, which has a section on systems that do not support AVX or armv8.2-a. There is a separate set of notes for the `armv7l` architecture, which is marked deprecated in the Dockerfile's own comment, and it carries two warnings, one about an unsupported base image and one about unsupported MongoDB. So the architecture support is real in the sense that the images are built for amd64, arm64 and armv7l, but it is uneven, and the README is candid about where the unevenness bites.

What is inside the image, and how it is wired up

The Dockerfile is short and tells you the shape of the thing. It is based on a rebased and repackaged Ubuntu 24.04 image, copies in `healthcheck.sh` and `install.sh`, takes the architecture as a build argument with amd64 as the default, arm64 as an alternative and armv7l marked deprecated, and takes the controller version as another build argument, defaulting to 6.3.0.45, with the label recording it. The controller itself is installed by running `install.sh`, and the entrypoint is a separate `entrypoint-unified.sh`. The workdir is the controller's own lib directory, two volumes are declared for the data and logs directories under `/opt/tplink/EAPController`, and a healthcheck runs `healthcheck.sh` with a five minute start period, which is sensible for a container that has to start a JVM, a database and a discovery listener before it is useful. The default command is the Java invocation with a modest heap, `-Xms128m` and `-Xmx1024m`, heap free ratios set, a heap dump written into the logs volume on an out of memory error, the headless flag, and the controller's own main class. The compose file that ships with the repository shows the operational shape, with a pinned image tag, an `unless-stopped` restart policy, a nofile ulimit, a sixty second stop grace period, host networking and the environment variables that configure the ports, the user and group ids, the log switches and the time zone:

services:
  omada-controller:
    container_name: omada-controller
    image: mbentley/omada-controller:6.3
    restart: unless-stopped
    network_mode: host
    environment:
      - PUID=508
      - PGID=508

The environment variable list in the compose file is long and worth reading as documentation in itself, since it names the ports the controller expects, among them the management HTTP and HTTPS ports, the portal HTTP and HTTPS ports, the upgrade ports, the app discovery and device discovery ports, the manager, adopt, upgrade, transfer, RTTY and device monitor ports.

Networking, rootless mode and Kubernetes

The README covers a surprising number of deployment shapes, and each exists for a reason. There is a section on using host networking, which is what the shipped compose file does, a section on using port mapping instead, a section on using non-default ports, a section on running rootless, and a section on Docker Compose with two compose files in the repository, one plain and one named for a bridge setup. Then there is Kubernetes, with a Helm chart in the `helm/` directory and manifests in `k8s/`. The persistence model is documented separately, with the data and logs volumes, and there is a section on custom SSL certificates, with the certificate and key file names given as environment variables, and a section on time zones, and a section on unprivileged ports. The completeness of that list is itself the point. This is the documentation of a project whose real product is the operational knowledge, accumulated by someone who has run this controller in containers long enough to hit the interesting failures, and the index at the top of the README is effectively a map of everything that can go wrong.

Operations: backups, upgrades and database corruption

The best practices section is the one an operator should read before the first deploy, and it has four parts. Container resource constraints, which connect to the known issues about low resource systems, with subsections on the JVM heap, the MongoDB WiredTiger cache, and the OpenJ9 image tags, and even a complete Kubernetes example for a pod limited to 2 GB. Controller backups, which matter because the controller's state lives in MongoDB and the volumes are the only copy. Controller upgrades, which the README treats as a separate topic from backups. And preventing database corruption, which is the failure mode that a Kubernetes operator will care about most, because the MongoDB corruption issue is a known issue with its own section. The repository also ships `spring-boot-tuning.md` for the tuning of the underlying Spring Boot application, an `external_mongodb/` directory and an `mongodb_upgrade/` directory for the case where the database is not inside the container, and `DEVICE_ADOPTION.md` for the process of getting hardware to join the controller, which has its own known issue entry about devices failing to adopt. The upgrade issues list is specific and dated, with entries for 5.8 and 6.3 producing 404s and blank pages, for 5.12 being unable to log in after an upgrade, for slowness in Safari, and for two separate controller-unable-to-start reports at 5.14 and 5.15.6.x.

Editorial conclusion

Adopt docker-omada-controller if you run TP-Link Omada hardware and want the controller to live in the same Docker or Kubernetes estate as everything else, and if you are comfortable running vendor software that you do not have the source for. Do not adopt it expecting vendor support, because the README is explicit that software problems belong to TP-Link's forums and support team, and do not adopt it on hardware that fails the CPU feature check, since the v6 images need MongoDB 8's requirements. Before the first run, pin a major.minor tag rather than latest, because the README says in capitals not to use latest, and verify your CPU with the bundled check script. The licence is AGPL-3.0, the current tags are 6.3.0 betas such as v6.3.0.111-beta, and the last push was on 2026-10-16.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. mbentley/docker-omada-controller on GitHub
4. README
5. Releases