NetAlertX/docs/DEV_PORTS_HOST_MODE.md

Dev Ports in Host Network Mode

When using "--network=host" in the devcontainer, VS Code's normal port forwarding model doesn't apply. All container ports are already on the host network namespace, so:

• Listing ports in forwardPorts can cause VS Code to pre-bind or reserve them (conflicts with startup scripts waiting for a free port).
• The PORTS panel will not auto-detect services reliably, because forwarding isn't occurring.
• Debugger ports (e.g. Xdebug 9003, Python debugpy 5678) can still be listed safely.

Recommended Pattern

1. Only include debugger ports in forwardPorts:

   "forwardPorts": [5678, 9003]
   

2. Do NOT list application service ports (e.g. 20211, 20212) there when in host mode.
3. Use the helper task to enumerate current bindings:
   • Run task: > Tasks: Run Task → [Dev Container] List NetAlertX Ports

Port Enumeration Script

Script: scripts/list-ports.sh Outputs binding address, PID (if resolvable) and process name for key ports.

You can edit the PORTS variable inside that script to add/remove watched ports.

Xdebug Notes

Set in 99-xdebug.ini:

xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.discover_client_host=1

Ensure your IDE is listening on 9003.

Troubleshooting

Symptom	Cause	Fix
Waiting for port 20211 to free... repeats	VS Code pre-bound the port via forwardPorts	Remove the port from forwardPorts, rebuild, retry
PHP request hangs at start	Xdebug trying to connect to unresolved host (host.docker.internal)	Use 127.0.0.1 or rely on discovery
PORTS panel empty	Expected in host mode	Use the port enumeration task

Future Improvements

• Optional: add a small web status endpoint summarizing runtime ports.
• Optional: detect host mode in setup.sh and skip the wait loop if the PID using port is the intended process.