Controlador Omada en Docker: paso a paso con docker compose

Los equipos Omada de TP-Link (routers, switches y access points) se pueden manejar uno por uno, cada uno desde su web, o todos juntos desde un controlador: el software que los adopta y los administra desde un solo panel. En otra entrada lo instalé en un LXC de Proxmox, con Java y MongoDB a mano. Esta vez va en Docker: un docker-compose.yml, un comando, y listo.

La idea es manejar desde acá el router ER605 de la casa. Todo se hizo en un servidor Ubuntu real y con capturas del navegador.

Antes de empezar: Docker

Hace falta un Linux con Docker y Docker Compose. Si no los tenés, está el paso a paso en Docker y docker-compose sobre Ubuntu (y para varios servidores, Automatizar instalación de docker con Ansible).

Para comprobarlo:

docker --version
docker compose version

Recursos: recién instalado y sin equipos, el contenedor usa 1,7 GB de RAM. Conviene tener 4 GB libres para que MongoDB tenga margen. La imagen pesa 1,5 GB.

La imagen

TP-Link no publica una imagen oficial de Docker. La que usa casi todo el mundo es mbentley/omada-controller: se actualiza con cada versión del controlador y trae todo adentro:

No hay que instalar Java, MongoDB ni jsvc: esa es la gran ventaja frente a la instalación a mano.

Un consejo del propio autor de la imagen: no usar la etiqueta latest. Fijá la versión, así una actualización no te agarra de sorpresa.

Host o bridge: la decisión importante

Hay dos formas de conectar el contenedor a la red, y cambian cómo encuentra los equipos:

El autor de la imagen recomienda host. Yo usé bridge, por un motivo concreto: el servidor tiene ufw activo y no quería tocar las reglas. Con bridge, Docker publica los puertos por su cuenta. Lo pago en la adopción: el router no encuentra solo al controlador y hay que cargarle la IP (lo vemos más abajo).

Ojo con esto último: los puertos que publica Docker no pasan por ufw. Aunque ufw diga que bloquea todo, el 8043 queda abierto. En una red de casa detrás de un router está bien, pero en un servidor con IP pública no: ahí publicá los puertos solo en la IP interna ("192.168.1.3:8043:8043") o usá host con reglas de ufw.

Paso 1: la carpeta y el compose

mkdir -p ~/contenedores/omada
cd ~/contenedores/omada

docker-compose.yml:

services:
  omada:
    image: mbentley/omada-controller:${OMADA_VERSION}
    container_name: omada
    restart: unless-stopped
    stop_grace_period: 60s
    ulimits:
      nofile:
        soft: 4096
        hard: 8192
    environment:
      - TZ=${TZ}
      - MANAGE_HTTP_PORT=8088
      - MANAGE_HTTPS_PORT=8043
      - PORTAL_HTTP_PORT=8088
      - PORTAL_HTTPS_PORT=8843
      - SHOW_SERVER_LOGS=true
      - SHOW_MONGODB_LOGS=false
    ports:
      - "8088:8088"            # web (redirige a 8043)
      - "8043:8043"            # web de administración (HTTPS)
      - "8044:8044"            # actualización de firmware de los equipos (HTTPS)
      - "8843:8843"            # portal cautivo (HTTPS)
      - "19810:19810/udp"      # descubrimiento de equipos viejos
      - "27001:27001/udp"      # descubrimiento desde la app Omada
      - "29810:29810/udp"      # descubrimiento
      - "29811-29817:29811-29817"  # gestión, adopción, firmware y monitoreo
    volumes:
      - ./data:/opt/tplink/EAPController/data
      - ./logs:/opt/tplink/EAPController/logs

Y un .env al lado, con la versión y la zona horaria:

OMADA_VERSION=6.3.0.111
TZ=America/Argentina/Buenos_Aires

Algunos detalles:

• stop_grace_period: 60s: le da tiempo a MongoDB para cerrar bien al parar el contenedor. Si lo cortan de golpe, la base se puede dañar.
• ./data y ./logs: los datos quedan en la carpeta, a la vista y fáciles de respaldar. La imagen les pone el dueño correcto sola (usuario 508).
• Los puertos de adentro y de afuera tienen que ser iguales. Si cambiás uno, cambialo también en las variables MANAGE_* y PORTAL_*.
• Host en lugar de bridge: borrá todo el bloque ports: y poné network_mode: host.

Paso 2: levantarlo

docker compose up -d

 Image mbentley/omada-controller:6.3.0.111 Pulled
 Network omada_default Created
 Container omada Started

El primer arranque tarda un par de minutos (crea la base). La imagen trae un healthcheck, así que se puede esperar a que diga healthy:

docker compose ps

NAME    IMAGE                                 STATUS
omada   mbentley/omada-controller:6.3.0.111   Up 2 minutes (healthy)

Si algo falla, los registros:

docker compose logs -f omada

Paso 3: el asistente inicial

En el navegador: https://IP-DEL-SERVIDOR:8043. El certificado es autofirmado: aceptá el aviso y seguí.

1. Sign In

Con un TP-Link ID se habilita también el acceso por la nube de Omada. Yo elegí Create a Local Account: un usuario que vive solo en este controlador.

La contraseña pide de 8 a 128 caracteres, con mayúscula, minúscula, número y símbolo, y no puede ser igual al usuario. El formulario los va marcando en verde.

2. Set Up Controller

• Controller Name: el que quieras.
• Country/Region: el real. Define qué canales y potencias de WiFi pueden usar los access points.
• Time Zone: (UTC-03:00) Buenos Aires.
• Aceptá los términos y Next.

Aparece una invitación al programa de mejora (datos de uso anónimos):

Es opcional. Yo puse No, thanks.

3. Add Devices

0 Devices Found, y es lo esperable: con el contenedor en bridge, el descubrimiento no funciona (y además el router está en otra red). Skip: los equipos se suman después.

Si usaste network_mode: host y los equipos están en la misma red, acá aparecen. Ojo: si tocás Next con equipos marcados, los adopta y reemplaza la configuración que tenían. Si no estás seguro, Skip.

4. Complete

El usuario y la contraseña de este resumen no son los tuyos: son los que el controlador les pone a los equipos que adopte (el usuario es admin y la clave la genera él). Se cambian en Network Config → General Settings → Site Settings → Device Account.

Go to Dashboard, cerrás el aviso de novedades de la versión 6.3 y aparece el panel:

Un sitio, 0 equipos y Cloud Access: Disabled: el controlador solo se maneja desde la red local.

Paso 4: sumar equipos

Con el contenedor en bridge, cada equipo tiene que saber dónde está el controlador. Las opciones:

• Desde la web del equipo. En el ER605: System Tools → Controller Settings → Controller Inform URL, con la IP del servidor. Lo muestro en la entrada del ER605.
• Opción 138 del DHCP. El servidor DHCP de la red de los equipos les pasa la IP del controlador. Sirve para muchos access points juntos.
• Omada Discovery Utility. Un programa de TP-Link que, desde una PC de la misma red, les avisa a los equipos dónde está el controlador.

Después el equipo aparece en Devices como Pending y se adopta con un clic. En mi caso, la adopción del ER605 queda para cuando el proveedor ponga el módem en modo bridge y el servidor y el router queden en la misma red: va en una próxima entrada.

Reservá la IP del servidor en el router. Los equipos adoptados recuerdan la IP del controlador: si cambia, se desconectan.

Paso 5: backups y actualizaciones

En Settings → Maintenance está el backup:

• Export baja un backup en el momento.
• Backup Schedule programa backups automáticos. Conviene activarlo.

No copies la carpeta data/ con el contenedor andando: MongoDB puede quedar a medio escribir y la copia no sirve. Usá el backup de la web, o pará el contenedor antes.

Para actualizar:

1. Backup desde la web.
2. Cambiá OMADA_VERSION en el .env.
3. Bajá la imagen nueva y recreá el contenedor:

docker compose pull
docker compose up -d

Leé las notas de la versión antes. Y una advertencia importante: no se puede volver a una versión anterior del controlador. Por eso el backup va primero.

Paso 6: guardar el compose en git

El docker-compose.yml, un .env.example y un README.md van a un repositorio privado. El .env real, data/ y logs/ quedan afuera:

.env
data/
logs/

Así, si se rompe el servidor, se clona el repo, se restaura el backup desde la web y listo.

Resumen en comandos

mkdir -p ~/contenedores/omada && cd ~/contenedores/omada
nano docker-compose.yml     # el de arriba
nano .env                   # OMADA_VERSION y TZ
docker compose up -d
docker compose ps           # esperar "healthy"

Y después, https://IP-DEL-SERVIDOR:8043. Diez minutos, contando la descarga de la imagen.