From 32c21b01bb541825df1dd9f9ca0014824993ab15 Mon Sep 17 00:00:00 2001 From: PlanBot Date: Wed, 18 Feb 2026 16:42:17 -0500 Subject: [PATCH 1/7] feat(docs): Update Docker install guide and templates - Add --force-recreate to install commands for easier version switching - Remove debug flags (ALWAYS_FRESH_INSTALL, NETALERTX_DEBUG) from templates - Link to official DOCKER_COMPOSE environment variable docs --- install/docker/README.md | 49 +++++++++++++++++++++++++++ install/docker/docker-compose.dev.yml | 44 ++++++++++++++++++++++++ install/docker/docker-compose.yml | 44 ++++++++++++++++++++++++ 3 files changed, 137 insertions(+) create mode 100644 install/docker/README.md create mode 100644 install/docker/docker-compose.dev.yml create mode 100644 install/docker/docker-compose.yml diff --git a/install/docker/README.md b/install/docker/README.md new file mode 100644 index 00000000..a0adc638 --- /dev/null +++ b/install/docker/README.md @@ -0,0 +1,49 @@ +# 🐳 Docker Compose Installation + +This folder provides standard Docker Compose configurations to get **NetAlertX** up and running quickly. This method is ideal for users on **Proxmox**, **TrueNAS Scale**, **Portainer**, or standard Linux hosts who prefer a simple, declarative setup. + +## 🚀 Getting Started + +### 1. Choose your flavor + +* **Stable (Recommended):** Use `docker-compose.yml`. This tracks the latest stable release. +* **Development:** Use `docker-compose.dev.yml`. This tracks the `dev` branch and contains the latest features (and potential bugs). + +### 2. Deploy + +Download the chosen file to a directory on your server (e.g., `netalertx/`). You can switch between Stable and Dev versions easily by pointing to the specific file. + +**For Stable:** +```bash +docker compose -f docker-compose.yml up -d --force-recreate +``` + +**For Development:** +```bash +docker compose -f docker-compose.dev.yml up -d --force-recreate +``` + +> [!NOTE] +> The `--force-recreate` flag ensures that your container is rebuilt with the latest configuration, making it seamless to switch between versions. Initial startup might take a few minutes. + +## ⚙️ Configuration + +### Storage +By default, these files use a **Docker Named Volume** (`netalertx_data`) for persistent storage. This is the easiest way to get started and ensures data persists across upgrades. + +> [!TIP] +> If you prefer to map a specific folder on your host (e.g., `/mnt/data/netalertx` on Proxmox or TrueNAS), edit the `volumes` section in the compose file to use a **bind mount** instead. + +### Networking +The container uses `network_mode: host` by default. This is **required** for core features like ARP scanning (`arp-scan`) to work correctly, as the container needs direct access to the network interface to discover devices. + +### Environment Variables +You can customize the application by editing the `environment` section in the compose file. Common overrides include: + +* `TZ`: Timezone (mapped via `/etc/localtime`). +* `SCAN_SUBNETS`: Define specific subnets to scan if auto-detection fails (e.g., `192.168.1.0/24`). + +For a full list of environment variables and configuration options, see the [Customize with Environment Variables](https://docs.netalertx.com/DOCKER_COMPOSE/?h=environmental+variables#customize-with-environmental-variables) section in the documentation. + +--- +[⬅️ Back to Main Repo](../../README.md) diff --git a/install/docker/docker-compose.dev.yml b/install/docker/docker-compose.dev.yml new file mode 100644 index 00000000..dae1069f --- /dev/null +++ b/install/docker/docker-compose.dev.yml @@ -0,0 +1,44 @@ +services: + netalertx: + network_mode: host # Use host networking for ARP scanning and other services + image: ghcr.io/netalertx/netalertx-dev:latest + container_name: netalertx + read_only: true + cap_drop: + - ALL + cap_add: + - NET_ADMIN + - NET_RAW + - NET_BIND_SERVICE + - CHOWN + - SETUID + - SETGID + volumes: + - type: volume + source: netalertx_data + target: /data + read_only: false + - type: bind + source: /etc/localtime + target: /etc/localtime + read_only: true + tmpfs: + - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev,async,noatime,nodiratime" + environment: + PUID: ${NETALERTX_UID:-20211} + PGID: ${NETALERTX_GID:-20211} + LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} + PORT: ${PORT:-20211} + GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} + mem_limit: 2048m + mem_reservation: 1024m + cpu_shares: 512 + pids_limit: 512 + logging: + options: + max-size: "10m" + max-file: "3" + restart: unless-stopped + +volumes: + netalertx_data: diff --git a/install/docker/docker-compose.yml b/install/docker/docker-compose.yml new file mode 100644 index 00000000..6622efcc --- /dev/null +++ b/install/docker/docker-compose.yml @@ -0,0 +1,44 @@ +services: + netalertx: + network_mode: host # Use host networking for ARP scanning and other services + image: ghcr.io/netalertx/netalertx:latest + container_name: netalertx + read_only: true + cap_drop: + - ALL + cap_add: + - NET_ADMIN + - NET_RAW + - NET_BIND_SERVICE + - CHOWN + - SETUID + - SETGID + volumes: + - type: volume + source: netalertx_data + target: /data + read_only: false + - type: bind + source: /etc/localtime + target: /etc/localtime + read_only: true + tmpfs: + - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev,async,noatime,nodiratime" + environment: + PUID: ${NETALERTX_UID:-20211} + PGID: ${NETALERTX_GID:-20211} + LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} + PORT: ${PORT:-20211} + GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} + mem_limit: 2048m + mem_reservation: 1024m + cpu_shares: 512 + pids_limit: 512 + logging: + options: + max-size: "10m" + max-file: "3" + restart: unless-stopped + +volumes: + netalertx_data: From 53b2596902c6c844bd7dcb570d937fffbdb39c59 Mon Sep 17 00:00:00 2001 From: Adam Outler Date: Mon, 23 Feb 2026 03:04:43 +0000 Subject: [PATCH 2/7] Add LLMs.txt --- front/llms.txt | 48 ++++++++++++++++++++++++++++++++++ front/php/templates/footer.php | 3 +-- 2 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 front/llms.txt diff --git a/front/llms.txt b/front/llms.txt new file mode 100644 index 00000000..4c93ef1c --- /dev/null +++ b/front/llms.txt @@ -0,0 +1,48 @@ +# For Humans +To set up MCP access for your AI Agent: + +1. Tell it to "Please go here and set up MCP using HOST:BACKEND_PORT " +-or- +2. Copy and paste the contents of this page and let it know your + + + +--- + +# For AI Agents: NetAlertX MCP Setup + +NetAlertX is a network monitoring system. Connect to its **MCP (Model Context Protocol) server** for live access to devices, scans, and events. + +## 1. Gather Connection Details +Ask the user for the following if not provided: +1. **API Token:** Found in **`/settings.php`** under **System / API**. If you were directed to this server, try to browse to /settings.php on your own. +2. **MCP URL:** Typically `http://:20212/mcp/sse`. (The UI is usually on port `20211`, and the MCP/GraphQL backend is on `20212`). + +*Note: Test HTTP connectivity. If port `20212` fails, ask the user if the `GRAPHQL_PORT` was changed in settings or if a reverse proxy is used.* + +## 2. Configure MCP Client +Use the gathered details to configure your MCP connection: + +```json +{ + "mcpServers": { + "netalertx": { + "url": "http://:/mcp/sse", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +## 3. Capabilities +Once connected, you can: +- Query and manage devices (search, filter, MAC details, Wake-on-LAN). +- Trigger network scans (ARP, NMAP, Avahi). +- Manage events, sessions, and notifications. + +## 4. Important Notes +- **UI Refresh:** When you modify data, tell the user to click the in-app refresh button (🔄) to see changes. +- **REST API Fallback:** If MCP is unavailable, use the REST API at `http://:/openapi.json`. All calls must be made with `Authorization: Bearer `. This page API is manual, relies on your abilities, and context-heavy so only use it as a last resort. +- **Authentication:** The API token is distinct from the UI login password and must be obtained/changed in the frontend /settings.php diff --git a/front/php/templates/footer.php b/front/php/templates/footer.php index 5b4058e9..02caeaff 100755 --- a/front/php/templates/footer.php +++ b/front/php/templates/footer.php @@ -24,11 +24,10 @@ NetAlertx - -
| + | | | | From cb0b3b607d76dd43ff6dff0a9fdb2fc94108af8a Mon Sep 17 00:00:00 2001 From: Adam Outler Date: Sun, 22 Feb 2026 22:11:40 -0500 Subject: [PATCH 3/7] Update front/llms.txt Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- front/llms.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/front/llms.txt b/front/llms.txt index 4c93ef1c..0242ddd4 100644 --- a/front/llms.txt +++ b/front/llms.txt @@ -45,4 +45,4 @@ Once connected, you can: ## 4. Important Notes - **UI Refresh:** When you modify data, tell the user to click the in-app refresh button (🔄) to see changes. - **REST API Fallback:** If MCP is unavailable, use the REST API at `http://:/openapi.json`. All calls must be made with `Authorization: Bearer `. This page API is manual, relies on your abilities, and context-heavy so only use it as a last resort. -- **Authentication:** The API token is distinct from the UI login password and must be obtained/changed in the frontend /settings.php +- **Authentication:** The API token is distinct from the UI login password and must be obtained/changed in the frontend /settings.php. From fe226597944b1db1320ede039b94de835a22eb51 Mon Sep 17 00:00:00 2001 From: Adam Outler Date: Mon, 23 Feb 2026 03:15:21 +0000 Subject: [PATCH 4/7] coderabbit suggested changes --- front/llms.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/front/llms.txt b/front/llms.txt index 0242ddd4..d7cfd670 100644 --- a/front/llms.txt +++ b/front/llms.txt @@ -3,7 +3,7 @@ To set up MCP access for your AI Agent: 1. Tell it to "Please go here and set up MCP using HOST:BACKEND_PORT " -or- -2. Copy and paste the contents of this page and let it know your +2. Copy and paste the contents of this page and let it know your HOST and API token. @@ -44,5 +44,5 @@ Once connected, you can: ## 4. Important Notes - **UI Refresh:** When you modify data, tell the user to click the in-app refresh button (🔄) to see changes. -- **REST API Fallback:** If MCP is unavailable, use the REST API at `http://:/openapi.json`. All calls must be made with `Authorization: Bearer `. This page API is manual, relies on your abilities, and context-heavy so only use it as a last resort. -- **Authentication:** The API token is distinct from the UI login password and must be obtained/changed in the frontend /settings.php. +- **REST API Fallback:** If MCP is unavailable, retrieve the OpenAPI spec from `http://:/openapi.json` to discover available endpoints, then call those endpoints with `Authorization: Bearer `. This approach is context-heavy and manual, so use it as a last resort. +- **Authentication:** The API token is distinct from the UI login password and must be obtained/changed in the frontend /settings.php From 4316a436ebd0024cfb827f3f5eff041932cd509c Mon Sep 17 00:00:00 2001 From: MrMeatikins Date: Sun, 22 Feb 2026 22:20:28 -0500 Subject: [PATCH 5/7] Apply CodeRabbit suggestions --- .env | 2 +- install/docker/README.md | 4 ++-- install/docker/docker-compose.dev.yml | 8 ++++---- install/docker/docker-compose.yml | 8 ++++---- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.env b/.env index 9344583d..128ddcbc 100755 --- a/.env +++ b/.env @@ -7,7 +7,7 @@ LOGS_LOCATION=/path/to/docker_logs #ENVIRONMENT VARIABLES TZ=Europe/Paris -PORT=20211 +NETALERTX_PORT=20211 #DEVELOPMENT VARIABLES diff --git a/install/docker/README.md b/install/docker/README.md index a0adc638..d6267ba1 100644 --- a/install/docker/README.md +++ b/install/docker/README.md @@ -40,8 +40,8 @@ The container uses `network_mode: host` by default. This is **required** for cor ### Environment Variables You can customize the application by editing the `environment` section in the compose file. Common overrides include: -* `TZ`: Timezone (mapped via `/etc/localtime`). -* `SCAN_SUBNETS`: Define specific subnets to scan if auto-detection fails (e.g., `192.168.1.0/24`). +* Timezone is controlled by the read-only `/etc/localtime` bind mount (do not use a `TZ` variable). +* `SCAN_SUBNETS`: Not present by default in the compose `environment` blocks. You must manually add it if you need to override subnet scanning (e.g., `192.168.1.0/24`). For a full list of environment variables and configuration options, see the [Customize with Environment Variables](https://docs.netalertx.com/DOCKER_COMPOSE/?h=environmental+variables#customize-with-environmental-variables) section in the documentation. diff --git a/install/docker/docker-compose.dev.yml b/install/docker/docker-compose.dev.yml index dae1069f..a2c12b24 100644 --- a/install/docker/docker-compose.dev.yml +++ b/install/docker/docker-compose.dev.yml @@ -23,13 +23,13 @@ services: target: /etc/localtime read_only: true tmpfs: - - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev,async,noatime,nodiratime" + - "/tmp:mode=1777,rw,noexec,nosuid,nodev,async,noatime,nodiratime" environment: PUID: ${NETALERTX_UID:-20211} PGID: ${NETALERTX_GID:-20211} - LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} - PORT: ${PORT:-20211} - GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} + LISTEN_ADDR: ${NETALERTX_LISTEN_ADDR:-0.0.0.0} + PORT: ${NETALERTX_PORT:-20211} + GRAPHQL_PORT: ${NETALERTX_GRAPHQL_PORT:-20212} mem_limit: 2048m mem_reservation: 1024m cpu_shares: 512 diff --git a/install/docker/docker-compose.yml b/install/docker/docker-compose.yml index 6622efcc..5dea86b0 100644 --- a/install/docker/docker-compose.yml +++ b/install/docker/docker-compose.yml @@ -23,13 +23,13 @@ services: target: /etc/localtime read_only: true tmpfs: - - "/tmp:mode=1700,uid=0,gid=0,rw,noexec,nosuid,nodev,async,noatime,nodiratime" + - "/tmp:mode=1777,rw,noexec,nosuid,nodev,async,noatime,nodiratime" environment: PUID: ${NETALERTX_UID:-20211} PGID: ${NETALERTX_GID:-20211} - LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} - PORT: ${PORT:-20211} - GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} + LISTEN_ADDR: ${NETALERTX_LISTEN_ADDR:-0.0.0.0} + PORT: ${NETALERTX_PORT:-20211} + GRAPHQL_PORT: ${NETALERTX_GRAPHQL_PORT:-20212} mem_limit: 2048m mem_reservation: 1024m cpu_shares: 512 From c7e754966ee7483a7e8cade8e1bb0898fedf0ac6 Mon Sep 17 00:00:00 2001 From: MrMeatikins Date: Sun, 22 Feb 2026 22:22:21 -0500 Subject: [PATCH 6/7] Simplify README to link official docs --- install/docker/README.md | 45 ++-------------------------------------- 1 file changed, 2 insertions(+), 43 deletions(-) diff --git a/install/docker/README.md b/install/docker/README.md index d6267ba1..b07768b3 100644 --- a/install/docker/README.md +++ b/install/docker/README.md @@ -1,49 +1,8 @@ # 🐳 Docker Compose Installation -This folder provides standard Docker Compose configurations to get **NetAlertX** up and running quickly. This method is ideal for users on **Proxmox**, **TrueNAS Scale**, **Portainer**, or standard Linux hosts who prefer a simple, declarative setup. +For complete and up-to-date instructions on how to install NetAlertX using Docker, including volumes, networking, and environment variables, please refer to the official documentation: -## 🚀 Getting Started - -### 1. Choose your flavor - -* **Stable (Recommended):** Use `docker-compose.yml`. This tracks the latest stable release. -* **Development:** Use `docker-compose.dev.yml`. This tracks the `dev` branch and contains the latest features (and potential bugs). - -### 2. Deploy - -Download the chosen file to a directory on your server (e.g., `netalertx/`). You can switch between Stable and Dev versions easily by pointing to the specific file. - -**For Stable:** -```bash -docker compose -f docker-compose.yml up -d --force-recreate -``` - -**For Development:** -```bash -docker compose -f docker-compose.dev.yml up -d --force-recreate -``` - -> [!NOTE] -> The `--force-recreate` flag ensures that your container is rebuilt with the latest configuration, making it seamless to switch between versions. Initial startup might take a few minutes. - -## ⚙️ Configuration - -### Storage -By default, these files use a **Docker Named Volume** (`netalertx_data`) for persistent storage. This is the easiest way to get started and ensures data persists across upgrades. - -> [!TIP] -> If you prefer to map a specific folder on your host (e.g., `/mnt/data/netalertx` on Proxmox or TrueNAS), edit the `volumes` section in the compose file to use a **bind mount** instead. - -### Networking -The container uses `network_mode: host` by default. This is **required** for core features like ARP scanning (`arp-scan`) to work correctly, as the container needs direct access to the network interface to discover devices. - -### Environment Variables -You can customize the application by editing the `environment` section in the compose file. Common overrides include: - -* Timezone is controlled by the read-only `/etc/localtime` bind mount (do not use a `TZ` variable). -* `SCAN_SUBNETS`: Not present by default in the compose `environment` blocks. You must manually add it if you need to override subnet scanning (e.g., `192.168.1.0/24`). - -For a full list of environment variables and configuration options, see the [Customize with Environment Variables](https://docs.netalertx.com/DOCKER_COMPOSE/?h=environmental+variables#customize-with-environmental-variables) section in the documentation. +👉 **[NetAlertX Docker Installation Guide](https://docs.netalertx.com/DOCKER_INSTALLATION/)** --- [⬅️ Back to Main Repo](../../README.md) From 14625926f95861d80ebcbaa18c0b61c8f42d3fd8 Mon Sep 17 00:00:00 2001 From: MrMeatikins Date: Sun, 22 Feb 2026 22:37:24 -0500 Subject: [PATCH 7/7] Revert env variables per jokob-sk review Co-authored-by: jokob-sk --- .env | 3 +-- install/docker/docker-compose.dev.yml | 6 +++--- install/docker/docker-compose.yml | 6 +++--- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/.env b/.env index 128ddcbc..7ab4755d 100755 --- a/.env +++ b/.env @@ -6,8 +6,7 @@ LOGS_LOCATION=/path/to/docker_logs #ENVIRONMENT VARIABLES -TZ=Europe/Paris -NETALERTX_PORT=20211 +PORT=20211 #DEVELOPMENT VARIABLES diff --git a/install/docker/docker-compose.dev.yml b/install/docker/docker-compose.dev.yml index a2c12b24..6854934b 100644 --- a/install/docker/docker-compose.dev.yml +++ b/install/docker/docker-compose.dev.yml @@ -27,9 +27,9 @@ services: environment: PUID: ${NETALERTX_UID:-20211} PGID: ${NETALERTX_GID:-20211} - LISTEN_ADDR: ${NETALERTX_LISTEN_ADDR:-0.0.0.0} - PORT: ${NETALERTX_PORT:-20211} - GRAPHQL_PORT: ${NETALERTX_GRAPHQL_PORT:-20212} + LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} + PORT: ${PORT:-20211} + GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} mem_limit: 2048m mem_reservation: 1024m cpu_shares: 512 diff --git a/install/docker/docker-compose.yml b/install/docker/docker-compose.yml index 5dea86b0..3f842a62 100644 --- a/install/docker/docker-compose.yml +++ b/install/docker/docker-compose.yml @@ -27,9 +27,9 @@ services: environment: PUID: ${NETALERTX_UID:-20211} PGID: ${NETALERTX_GID:-20211} - LISTEN_ADDR: ${NETALERTX_LISTEN_ADDR:-0.0.0.0} - PORT: ${NETALERTX_PORT:-20211} - GRAPHQL_PORT: ${NETALERTX_GRAPHQL_PORT:-20212} + LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0} + PORT: ${PORT:-20211} + GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} mem_limit: 2048m mem_reservation: 1024m cpu_shares: 512