Omada Controller Docker Setup: Step-by-Step Guide

Table of Contents

This guide will walk you through the Omada Controller Docker setup process, which enables efficient management of TP-Link Omada devices in a Docker environment. With this setup, Homelab enthusiasts and small businesses can centralize network management and leverage Docker for scalability and efficiency. If you’re new to the TP-Link ecosystem, consider starting with the TP-Link EAP653 Access Point—an entry-level device that pairs perfectly with the Omada Controller.

Setting Up the Omada Controller Docker Setup: Prerequisites

Before starting, make sure you have the following:

Docker and Docker Compose installed on your server.
PUID and PGID values matching the user ID and group ID for managing the Docker container (in this guide, both are set to 508).
Open ports on your server for the required connections, such as 8088 and 8043.

Omada Controller Docker Setup: Docker Compose Configuration

Here’s the docker-compose.yml file for setting up the Omada Controller:

version: "3.1"

services:
  omada-controller:
    container_name: omada-controller
    image: mbentley/omada-controller:5.14
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 4096
        hard: 8192
    stop_grace_period: 60s
    network_mode: host
    environment:
      - PUID=508
      - PGID=508
      - MANAGE_HTTP_PORT=8088
      - MANAGE_HTTPS_PORT=8043
      - PORTAL_HTTP_PORT=8088
      - PORTAL_HTTPS_PORT=8843
      - PORT_APP_DISCOVERY=27001
      - PORT_ADOPT_V1=29812
      - PORT_UPGRADE_V1=29813
      - PORT_MANAGER_V1=29811
      - PORT_MANAGER_V2=29814
      - PORT_DISCOVERY=29810
      - PORT_TRANSFER_V2=29815
      - PORT_RTTY=29816
      - SHOW_SERVER_LOGS=true
      - SHOW_MONGODB_LOGS=false
      - SSL_CERT_NAME=tls.crt
      - SSL_KEY_NAME=tls.key
      - TZ=Etc/UTC
    volumes:
      - omada-data:/opt/tplink/EAPController/data
      - omada-logs:/opt/tplink/EAPController/logs

volumes:
  omada-data:
  omada-logs:

Source: mbentley (GitHub)

Step-by-Step Omada Controller Docker Setup Guide

1. Creating the docker-compose.yml File

Copy the configuration above into a file named docker-compose.yml in your preferred directory on your server.

2. Adjusting User Permissions (PUID and PGID)

Make sure the PUID and PGID values match the user ID and group ID of the user managing the Docker container. To find your user’s IDs, run:

id

3. Starting the Container with Docker Compose

In the same directory as your docker-compose.yml file, start the container with:

docker-compose up -d

This command downloads the mbentley/omada-controller Docker image, creates the container, and starts it in detached mode.

4. Checking Container Status

To check if the container is running properly, use:

docker ps

The output should display omada-controller with its status as “Up”.

5. Accessing the Omada Controller Interface

Once the container is running, open your browser and navigate to the Omada Controller URL:

HTTP: http://<your-server-ip>:8088
HTTPS: https://<your-server-ip>:8043

This will bring you to the Omada Controller setup page, where you can configure your network and add devices.

6. Configure and Manage Devices

After completing the initial setup, you can start adding and managing TP-Link Omada-compatible devices (such as access points and switches) through this interface. The Omada Controller allows for centralized monitoring, configuration, and firmware updates, streamlining network management.

Key Considerations and Tips

Network Mode
The container uses network_mode: host to utilize the host’s network stack. This is required for TP-Link’s discovery protocol, allowing Omada devices to detect and communicate with the controller.
Port Configuration
Make sure the specified ports (e.g., 8088 for HTTP, 8043 for HTTPS) are open and not blocked by any firewalls.
Data Persistence
The omada-data and omada-logs volumes ensure persistent data storage and log retention, mapped to /opt/tplink/EAPController/data and /opt/tplink/EAPController/logs inside the container.
SSL Certificates
To enable HTTPS with custom SSL certificates, replace tls.crt and tls.key in the container with your SSL files in /opt/tplink/EAPController/data.

Conclusion

Setting up the Omada Controller Docker Setup allows for convenient and flexible network management. With this Docker configuration, you can deploy the Omada Controller on your server, gaining centralized control over your TP-Link Omada devices. This setup is especially useful for Homelabs and small business environments looking for efficient network management tools. For a detailed hardware pairing, consider checking out our guide to the TP-Link EAP653 Access Point, a great entry-level device that complements the Omada Controller setup perfectly.

TP-Link OC200 Omada Hybrid PoE Hardware Controller

Manage your network effortlessly with the TP-Link OC200 Omada Controller, offering centralized cloud access for real-time monitoring and configuration. Ideal for Homelabs and businesses, it features user management, automated backups, and a durable metal casing for professional-grade performance.

Buy Now on Amazon