From 32c21b01bb541825df1dd9f9ca0014824993ab15 Mon Sep 17 00:00:00 2001 From: PlanBot Date: Wed, 18 Feb 2026 16:42:17 -0500 Subject: [PATCH] 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: