[Bug]: Omada Controller Fails to Start as Incus OCI Container (ClassNotFoundException)

[luca-valentini]

Controller Version

5.15.8.2

Describe the Bug

I’m trying to run Omada Controller as an Incus OCI container, but it fails to start with the following error:

INFO: Starting Omada Controller as user omada  
Error: Could not find or load main class com.tplink.smb.omada.starter.OmadaLinuxMain  
Caused by: java.lang.ClassNotFoundException: com.tplink.smb.omada.starter.OmadaLinuxMain  

However, the controller runs successfully inside a Docker container using the same settings. I’d like to run it “natively” in Incus.

Are there any known compatibility issues with Incus, or any debugging steps I can take to resolve this?

Expected Behavior

I'm expecting the container to start correctly.

Steps to Reproduce

incus init docker:mbentley/omada-controller:latest omada-controller -p bridged
incus config set omada-controller boot.autostart true
incus config set omada-controller environment.TZ Europe/London
incus config set omada-controller environment.PUID 508
incus config set omada-controller environment.PGID 508
incus config set omada-controller environment.MANAGE_HTTP_PORT 8088
incus config set omada-controller environment.MANAGE_HTTPS_PORT 8043
incus config set omada-controller environment.PORTAL_HTTP_PORT 8088
incus config set omada-controller environment.PORTAL_HTTPS_PORT 8843
incus config set omada-controller environment.PORT_APP_DISCOVERY 27001
incus config set omada-controller environment.PORT_ADOPT_V1 29812
incus config set omada-controller environment.PORT_UPGRADE_V1 29813
incus config set omada-controller environment.PORT_MANAGER_V1 29811
incus config set omada-controller environment.PORT_MANAGER_V2 29814
incus config set omada-controller environment.PORT_DISCOVERY 29810
incus config set omada-controller environment.PORT_TRANSFER_V2 29815
incus config set omada-controller environment.PORT_RTTY 29816
incus config set omada-controller environment.SHOW_SERVER_LOGS true
incus config set omada-controller environment.SHOW_MONGODB_LOGS true
incus config set omada-controller environment.SSL_CERT_NAME tls.crt
incus config set omada-controller environment.SSL_KEY_NAME tls.key

incus device add omada-controller omada-controller-data disk \
  source=default/containers/omada-controller-data \
  path=/opt/tplink/EAPController/data

incus device add omada-controller omada-controller-logs disk \
  source=default/containers/omada-controller-logs \
  path=/opt/tplink/EAPController/logs

incus start omada-controller

How You're Launching the Container

resource "incus_storage_volume" "omada-controller-data" {
  name = "omada-controller-data"
  pool = incus_storage_pool.main.name
}

resource "incus_storage_volume" "omada-controller-logs" {
  name = "omada-controller-logs"
  pool = incus_storage_pool.main.name
}

resource "incus_instance" "omada-controller" {
  name  = "omada-controller"
  image = "docker:mbentley/omada-controller:latest"

  config = {
    "boot.autostart"                 = true
    "environment.TZ"                 = "Europe/London"
    "environment.PUID"               = "508"
    "environment.PGID"               = "508"
    "environment.MANAGE_HTTP_PORT"   = "8088"
    "environment.MANAGE_HTTPS_PORT"  = "8043"
    "environment.PORTAL_HTTP_PORT"   = "8088"
    "environment.PORTAL_HTTPS_PORT"  = "8843"
    "environment.PORT_APP_DISCOVERY" = "27001"
    "environment.PORT_ADOPT_V1"      = "29812"
    "environment.PORT_UPGRADE_V1"    = "29813"
    "environment.PORT_MANAGER_V1"    = "29811"
    "environment.PORT_MANAGER_V2"    = "29814"
    "environment.PORT_DISCOVERY"     = "29810"
    "environment.PORT_TRANSFER_V2"   = "29815"
    "environment.PORT_RTTY"          = "29816"
    "environment.SHOW_SERVER_LOGS"   = "true"
    "environment.SHOW_MONGODB_LOGS"  = "true"
    "environment.SSL_CERT_NAME"      = "tls.crt"
    "environment.SSL_KEY_NAME"       = "tls.key"
    # "environment.WORKAROUND_509"     = "true"
    # "security.privileged" = true
    # "security.nesting"    = true
    # "raw.lxc" = <<EOF
    #     lxc.execute.cmd = /bin/sh -c 'while true; do sleep 3600; done'
    #     EOF
  }

  profiles = [incus_profile.bridged.name]

  device {
    name = "omada-controller-data"
    type = "disk"
    properties = {
      path   = "/opt/tplink/EAPController/data"
      source = incus_storage_volume.omada-controller-data.name
      pool   = incus_storage_pool.main.name
    }
  }

  device {
    name = "omada-controller-logs"
    type = "disk"
    properties = {
      path   = "/opt/tplink/EAPController/logs"
      source = incus_storage_volume.omada-controller-logs.name
      pool   = incus_storage_pool.main.name
    }
  }
}

Container Logs

INFO: Validating user/group (omada:omada) exists with correct UID/GID (508:508)
INFO: Group (omada) doesn't exist; creating
INFO: User (omada) doesn't exist; creating
INFO: Time zone set to 'Europe/London'
INFO: Value of 'manage.http.port' already set to 8088 in omada.properties
INFO: Value of 'manage.https.port' already set to 8043 in omada.properties
INFO: Value of 'portal.http.port' already set to 8088 in omada.properties
INFO: Value of 'portal.https.port' already set to 8843 in omada.properties
INFO: Value of 'port.adopt.v1' already set to 29812 in omada.properties
INFO: Value of 'port.app.discovery' already set to 27001 in omada.properties
INFO: Value of 'port.upgrade.v1' already set to 29813 in omada.properties
INFO: Value of 'port.manager.v1' already set to 29811 in omada.properties
INFO: Value of 'port.manager.v2' already set to 29814 in omada.properties
INFO: Value of 'port.discovery' already set to 29810 in omada.properties
INFO: Value of 'port.transfer.v2' already set to 29815 in omada.properties
INFO: Value of 'port.rtty' already set to 29816 in omada.properties
INFO: Value of 'mongo.external' already set to false in omada.properties
INFO: Value of 'eap.mongod.uri' already set to mongodb://127.0.0.1:27217/omada in omada.properties
WARN: Ownership not set correctly on '/opt/tplink/EAPController/properties'; setting correct ownership (omada:omada)
INFO: Version check passed; image version (5.15.8.2) >= the last version ran (5.15.8.2); writing image version to last ran file...
INFO: userland/kernel check passed
INFO: output of 'java -version':
openjdk version "17.0.14" 2025-01-21
OpenJDK Runtime Environment (build 17.0.14+7-Ubuntu-120.04)
OpenJDK 64-Bit Server VM (build 17.0.14+7-Ubuntu-120.04, mixed mode, sharing)

INFO: Starting Omada Controller as user omada
tail: cannot open '/opt/tplink/EAPController/logs/mongod.log' for reading: No such file or directory
Error: Could not find or load main class com.tplink.smb.omada.starter.OmadaLinuxMain
Caused by: java.lang.ClassNotFoundException: com.tplink.smb.omada.starter.OmadaLinuxMain

MongoDB Logs

Additional Context

No response

[mbentley]

I converted this to a discussion because it's not a bug with the image.

Anyway, it's likely that your CMD is incorrect, specifically that your classpath is screwed up. The default CMD, removing the formatting from the Dockerfile, is:

java -server -Xms128m -Xmx1024m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/tplink/EAPController/logs/java_heapdump.hprof -Djava.awt.headless=true --add-opens java.base/sun.security.x509=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED -cp /opt/tplink/EAPController/lib/*::/opt/tplink/EAPController/properties: com.tplink.smb.omada.starter.OmadaLinuxMain

I can reproduce this by overriding it using a Docker command w/a classpath that isn't valid:

docker run -it --rm --name test mbentley/omada-controller:5.15 \
  java -server -Xms128m -Xmx1024m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/tplink/EAPController/logs/java_heapdump.hprof -Djava.awt.headless=true --add-opens java.base/sun.security.x509=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED -cp /opt/tplink/EAPController/properties: com.tplink.smb.omada.starter.OmadaLinuxMain

One common issue that might come up would be related to how the asterisk * is handled in the classpath for /opt/tplink/EAPController/lib/*

[luca-valentini]

Thanks! I solved it by overriding the command from the Dockerfile with the one you suggested, and it works 👍
I still don’t understand what happens in the Dockerfile that makes it fail—I’ll investigate in the next few days. In the meantime, these couple of lines did the trick:

    "raw.lxc" = <<EOF
        lxc.execute.cmd = 'java -server -Xms128m -Xmx1024m -XX:MaxHeapFreeRatio=60 -XX:MinHeapFreeRatio=30 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/tplink/EAPController/logs/java_heapdump.hprof -Djava.awt.headless=true --add-opens java.base/sun.security.x509=ALL-UNNAMED --add-opens java.base/sun.security.util=ALL-UNNAMED -cp /opt/tplink/EAPController/lib/*::/opt/tplink/EAPController/properties: com.tplink.smb.omada.starter.OmadaLinuxMain'
        EOF