vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-06 17:15:38 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

devcontainer docs

Browse Source 
Signed-off-by: jokob-sk <jokob.sk@gmail.com>
This commit is contained in:
jokob-sk
2025-09-21 10:41:06 +10:00
parent c5610f11e0
commit 4ed1b6e8e6
1 changed files with 12 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/DEV_DEVCONTAINER.md
View File

@@ -1,8 +1,8 @@
### Devcontainer for NetAlertX Guide # Devcontainer for NetAlertX Guide
This devcontainer is designed to mirror the production container environment as closely as possible, while providing a rich set of tools for development. This devcontainer is designed to mirror the production container environment as closely as possible, while providing a rich set of tools for development.
#### How to Get Started ## How to Get Started
1. **Prerequisites:** 1. **Prerequisites:**
* A working **Docker installation** that can be managed by your user. This can be [Docker Desktop](https://www.docker.com/products/docker-desktop/) or Docker Engine installed via other methods (like the official [get-docker script](https://get.docker.com)). * A working **Docker installation** that can be managed by your user. This can be [Docker Desktop](https://www.docker.com/products/docker-desktop/) or Docker Engine installed via other methods (like the official [get-docker script](https://get.docker.com)).
@@ -15,16 +15,18 @@ This devcontainer is designed to mirror the production container environment as
* A notification will pop up in the bottom-right corner asking to **"Reopen in Container"**. Click it. * A notification will pop up in the bottom-right corner asking to **"Reopen in Container"**. Click it.
* VS Code will now build the Docker image and connect your editor to the container. Your terminal, debugger, and all tools will now be running inside this isolated environment. * VS Code will now build the Docker image and connect your editor to the container. Your terminal, debugger, and all tools will now be running inside this isolated environment.
#### Key Workflows & Features ## Key Workflows & Features
Once you're inside the container, everything is set up for you. Once you're inside the container, everything is set up for you.
**1. Services (Frontend & Backend)** ### 1. Services (Frontend & Backend)
![Services](./img/DEV/devcontainer_1.png) ![Services](./img/DEV/devcontainer_1.png)
The container's startup script (`.devcontainer/scripts/setup.sh`) automatically starts the Nginx/PHP frontend and the Python backend. You can restart them at any time using the built-in tasks. The container's startup script (`.devcontainer/scripts/setup.sh`) automatically starts the Nginx/PHP frontend and the Python backend. You can restart them at any time using the built-in tasks.
**2. Integrated Debugging (Just Press F5!)** ### 2. Integrated Debugging (Just Press F5!)
![Debugging](./img/DEV/devcontainer_2.png) ![Debugging](./img/DEV/devcontainer_2.png)
Debugging for both the Python backend and PHP frontend is pre-configured and ready to go. Debugging for both the Python backend and PHP frontend is pre-configured and ready to go.
@@ -32,7 +34,8 @@ Debugging for both the Python backend and PHP frontend is pre-configured and rea
* **Python Backend (debugpy):** The backend automatically starts with a debugger attached on port `5678`. Simply open a Python file (e.g., `server/__main__.py`), set a breakpoint, and press **F5** (or select "Python Backend Debug: Attach") to connect the debugger. * **Python Backend (debugpy):** The backend automatically starts with a debugger attached on port `5678`. Simply open a Python file (e.g., `server/__main__.py`), set a breakpoint, and press **F5** (or select "Python Backend Debug: Attach") to connect the debugger.
* **PHP Frontend (Xdebug):** Xdebug listens on port `9003`. In VS Code, start listening for Xdebug connections and use a browser extension (like "Xdebug helper") to start a debugging session for the web UI. * **PHP Frontend (Xdebug):** Xdebug listens on port `9003`. In VS Code, start listening for Xdebug connections and use a browser extension (like "Xdebug helper") to start a debugging session for the web UI.
**3. Common Tasks (F1 -> Run Task)** ### 3. Common Tasks (F1 -> Run Task)
![Common tasks](./img/DEV/devcontainer_3.png) ![Common tasks](./img/DEV/devcontainer_3.png)
We've created several VS Code Tasks to simplify common operations. Access them by pressing `F1` and typing "Tasks: Run Task". We've created several VS Code Tasks to simplify common operations. Access them by pressing `F1` and typing "Tasks: Run Task".
@@ -41,12 +44,13 @@ We've created several VS Code Tasks to simplify common operations. Access them b
* `Re-Run Startup Script`: Manually re-runs the `.devcontainer/scripts/setup.sh` script to re-link files and restart services. * `Re-Run Startup Script`: Manually re-runs the `.devcontainer/scripts/setup.sh` script to re-link files and restart services.
* `Start Backend (Python)` / `Start Frontend (nginx and PHP-FPM)`: Manually restart the services if needed. * `Start Backend (Python)` / `Start Frontend (nginx and PHP-FPM)`: Manually restart the services if needed.
**4. Running Tests** ### 4. Running Tests
![Running tests](./img/DEV/devcontainer_4.png) ![Running tests](./img/DEV/devcontainer_4.png)
The environment includes `pytest`. You can run tests directly from the VS Code Test Explorer UI or by running `pytest -q` in the integrated terminal. The necessary `PYTHONPATH` is already configured so that tests can correctly import the server modules. The environment includes `pytest`. You can run tests directly from the VS Code Test Explorer UI or by running `pytest -q` in the integrated terminal. The necessary `PYTHONPATH` is already configured so that tests can correctly import the server modules.
### How to Maintain This Devcontainer ## How to Maintain This Devcontainer
The setup is designed to be easy to manage. Here are the core principles: The setup is designed to be easy to manage. Here are the core principles: