Tune JVM Heap and Mongo Cache for Omada at 500+ Devices

This configuration overrides the Omada controller's default JVM heap and MongoDB WiredTiger cache to stabilize performance at scale. Internally, the controller launches via /opt/tplink/EAPController/bin/control.sh, which reads JAVA_OPTS from /opt/tplink/EAPController/properties/omada.properties and the launcher scripts. The default heap is often 512 MB or 1 GB, which is fine for 50 devices but causes aggressive GC pauses and dashboard timeouts above 300 devices because the controller keeps per-device RRD-like stat objects and site topology graphs in memory. MongoDB's default cache is 50 percent of RAM minus 1 GB, which can starve the controller if the same host runs both.

In production, right-size both: give the JVM roughly 2-4 GB for 500-1000 devices and cap Mongo at 2-4 GB on a dedicated 8-16 GB VM. This eliminates the classic 3 AM 'controller unreachable' alerts caused by stop-the-world GC during nightly statistics aggregation. It is also the correct fix before enabling Omada's built-in analytics or long retention windows.

Security and pitfalls: increasing heap does not fix a MongoDB that is running out of disk, so monitor both. Do not set Xmx above 50 percent of host RAM or the OOM killer will terminate the controller under load. Restart the controller during a maintenance window, since a JVM restart drops all live device sessions and forces re-inform, briefly showing devices as 'adopting'. Verify with jstat and db.serverStatus().wiredTiger.cache after the change.

> System.Execute()

sudo sed -i 's/^JAVA_OPTS=.*/JAVA_OPTS="-Xms2048m -Xmx4096m -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -Dfile.encoding=UTF-8"/' \
  /opt/tplink/EAPController/properties/omada.properties
sudo tee -a /etc/mongod.conf >/dev/null <<'EOF'
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 3
EOF
sudo systemctl daemon-reload
sudo systemctl restart mongod
sudo systemctl restart tpeap
sleep 30
jcmd $(pgrep -f Omada) VM.flags | tr ' ' '\n' | grep -Ei 'MaxHeapSize|InitialHeapSize'

> Architecture & Security Context

Verified for Valters IT Hub. When deploying this configuration in a production homelab or enterprise environment, ensure that you monitor system resources and implement strict access controls. Administrator privileges are required.

ID: VALTERSIT-441BAFDE3A09