NetAlertX/.devcontainer/README.md

NetAlertX Devcontainer Notes

This devcontainer replicates the production container as closely as practical, with a few development-oriented differences.

Key behavior

• No init process: Services are managed by shell scripts using killall, setsid, and nohup. Startup and restarts are script-driven rather than supervised by an init system.
• Autogenerated Dockerfile: The effective devcontainer Dockerfile is generated on demand by .devcontainer/scripts/generate-dockerfile.sh. It combines the root Dockerfile (with certain COPY instructions removed) and an extra "devcontainer" stage from .devcontainer/resources/devcontainer-Dockerfile. When you change the resource Dockerfile, re-run the generator to refresh .devcontainer/Dockerfile.
• Where to put setup: Prefer baking setup into .devcontainer/resources/devcontainer-Dockerfile. Use .devcontainer/scripts/setup.sh only for steps that must happen at container start (e.g., cleaning up nginx/php ownership, creating directories, touching runtime files) or depend on runtime paths.

Debugging (F5) The Frontend and backend run in debug mode always. You can attach your debugger at any time.

• Python Backend Debug: Attach - The backend runs with a debugger on port 5678. Set breakpoints in the code and press F5 to begin triggering them.
• PHP Frontend (XDebug) Xdebug listens on 9003. Start listening and use an Xdebug extension in your browser to debug PHP.

Common workflows (F1->Tasks: Run Task)

• Regenerate the devcontainer Dockerfile: Run the VS Code task "Generate Dockerfile" or execute .devcontainer/scripts/generate-dockerfile.sh. The result is .devcontainer/Dockerfile.
• Re-run startup provisioning: Use the task "Re-Run Startup Script" to execute .devcontainer/scripts/setup.sh in the container.
• Start services:
  • Backend (GraphQL/Flask): .devcontainer/scripts/restart-backend.sh starts it under debugpy and logs to /app/log/app.log
  • Frontend (nginx + PHP-FPM): Started via setup.sh; can be restarted by the task "Start Frontend (nginx and PHP-FPM)".

Production Container Evaulation

1. F1 → Tasks: Shutdown services ([Dev Container] Stop Frontend & Backend Services)
2. F1 → Tasks: Docker system and build prune ([Any] Docker system and build Prune)
3. F1 → Remote: Close Unused Forwarded Ports (VS Code command)
4. F1 → Tasks: Build & Launch Production (Build & Launch Prodcution Docker
5. visit http://localhost:20211

Unit tests

1. F1 → Tasks: Rebuild test container ([Any] Build Unit Test Docker image)
2. F1 → Test: Run all tests

Testing

• pytest is installed via Alpine packages (py3-pytest, py3-pytest-cov).
• PYTHONPATH includes workspace and venv site-packages so tests can import server/* modules and third-party libs.
• Run tests via VS Code Pytest Runner or pytest -q from the workspace root.

Conventions

• Don’t edit .devcontainer/Dockerfile directly; edit .devcontainer/resources/devcontainer-Dockerfile and regenerate.
• Keep setup in the resource Dockerfile when possible; reserve setup.sh for runtime fixes.
• Avoid hardcoding ports/secrets; prefer existing settings and helpers (see .github/copilot-instructions.md).