[Help]:

[adpal06]

Controller Version

v5.15.24.18

Describe Your Issue or Question

Hi, first of all, thank you for your amazing work on this image – it’s really appreciated.

I'm using your Docker container to host the Omada controller on a Proxmox VM in my basement, and I run it in production to manage around 17 clients and over 100 devices.

Everything was working fine initially, but recently I’ve been experiencing noticeable slowdowns in the web UI and performance issues when handling the load.

After some analysis, I noticed that the Java process in the container is hard-limited to 1024MB of maximum heap memory (-Xmx1024m). I suspect this limitation might be the reason for these slowdowns, especially given the scale I’m working with.

Expected Behavior

Ideally, the container should either:

Automatically scale the Java heap memory according to available system memory, or

Allow easy configuration (via an env var or documented method) to increase the memory cap for larger deployments.

Steps to Reproduce

Run the container with a mid- to large-scale network (100+ devices).

Observe increasing slowness in the Omada web interface and higher CPU usage.

Check Java memory with cat /proc/1/cmdline and see it is limited to -Xmx1024m.

How You're Launching the Container

services:
  omada-controller:
    container_name: omada-novolink
    image: mbentley/omada-controller:latest-chromium
    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:

Container Logs

No explicit errors are reported in the logs – the application starts normally and is marked as healthy. However, docker stats shows high CPU usage (~40–50%) and 2.3+ GB RAM usage, while the Java heap is stuck at 1024MB max.

MongoDB Logs

No response

Additional Context

I'm not looking to fork or modify the image, and I'd prefer to follow your supported setup. Is there an officially supported or recommended way to increase the Java heap memory for larger deployments like this one?

Thank you again for your great work!

[mbentley]

As configured right now, the way to modify it would be to override the CMD. I know that it is a bit annoying to have to do, especially since if there are modifications to the default CMD, you'd need to manage those but right now, that's what it is. The default 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 so you can start from that and modify it.

Longer term, I could look at other patterns for allowing setting either custom options with an env var or something but of course I also don't want to break anyone's controller config if they've also overwritten the default CMD.

[adpal06]

Hi,

Thanks again for your help and for your great availability!

I'm not very familiar with Docker and how it works under the hood, especially when it comes to overriding things like the CMD from a Docker image. I'm currently using Docker Compose to run the container, but I'm not exactly sure how to apply your suggestion using Compose to change the Java parameters.

Would you happen to have an example of how to do that in a docker-compose.yml file?

Again, thank you very much for your support and for maintaining this awesome project!

Best regards

[mbentley]

*edit: see the next answer as there is a better way that overriding what is at the CLI

[mbentley]

I did some more searching because I could have sworn there was a way to even override options set at the CLI and this stackoverflow answer had it. So there is one other way that is much easier to override it with the environment variable _JAVA_OPTIONS so something like: _JAVA_OPTIONS="-Xms512m -Xmx2048m" set would override what is set on the command line so here is a compose example that does it that way:

services:
  omada-controller:
    container_name: omada-novolink
    image: mbentley/omada-controller:latest-chromium
    restart: unless-stopped
    ulimits:
      nofile:
        soft: 4096
        hard: 8192
    stop_grace_period: 60s
    network_mode: host
    environment:
      - _JAVA_OPTIONS=-Xms512m -Xmx2048m
      - 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:

[adpal06]

Hi,

Thank you very much for your detailed reply — I’ll give it a try and see if it works!

Your GitHub repo is absolutely great. I actually mentioned it during meetings with the TP-Link France teams. I’ve shared it with several technicians so they can promote your work and help others benefit from it as well.

I brought it up while doing my training and certification on TP-Link networking equipment.

Thanks again for everything, and have a great day!

Best regards,

[mbentley]

I appreciate the feedback - glad that it's been helpful!

[adpal06]

Hi again,

Thanks a lot for your time and your suggestion regarding the _JAVA_OPTIONS environment variable.

I just tested the updated docker-compose.yml using the method you described, but unfortunately it doesn’t seem to have any effect. Here's the compose snippet I used:

yaml
services:
omada-controller:
container_name: omada-novolink
image: mbentley/omada-controller:latest-chromium
restart: unless-stopped
ulimits:
nofile:
soft: 4096
hard: 8192
stop_grace_period: 60s
network_mode: host
environment:
- _JAVA_OPTIONS=-Xms512m -Xmx4096m
- 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
After restarting the container and checking the Java process with:

docker exec -it omada-novolink cat /proc/1/cmdline | tr '\0' ' '
…the Java heap size still shows as -Xmx1024m, and not the expected 4096m.

It looks like the _JAVA_OPTIONS variable is being ignored in this case, or maybe overridden by the CMD explicitly defined in the image.

Let me know if you have any other suggestions! Thanks again for your great work and your availability — it’s really appreciated.

Best regards,

[mbentley]

Looking at the process list will still show the previous options because that is what was passed as command line parameters as the literal command. The internal logic in the java process overrides what was passed on the CLI parameters.

Here is a quick docker run based example with a test controller:

docker run -it --rm -e _JAVA_OPTIONS="-Xms1 -Xmx1" mbentley/omada-controller:5.15
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 'Etc/UTC'
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/data'; setting correct ownership (omada:omada)
WARN: Ownership not set correctly on '/opt/tplink/EAPController/logs'; setting correct ownership (omada:omada)
WARN: Ownership not set correctly on '/opt/tplink/EAPController/properties'; setting correct ownership (omada:omada)
INFO: Version check passed; image version (5.15.24.18) >= the last version ran (0.0.0); writing image version to last ran file...
INFO: userland/kernel check passed
INFO: output of 'java -version':
Picked up _JAVA_OPTIONS: -Xms1 -Xmx1
Error occurred during initialization of VM
Too small maximum heap


##############################################################################
##############################################################################
WARN: autobackup directory not found! Please configure automatic backups!
  For instructions, see https://github.com/mbentley/docker-omada-controller#controller-backups
##############################################################################
##############################################################################

INFO: Starting Omada Controller as user omada
tail: cannot open '/opt/tplink/EAPController/logs/server.log' for reading: No such file or directory
Picked up _JAVA_OPTIONS: -Xms1 -Xmx1
Error occurred during initialization of VM
Too small maximum heap

You should see a line similar to this indicating that the process has picked up the env var:

Picked up _JAVA_OPTIONS: -Xms1 -Xmx1

As a matter of fact, try to set it to 1 for both options and you should see the controller fail to start with the same message.