Putting in Omada Controller with Docker in 5min — LazyAdmin

You probably have TP-Hyperlink Omada community gear then you definitely additionally want the Omada Controller. And the simplest means to do this is by operating the Omada Controller in Docker. You may run the Docker container by yourself PC, a Raspberry Pi, Synology NAS for instance.

On this article, I’ll clarify how one can set up the Omada Controller Docker container. We are going to additionally have a look at how one can run the Omada Controller on a Raspberry Pi and the issues it’s good to be careful for.

Why Docker?

Now you may obtain an set up the Omada Controller immediately in your Window or Linux system, utilizing one these installers. Nevertheless it’s higher to make use of a Docker container as an alternative.

Docker means that you can run purposes in a container. The benefit of a container is that the developer can create the package deal with all of the dependencies it wants wants, like Java and MongoDB. Particularly Java variations can create conflicts with different purposes, so through the use of a container we forestall this threat.

One other benefit of utilizing Docker is that we will merely replace the controller by pulling a brand new picture and restarting the container. And if wanted we will transfer the container to a differenent machine with out loosing any knowledge.

There are different methods to run the Omada Controller, for instance utilizing the hosted model. I’ve defined all of the choices on this article.

Conditions

Earlier than we begin you’ll want:

• A tool to run Docker on – This is usually a NAS (Synology, QNAP), a mini PC, a Raspberry Pi, and even your Home windows or Linux desktop. Just about something that may run Docker will work.
• Docker and Docker Compose put in – On most NAS gadgets you may set up Docker (or Container Supervisor) from the package deal middle. On Linux or Home windows, set up Docker Desktop or Docker Engine.
• The system on the identical community as your Omada {hardware} – The controller wants to have the ability to uncover your entry factors and switches on the native community.

The Omada Controller makes use of round 1.9 GB of RAM after startup. So ensure your system has at the very least 4 GB of RAM out there, ideally extra in case you’re operating different containers as properly.

Notice

There isn’t a official Docker picture from TP-Hyperlink. The picture we’re utilizing is mbentley/omada-controller – a group picture maintained by Matt Bentley. When TP-Hyperlink releases a brand new controller model, the picture is often up to date inside days.

Setting Up the Omada Controller Docker Container

Let’s get the controller operating. Create a brand new folder on the system the place you’ll run the docker container. On Home windows this might for instance be C:DockerOmada. On Linux, this might for instance be ~/docker/omada or /decide/docker/omada. On Linux you may create the folder with:

mkdir -p /decide/docker/omada && cd /decide/docker/omada

Subsequent we’re going to create the docker-compose.yml file. On Home windows simply create a brand new file or for Linux we will use nano docker-compose.yml

providers:
  omada-controller:
    picture: mbentley/omada-controller:6.2
    container_name: omada-controller
    stop_grace_period: 60s
    restart: unless-stopped
    ulimits:
      nofile:
        comfortable: 4096
        exhausting: 8192
    ports:
      - "8088:8088"
      - "8043:8043"
      - "8843:8843"
      - "27001:27001/udp"
      - "29810:29810/udp"
      - "29811-29817:29811-29817"
    atmosphere:
      - TZ=Europe/Amsterdam
    volumes:
      - omada-data:/decide/tplink/EAPController/knowledge
      - omada-logs:/decide/tplink/EAPController/logs

volumes:
  omada-data:
  omada-logs:

A number of issues to notice right here:

• Picture tag 6.2 – This pins you to the 6.2.x department. The picture helps each amd64 and arm64, so it really works on Intel/AMD machines and ARM gadgets just like the Raspberry Pi 5.
• stop_grace_period: 60s – That is essential. The controller makes use of MongoDB internally, and MongoDB wants a clear shutdown. With out this, you threat database corruption when stopping the container. Don’t skip this.
• TZ – Set this to your timezone. The controller makes use of it for logs and scheduled duties.
• Named volumes – Your configuration and knowledge are saved in omada-data and omada-logs. These survive container restarts and updates.

Ports Defined

The Omada Controller makes use of fairly a couple of ports:

You may change the administration ports (8088 and 8043) in the event that they battle with one thing else in your system, extra on that within the troubleshooting part.

Begin the Container

Open a terminal within the folder the place you saved the compose file and run:

docker compose up -d

The primary startup takes a minute or two as a result of the container must initialize MongoDB and begin the Java utility. You may comply with the progress within the logs:

docker logs -f omada-controller

Wait till you see a line that claims the controller has began with the model quantity. Press Ctrl+C to cease following the logs.

To confirm all the things is operating:

docker ps --format "desk {{.Names}}t{{.Picture}}t{{.Standing}}"

You must see the container with standing “Up”.

Omada Controller First-Run Setup

Now open your browser and go to https://localhost:8043 (or substitute localhost with the IP handle of the machine operating Docker).

Coping with the SSL Warning

The very first thing you will note is a browser warning that the connection will not be safe. That is regular, the controller makes use of a self-signed SSL certificates by default.

In Chrome or Edge:

1. Click on Superior
2. Click on Proceed to localhost (unsafe) (or Proceed to [IP address])

In Firefox:

1. Click on Superior
2. Click on Settle for the Threat and Proceed

Firefox really helps you to retailer this exception completely, so that you received’t see the warning once more for this handle. Chrome remembers it for some time however could ask once more after a browser replace.

Notice

For a house community, clicking by means of the warning is completely fantastic. The connection remains to be encrypted, the certificates is simply not signed by a trusted authority. If you would like correct HTTPS with a trusted certificates, you’ll have to put a reverse proxy like Caddy or Nginx Proxy Supervisor in entrance of the controller with an actual area title and Let’s Encrypt.

Strolling By the Wizard

The setup wizard has a couple of steps:

1. Signal In – You get the selection between signing in with a TP-Hyperlink ID or creating an area account. For a self-hosted setup, decide Create a Native Account. This fashion the controller runs utterly unbiased from TP-Hyperlink’s cloud.
2. Controller Title and Timezone – Give your controller a reputation and set the timezone. The timezone right here ought to match the TZ you set within the compose file.
3. Gadget Discovery – You probably have Omada gadgets on the identical community, they might already present up right here. You may add them now or skip this and do it later from the dashboard.
4. Completed – Full the setup and also you’re taken to the login display.

Now log in with the credentials you simply created. You’ll land on the dashboard displaying your native website. Click on on the location to begin configuring your community and including gadgets.

Notice

I seen a small UI bug throughout setup: I set my username to “lazyadmin” in step 1, however the completion display confirmed the username as “admin”. The precise username was appropriately set to “lazyadmin” although, only a show bug within the wizard.

Adopting Omada Units

Adopting gadgets in your Omada Controller in Docker isn’t as easy generally as you suppose. Your Omada entry factors and switches use Layer 2 broadcast to search out the controller. And by default, Docker containers run on their very own bridge community, which suggests these broadcasts by no means attain the container.

With the port mapping setup from the compose file above, the administration net UI works fantastic. However system discovery won’t discover your {hardware} routinely.

To repair this, we now have two choices:

Choice 1: Host Networking (Linux solely)

If you happen to run Docker on Linux (together with a NAS), you may swap to host networking. Substitute the ports part in your compose file with:

    network_mode: host

This makes the container share the host’s community immediately, so Layer 2 discovery works. The draw back is that you would be able to’t remap ports, the controller binds on to the host’s interfaces.

Notice

Host networking doesn’t work on Docker Desktop for Home windows or macOS. Docker Desktop runs containers inside a Linux VM, so host networking solely exposes ports to that VM, to not your precise community.

Choice 2: Set the Inform URL (Works In all places)

If host networking will not be an possibility, you may inform your gadgets the place to search out the controller manually. Enter the IP Deal with of the system in your browser and login with the default username and password admin/admin. Then go to System Instruments→ Controller Settings and set the Controller Inform URL to the IP handle of your Docker host.

For brand new gadgets, you may as well set the inform URL by means of the system’s personal administration interface or through DHCP Choice 138.

For many residence setups with all the things on the identical subnet, host networking on Linux is the simplest path. If you happen to’re operating on Docker Desktop or have a extra advanced community with VLANs, use the inform URL methodology.

Updating the Omada Controller

When a brand new model comes out, updating is easy. Necessary to recollect is that your knowledge is saved in named volumes, not contained in the container. So you may safely take away and recreate the container with out dropping something.

docker compose down
docker compose pull
docker compose up -d

That’s it. The docker compose down command stops and removes the container however retains the volumes. docker compose pull downloads the newest picture for the tag you specified (like 6.2). And docker compose up -d creates a recent container with the brand new picture, utilizing your current knowledge.

Necessary

By no means use docker compose down -v throughout an replace. The -v flag removes the named volumes, and with it all of your configuration and knowledge.

After the replace, open the controller in your browser. You must see the login display, not the setup wizard. That confirms your knowledge survived the replace. Examine the controller model beneath Settings to confirm you’re operating the brand new model.

A Notice on Main Model Upgrades

The tag 6.2 will get you the newest 6.2.x launch routinely. However if you wish to bounce to a brand new main model (like from 5.x to six.x), don’t skip variations. Improve one main model at a time and ensure the controller begins cleanly earlier than shifting to the subsequent. And all the time make a backup first.

Backup and Restore

After you’ve gotten the controller up and operating, it’s best to first allow the up computerized backups earlier than you neglect about it. Within the Omada Controller, go to Settings → Upkeep and allow the Backup Schedule.

A weekly backup is for many residence or small enterprise networks extra then sufficient. For the backup contents, the default Configuration file possibility (which incorporates settings, person data, authenticated purchasers, and firmware replace logs) is ideal.

The default is Save to Native File, which shops the backup contained in the controller’s knowledge quantity. That’s fantastic for many circumstances. If you would like extra safety, swap to Save to File Server and level it to an SFTP server in your community, that means your backup survives even when the Docker host dies.

Restore from Backup

If you happen to ever want to revive from a backup, whether or not on the identical machine or a recent set up, right here’s how:

1. Begin a recent Omada Controller container (use the identical compose file)
2. Open the setup wizard and create an area account first (it’s good to get previous step 1)
3. On step 2, click on Restore from Backup File
4. Choose your .cfg backup file
5. Look ahead to the “Restored Efficiently” message and click on Go to Dashboard

Your authentic settings, website configuration, and credentials are all again. Necessary to notice, the native account you created in step 1 will get overwritten by the backup, so that you log in together with your authentic credentials.

Altering the Default Ports

If ports 8043 or 8088 battle with one thing else in your system, you may change them. However there’s a gotcha: the controller shops port configuration in its database after the primary run. So simply altering the port mapping in Docker received’t work, the controller contained in the container nonetheless listens on the previous port.

You’ll want to set the port each within the atmosphere variables AND within the port mapping. And add WEB_CONFIG_OVERRIDE=true to drive the controller to make use of the atmosphere variables as an alternative of the database values:

    ports:
      - "8088:8088"
      - "8443:8443"          # Modified from 8043
      - "8843:8843"
      - "27001:27001/udp"
      - "29810:29810/udp"
      - "29811-29817:29811-29817"
    atmosphere:
      - TZ=Europe/Amsterdam
      - MANAGE_HTTPS_PORT=8443 # Set the administration port
      - WEB_CONFIG_OVERRIDE=true # Add the override

After altering the compose file, restart:

docker compose down
docker compose up -d

The controller is now accessible on https://localhost:8443.

Working the Omada Controller on a Raspberry Pi

You probably have a Raspberry Pi mendacity round, you is perhaps tempted to run the Omada Controller on it. I’ve written an identical information for operating the UniFi Controller on a Raspberry Pi, and that works nice. However with the Omada Controller there are some issues it’s good to know.

The Pi 4 Downside

The Omada Controller model 6.x makes use of a more moderen model of MongoDB that requires the AVX instruction set. And the Raspberry Pi 4 doesn’t have AVX. So in case you attempt to run the 6.2 picture on a Pi 4, MongoDB will crash on startup.

The older model 5.x of the controller does run on a Pi 4. Neighborhood reviews verify it really works on a Pi 4 with 4 GB RAM, although it makes use of round 3.1 GB of reminiscence, so get the 4 GB or 8 GB mannequin. Use the picture tag 5 as an alternative of 6.2:

    picture: mbentley/omada-controller:5

However needless to say model 5 received’t get new options and can ultimately cease receiving updates.

Raspberry Pi 5

The Pi 5 makes use of a special CPU structure and will deal with the v6 controller higher. Examine the mbentley GitHub repository for the newest compatibility data earlier than you set it up.

My Advice

If you happen to’re shopping for one thing particularly to run the Omada Controller, take into account a used mini PC as an alternative of a Raspberry Pi. Something with a sixth gen Intel processor or newer has AVX help, and used mini PCs are sometimes price-competitive with a Pi 4 when you add the case, energy provide, and an SSD. Plus you get extra RAM, an actual SSD, and no compatibility points.

If you have already got a Pi 4 and simply need to get going, the v5 controller works. However for a brand new setup, a mini PC is the extra future-proof alternative.

Troubleshooting

Units Don’t Present Up for Adoption

More often than not it is a networking problem. The gadgets can’t discover the controller as a result of Docker’s bridge community blocks the Layer 2 discovery broadcasts. Swap to host networking on Linux, or set the inform URL manually. See the Adopting Omada Units part above.

Container Begins Then Instantly Stops

Examine the logs first:

docker logs omada-controller

Frequent causes:

• Not sufficient reminiscence – The controller wants round 1.9 GB of RAM. On a low-memory system, MongoDB would possibly get killed by the OS. You may restrict the Java heap dimension by including -e JAVA_MAX_HEAP_SIZE=1024m to the atmosphere variables.
• Port conflicts – One other service is already utilizing one of many required ports. Examine with docker logs for binding errors.

Gradual Startup

The controller is a Java utility with an embedded MongoDB. First startup can take 2 minutes, and even subsequent begins want a couple of minute. That is regular. Don’t restart the container simply because it doesn’t reply instantly, verify the logs to see if it’s nonetheless booting.

Database Corruption After a Crash

This is the reason the stop_grace_period: 60s within the compose file is so essential. If the container will get killed with out giving MongoDB time to close down cleanly, the database can get corrupted. If this occurs, you’ll see MongoDB errors within the logs. Your only option is to revive from a backup.

If you happen to don’t have a backup, strive stopping and beginning the container as soon as extra. MongoDB has a restoration mechanism that generally fixes minor corruption on the subsequent startup. If that doesn’t work, you’ll have to take away the info quantity and begin recent:

docker compose down -v
docker compose up -d

Wrapping Up

Working the Omada Controller in Docker is the simplest solution to self-host it. One compose file, a few minutes to arrange, and your whole Omada community is managed from a container that you would be able to replace, again up, and restore with none problem.

Be sure to arrange these computerized backups, you’ll thank your self later. And in case you’re searching for extra Omada guides, take a look at my Omada Fusion 2.5G overview or my information on establishing VLANs with Omada.

I hope you preferred this text, in case you have any questions, simply drop a remark under.