MERGE: resolve conflicts

Signed-off-by: jokob-sk <jokob.sk@gmail.com>

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-dockerfile.sh
+# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh
 
 # ---/Dockerfile---
 # The NetAlertX Dockerfile has 3 stages:
@@ -46,14 +46,16 @@ ARG INSTALL_DIR=/app
 
 # NetAlertX app directories
 ENV NETALERTX_APP=${INSTALL_DIR}
-ENV NETALERTX_CONFIG=${NETALERTX_APP}/config
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
 ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
 ENV NETALERTX_SERVER=${NETALERTX_APP}/server
-ENV NETALERTX_API=${NETALERTX_APP}/api
+ENV NETALERTX_API=/tmp/api
-ENV NETALERTX_DB=${NETALERTX_APP}/db
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
 ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
 ENV NETALERTX_BACK=${NETALERTX_APP}/back
-ENV NETALERTX_LOG=${NETALERTX_APP}/log
+ENV NETALERTX_LOG=/tmp/log
 ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
 ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
@@ -70,31 +72,35 @@ ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
 ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
 ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
 ENV LOG_CROND=${NETALERTX_LOG}/crond.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
 # System Services configuration files
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
 ENV SYSTEM_SERVICES=/services
 ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
 ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
 ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
 ENV SYSTEM_NGINX_CONFIG_FILE=${SYSTEM_NGINX_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
 ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
 ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
 ENV SYSTEM_SERVICES_CROND=${SYSTEM_SERVICES_CONFIG}/crond
-ENV SYSTEM_SERVICES_RUN=${SYSTEM_SERVICES}/run
+ENV SYSTEM_SERVICES_RUN=/tmp/run
 ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
 ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
 ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
 ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
-                       ${SYSTEM_SERVICES_CONFIG}"
+                       ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
-ENV READ_WRITE_FOLDERS="${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} ${NETALERTX_LOG} \
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
-                       ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} ${SYSTEM_SERVICES_RUN_TMP} \
+                       ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
-                       ${SYSTEM_SERVICES_RUN_LOG}"
+                       ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+                       ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
 #Python environment
 ENV PYTHONUNBUFFERED=1 
 ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
-ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${VIRTUAL_ENV}/lib/python3.12/site-packages
+ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.12/site-packages
 ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH" 
 
 # App Environment
@@ -102,8 +108,7 @@ ENV LISTEN_ADDR=0.0.0.0
 ENV PORT=20211
 ENV NETALERTX_DEBUG=0
 ENV VENDORSPATH=/app/back/ieee-oui.txt
-ENV VENDORSPATH_NEWEST=/services/run/tmp/ieee-oui.txt
+ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
-ENV PYTHONPATHPATH="${NETALERTX_APP}:${VIRTUAL_ENV}/bin:${PATH}"
 ENV ENVIRONMENT=alpine
 ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
 ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
@@ -127,8 +132,9 @@ COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
-RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 755 ${NETALERTX_API}  \
+
-    ${NETALERTX_LOG} ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} && \
+# Create required folders with correct ownership and permissions
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
     sh -c "find ${NETALERTX_APP} -type f \( -name '*.sh' -o -name 'speedtest-cli' \) \
     -exec chmod 750 {} \;"
 
@@ -146,13 +152,14 @@ RUN apk add libcap && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/arp-scan && \
     setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nbtscan && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/traceroute && \
-    setcap cap_net_raw,cap_net_admin+eip ${VIRTUAL_ENV_BIN}/scapy && \
+    setcap cap_net_raw,cap_net_admin+eip $(readlink -f ${VIRTUAL_ENV_BIN}/python) && \
     /bin/sh /build/init-nginx.sh && \
     /bin/sh /build/init-php-fpm.sh && \
     /bin/sh /build/init-crond.sh && \
     /bin/sh /build/init-backend.sh && \
     rm -rf /build && \
-    apk del libcap
+    apk del libcap && \
+    date +%s > ${NETALERTX_FRONT}/buildtimestamp.txt
 
 
 ENTRYPOINT ["/bin/sh","/entrypoint.sh"]
@@ -184,7 +191,10 @@ RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     chmod -R 600 ${READ_WRITE_FOLDERS} && \
     find ${READ_WRITE_FOLDERS} -type d -exec chmod 700 {} + && \
     chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /opt /opt/venv && \
-    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh /app /opt /opt/venv && \
+    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    for dir in ${READ_WRITE_FOLDERS}; do \
+        install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 "$dir"; \
+    done && \
     apk del apk-tools && \
     rm -Rf /var /etc/sudoers.d/* /etc/shadow /etc/gshadow /etc/sudoers \
     /lib/apk /lib/firmware /lib/modules-load.d /lib/sysctl.d /mnt /home/ /root \
@@ -206,11 +216,14 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
 #   .devcontainer/scripts/generate-configs.sh
 # The generator appends this stage to produce .devcontainer/Dockerfile.
 # Prefer to place dev-only setup here; use setup.sh only for runtime fixes.
+# Permissions in devcontainer should be of a brutalist nature. They will be
+# Open and wide to avoid permission issues during development allowing max
+# flexibility.
 
 FROM runner AS netalertx-devcontainer
 ENV INSTALL_DIR=/app
 
-ENV PYTHONPATH=/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/app:/app/server:/opt/venv/lib/python3.12/site-packages
+ENV PYTHONPATH=${PYTHONPATH}:/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/usr/lib/python3.12/site-packages
 ENV PATH=/services:${PATH}
 ENV PHP_INI_SCAN_DIR=/services/config/php/conf.d:/etc/php83/conf.d
 ENV LISTEN_ADDR=0.0.0.0
@@ -218,19 +231,32 @@ ENV PORT=20211
 ENV NETALERTX_DEBUG=1
 ENV PYDEVD_DISABLE_FILE_VALIDATION=1
 COPY .devcontainer/resources/devcontainer-overlay/ /
-
+USER root
 # Install common tools, create user, and set up sudo
-RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest pytest-cov fish shfmt sudo
+RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \
+    pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
+    docker-cli-compose
 
 RUN install -d -o netalertx -g netalertx -m 755 /services/php/modules && \
     cp -a /usr/lib/php83/modules/. /services/php/modules/ && \
     echo "${NETALERTX_USER} ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
-# Install debugpy in the virtualenv if present, otherwise into system python3
+ENV SHELL=/bin/zsh
-RUN /bin/sh -c '(/opt/venv/bin/python3 -m pip install --no-cache-dir debugpy) || (python3 -m pip install --no-cache-dir debugpy) || true' && \
-    mkdir /workspaces && \
-    install -d -o netalertx -g netalertx -m 777 /services/run/logs && \
-    install -d -o netalertx -g netalertx -m 777 /app/run/tmp/client_body && \
-    sed -i -e 's|:/app:|:/workspaces:|' /etc/passwd && \
-    python -m pip install -U pytest pytest-cov
 
+RUN mkdir -p /workspaces && \
+    install -d -m 777 /data /data/config /data/db && \
+    install -d -m 777 /tmp/log /tmp/log/plugins /tmp/api /tmp/run /tmp/nginx && \
+    install -d -m 777 /tmp/nginx/active-config /tmp/nginx/client_body /tmp/nginx/config && \
+    install -d -m 777 /tmp/nginx/fastcgi /tmp/nginx/proxy /tmp/nginx/scgi /tmp/nginx/uwsgi && \
+    install -d -m 777 /tmp/run/tmp /tmp/run/logs && \
+    chmod 777 /workspaces && \
+    chown -R netalertx:netalertx /data && \
+    chmod 666 /data/config/app.conf /data/db/app.db && \
+    chmod 1777 /tmp && \
+    install -d -o root -g root -m 1777 /tmp/.X11-unix && \
+    mkdir -p /home/netalertx && \
+    chown netalertx:netalertx /home/netalertx && \
+    sed -i -e 's#/app:#/workspaces:#' /etc/passwd && \
+    find /opt/venv -type d -exec chmod o+rwx {} \;
+    
+USER netalertx
 ENTRYPOINT ["/bin/sh","-c","sleep infinity"]

.devcontainer/NetAlertX.code-workspace

@@ -0,0 +1,37 @@
+{
+	"folders": [
+		{
+			"name": "NetAlertX Source",
+			"path": "/workspaces/NetAlertX"
+		},
+		{
+			"name": "💾 NetAlertX Data",
+			"path": "/data"
+		},
+		{
+			"name": "🔍 Active NetAlertX log",
+			"path": "/tmp/log"
+		},
+		{
+			"name": "🌐 Active NetAlertX nginx",
+			"path": "/tmp/nginx"
+		},
+		{
+			"name": "📊 Active NetAlertX api",
+			"path": "/tmp/api"
+		},
+		{
+			"name": "⚙️ Active NetAlertX run",
+			"path": "/tmp/run"
+		}
+	],
+	"settings": {
+		"terminal.integrated.suggest.enabled": true,
+		"terminal.integrated.defaultProfile.linux": "zsh",
+		"terminal.integrated.profiles.linux": {
+			"zsh": {
+				"path": "/usr/bin/fish"
+			}
+		}
+	}
+}

.devcontainer/README.md

@@ -19,6 +19,17 @@ Common workflows (F1->Tasks: Run Task)
   - 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.

.devcontainer/WORKSPACE.md

@@ -0,0 +1,26 @@
+# NetAlertX Multi-Folder Workspace
+
+This repository uses a multi-folder workspace configuration to provide easy access to runtime directories.
+
+## Opening the Multi-Folder Workspace
+
+After the devcontainer builds, open the workspace file to access all folders:
+
+1. **File** → **Open Workspace from File**
+2. Select `NetAlertX.code-workspace`
+
+Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
+- Type: `Workspaces: Open Workspace from File`
+- Select `NetAlertX.code-workspace`
+
+## Workspace Folders
+
+The workspace includes:
+- **NetAlertX** - Main source code
+- **/tmp** - Runtime temporary files
+- **/tmp/api** - API response cache (JSON files)
+- **/tmp/log** - Application and plugin logs
+
+## Testing Configuration
+
+Pytest is configured to only discover tests in the main `test/` directory, not in `/tmp` folders.

.devcontainer/devcontainer.json

@@ -2,6 +2,8 @@
   "name": "NetAlertX DevContainer",
   "remoteUser": "netalertx",
   "workspaceFolder": "/workspaces/NetAlertX",
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/NetAlertX,type=bind,consistency=cached",
+  "onCreateCommand": "mkdir -p /tmp/api /tmp/log",
   "build": {
     "dockerfile": "./Dockerfile", // Dockerfile generated by script
     "context": "../", // Context is the root of the repository
@@ -23,6 +25,9 @@
     // even within this container and connect to them as needed.
     // "--network=host",
   ],
+  "mounts": [ 
+    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind" //used for testing various conditions in docker
+  ],
   // ATTENTION: If running with --network=host, COMMENT `forwardPorts` OR ELSE THERE WILL BE NO WEBUI!
   "forwardPorts": [20211, 20212, 5678],
   "portsAttributes": { // the ports we care about
@@ -40,8 +45,14 @@
     }
   },
 
-  "postStartCommand": "${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh",
+  "postCreateCommand": {
-
+      "Install Pip Requirements": "/opt/venv/bin/pip3 install pytest docker debugpy",
+      "Workspace Instructions": "printf '\n\n<> DevContainer Ready!\n\n📁 To access /tmp folders in the workspace:\n   File → Open Workspace from File → NetAlertX.code-workspace\n\n📖 See .devcontainer/WORKSPACE.md for details\n\n'"
+  },
+  "postStartCommand": {
+      "Start Environment":"${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh",
+      "Build test-container":"echo building netalertx-test container in background. check /tmp/build.log for progress. && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 &"
+  },
   "customizations": {
     "vscode": {
       "extensions": [
@@ -62,15 +73,25 @@
         "esbenp.prettier-vscode",
         "eamodio.gitlens",
         "alexcvzz.vscode-sqlite",
-        "yzhang.markdown-all-in-one",
+        "mkhl.shfmt",
-        "mkhl.shfmt"
+        "charliermarsh.ruff",
+        "ms-python.flake8"
       ],
       "settings": {
         "terminal.integrated.cwd": "${containerWorkspaceFolder}",
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "/bin/zsh",
+            "args": ["-l"]
+          }
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        
         // Python testing configuration
         "python.testing.pytestEnabled": true,
         "python.testing.unittestEnabled": false,
         "python.testing.pytestArgs": ["test"],
+        "python.testing.cwd": "${containerWorkspaceFolder}",
         // Make sure we discover tests and import server correctly
         "python.analysis.extraPaths": [
           "/workspaces/NetAlertX",

.devcontainer/resources/devcontainer-Dockerfile

@@ -3,11 +3,14 @@
 #   .devcontainer/scripts/generate-configs.sh
 # The generator appends this stage to produce .devcontainer/Dockerfile.
 # Prefer to place dev-only setup here; use setup.sh only for runtime fixes.
+# Permissions in devcontainer should be of a brutalist nature. They will be
+# Open and wide to avoid permission issues during development allowing max
+# flexibility.
 
 FROM runner AS netalertx-devcontainer
 ENV INSTALL_DIR=/app
 
-ENV PYTHONPATH=/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/app:/app/server:/opt/venv/lib/python3.12/site-packages
+ENV PYTHONPATH=${PYTHONPATH}:/workspaces/NetAlertX/test:/workspaces/NetAlertX/server:/usr/lib/python3.12/site-packages
 ENV PATH=/services:${PATH}
 ENV PHP_INI_SCAN_DIR=/services/config/php/conf.d:/etc/php83/conf.d
 ENV LISTEN_ADDR=0.0.0.0
@@ -15,19 +18,32 @@ ENV PORT=20211
 ENV NETALERTX_DEBUG=1
 ENV PYDEVD_DISABLE_FILE_VALIDATION=1
 COPY .devcontainer/resources/devcontainer-overlay/ /
-
+USER root
 # Install common tools, create user, and set up sudo
-RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest pytest-cov fish shfmt github-cli
+RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \
+    pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
+    docker-cli-compose
 
 RUN install -d -o netalertx -g netalertx -m 755 /services/php/modules && \
     cp -a /usr/lib/php83/modules/. /services/php/modules/ && \
     echo "${NETALERTX_USER} ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
-# Install debugpy in the virtualenv if present, otherwise into system python3
+ENV SHELL=/bin/zsh
-RUN /bin/sh -c '(/opt/venv/bin/python3 -m pip install --no-cache-dir debugpy) || (python3 -m pip install --no-cache-dir debugpy) || true' && \
-    mkdir /workspaces && \
-    install -d -o netalertx -g netalertx -m 777 /services/run/logs && \
-    install -d -o netalertx -g netalertx -m 777 /app/run/tmp/client_body && \
-    sed -i -e 's|:/app:|:/workspaces:|' /etc/passwd && \
-    python -m pip install -U pytest pytest-cov
 
+RUN mkdir -p /workspaces && \
+    install -d -m 777 /data /data/config /data/db && \
+    install -d -m 777 /tmp/log /tmp/log/plugins /tmp/api /tmp/run /tmp/nginx && \
+    install -d -m 777 /tmp/nginx/active-config /tmp/nginx/client_body /tmp/nginx/config && \
+    install -d -m 777 /tmp/nginx/fastcgi /tmp/nginx/proxy /tmp/nginx/scgi /tmp/nginx/uwsgi && \
+    install -d -m 777 /tmp/run/tmp /tmp/run/logs && \
+    chmod 777 /workspaces && \
+    chown -R netalertx:netalertx /data && \
+    chmod 666 /data/config/app.conf /data/db/app.db && \
+    chmod 1777 /tmp && \
+    install -d -o root -g root -m 1777 /tmp/.X11-unix && \
+    mkdir -p /home/netalertx && \
+    chown netalertx:netalertx /home/netalertx && \
+    sed -i -e 's#/app:#/workspaces:#' /etc/passwd && \
+    find /opt/venv -type d -exec chmod o+rwx {} \;
+    
+USER netalertx
 ENTRYPOINT ["/bin/sh","-c","sleep infinity"]

.devcontainer/resources/devcontainer-overlay/services/config/nginx/netalertx.conf.template

@@ -8,7 +8,9 @@ worker_processes auto;
 pcre_jit on;
 
 # Configures default error logger.
-error_log /app/log/nginx-error.log warn;
+error_log /tmp/log/nginx-error.log warn;
+
+pid /tmp/run/nginx.pid;
 
 events {
 	# The maximum number of simultaneous connections that can be opened by
@@ -17,13 +19,12 @@ events {
 }
 
 http {
-
 	# Mapping of temp paths for various nginx modules.
-    client_body_temp_path /services/run/tmp/client_body;
+    client_body_temp_path /tmp/nginx/client_body;
-    proxy_temp_path /services/run/tmp/proxy;
+    proxy_temp_path /tmp/nginx/proxy;
-	fastcgi_temp_path /services/run/tmp/fastcgi;
+	fastcgi_temp_path /tmp/nginx/fastcgi;
-	uwsgi_temp_path /services/run/tmp/uwsgi;
+	uwsgi_temp_path /tmp/nginx/uwsgi;
-	scgi_temp_path /services/run/tmp/scgi;
+	scgi_temp_path /tmp/nginx/scgi;
 	
 	# Includes mapping of file name extensions to MIME types of responses
 	# and defines the default type.
@@ -89,7 +90,7 @@ http {
 	    '"$http_user_agent" "$http_x_forwarded_for"';
 
 	# Sets the path, format, and configuration for a buffered log write.
-	access_log /app/log/nginx-access.log main;
+	access_log /tmp/log/nginx-access.log main;
 
 
 	# Virtual host config
@@ -100,11 +101,10 @@ http {
         index index.php;
         add_header X-Forwarded-Prefix "/app" always;
 
-
         location ~* \.php$ {
             # Set Cache-Control header to prevent caching on the first load
             add_header Cache-Control "no-store";
-            fastcgi_pass unix:/services/run/php.sock;
+			fastcgi_pass unix:/tmp/run/php.sock;
             include /services/config/nginx/fastcgi_params;
 			fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
 			fastcgi_param SCRIPT_NAME $fastcgi_script_name;

.devcontainer/resources/devcontainer-overlay/workspaces/.zshrc

@@ -0,0 +1,47 @@
+# NetAlertX devcontainer zsh configuration
+# Keep this lightweight and deterministic so shells behave consistently.
+
+export PATH="$HOME/.local/bin:$PATH"
+export EDITOR=vim
+export SHELL=/bin/zsh
+
+# Start inside the workspace if it exists
+if [ -d "/workspaces/NetAlertX" ]; then
+  cd /workspaces/NetAlertX
+fi
+
+# Enable basic completion and prompt helpers
+autoload -Uz compinit promptinit colors
+colors
+compinit -u
+promptinit
+
+# Friendly prompt with virtualenv awareness
+setopt PROMPT_SUBST
+
+_venv_segment() {
+  if [ -n "$VIRTUAL_ENV" ]; then
+    printf '(%s) ' "${VIRTUAL_ENV:t}"
+  fi
+}
+
+PROMPT='%F{green}$(_venv_segment)%f%F{cyan}%n@%m%f %F{yellow}%~%f %# '
+RPROMPT='%F{magenta}$(git rev-parse --abbrev-ref HEAD 2>/dev/null)%f'
+
+# Sensible defaults
+setopt autocd
+setopt correct
+setopt extendedglob
+HISTFILE="$HOME/.zsh_history"
+HISTSIZE=5000
+SAVEHIST=5000
+
+alias ll='ls -alF'
+alias la='ls -A'
+alias gs='git status -sb'
+alias gp='git pull --ff-only'
+
+# Ensure pyenv/virtualenv activate hooks adjust the prompt cleanly
+if [ -f "$HOME/.zshrc.local" ]; then
+  source "$HOME/.zshrc.local"
+fi

.devcontainer/scripts/confirm-docker-prune.sh

@@ -1,7 +1,11 @@
 #!/bin/bash
 set -euo pipefail
 
-read -r -p "Are you sure you want to destroy your host docker containers and images? Type YES to continue: " reply
+if [[ -n "${CONFIRM_PRUNE:-}" && "${CONFIRM_PRUNE}" == "YES" ]]; then
+  reply="YES"
+else
+  read -r -p "Are you sure you want to destroy your host docker containers and images? Type YES to continue: " reply
+fi
 
 if [[ "${reply}" == "YES" ]]; then
   docker system prune -af

.devcontainer/scripts/setup.sh

@@ -1,137 +1,110 @@
 #!/bin/bash
-# Runtime setup for devcontainer (executed after container starts).
+# NetAlertX Devcontainer Setup Script
-# Prefer building setup into resources/devcontainer-Dockerfile when possible.
+#
-# Use this script for runtime-only adjustments (permissions, sockets, ownership,
+# This script forcefully resets all runtime state for a single-user devcontainer.
-# and services managed without init) that are difficult at build time.
+# It is intentionally idempotent: every run wipes and recreates all relevant folders,
-id
+# symlinks, and files, so the environment is always fresh and predictable.
-
+#
-# Define variables (paths, ports, environment)
+# - No conditional logic: everything is (re)created, overwritten, or reset unconditionally.
-
+# - No security hardening: this is for disposable, local dev use only.
-export APP_DIR="/app"
+# - No checks for existing files, mounts, or processes—just do the work.
-export APP_COMMAND="/workspaces/NetAlertX/.devcontainer/scripts/restart-backend.sh"
+#
-export PHP_FPM_BIN="/usr/sbin/php-fpm83"
+# If you add new runtime files or folders, add them to the creation/reset section below.
-export CROND_BIN="/usr/sbin/crond -f"
+#
+# Do not add if-then logic or error handling for missing/existing files. Simplicity is the goal.
 
 
-export ALWAYS_FRESH_INSTALL=false
+SOURCE_DIR=${SOURCE_DIR:-/workspaces/NetAlertX}
-export INSTALL_DIR=/app
+PY_SITE_PACKAGES="${VIRTUAL_ENV:-/opt/venv}/lib/python3.12/site-packages"
-export LOGS_LOCATION=/app/logs
+SOURCE_SERVICES_DIR="${SOURCE_DIR}/install/production-filesystem/services"
-export CONF_FILE="app.conf"
-export DB_FILE="app.db"
-export FULL_FILEDB_PATH="${INSTALL_DIR}/db/${DB_FILE}"
-export OUI_FILE="/usr/share/arp-scan/ieee-oui.txt" # Define the path to ieee-oui.txt and ieee-iab.txt
-export TZ=Europe/Paris
-export PORT=20211
-export SOURCE_DIR="/workspaces/NetAlertX"
 
+LOG_FILES=(
+  LOG_APP
+  LOG_APP_FRONT
+  LOG_STDOUT
+  LOG_STDERR
+  LOG_EXECUTION_QUEUE
+  LOG_APP_PHP_ERRORS
+  LOG_IP_CHANGES
+  LOG_CROND
+  LOG_REPORT_OUTPUT_TXT
+  LOG_REPORT_OUTPUT_HTML
+  LOG_REPORT_OUTPUT_JSON
+  LOG_DB_IS_LOCKED
+  LOG_NGINX_ERROR
+)
 
-main() {
+sudo chmod 666 /var/run/docker.sock 2>/dev/null || true
-    echo "=== NetAlertX Development Container Setup ==="
+sudo chown "$(id -u)":"$(id -g)" /workspaces
-    killall php-fpm83 nginx crond python3 2>/dev/null
+sudo chmod 755 /workspaces
-    sleep 1
-    echo "Setting up ${SOURCE_DIR}..."
-    sudo chown $(id -u):$(id -g) /workspaces
-    sudo chmod 755 /workspaces
-    configure_source
 
-    echo "--- Starting Development Services ---"
+killall php-fpm83 nginx crond python3 2>/dev/null || true
-    configure_php
 
+# Mount ramdisks for volatile data
+sudo mount -t tmpfs -o size=100m,mode=0777 tmpfs /tmp/log 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/api 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/run 2>/dev/null || true
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/nginx 2>/dev/null || true
 
-    start_services
+sudo chmod 777 /tmp/log /tmp/api /tmp/run /tmp/nginx
-}
-
-isRamDisk() {
-  if [ -z "$1" ] || [ ! -d "$1" ]; then
-    echo "Usage: isRamDisk <directory>" >&2
-    return 2
-  fi
-
-  local fstype
-  fstype=$(df -T "$1" | awk 'NR==2 {print $2}')
-
-  if [ "$fstype" = "tmpfs" ] || [ "$fstype" = "ramfs" ]; then
-    return 0 # Success (is a ramdisk)
-  else
-    return 1 # Failure (is not a ramdisk)
-  fi
-}
-
-# Setup source directory
-configure_source() {
-    echo "[1/4] Configuring System..."
-    echo "      -> Setting up /services permissions"
-    sudo chown -R netalertx /services
-
-    echo "[2/4] Configuring Source..."
-    echo "      -> Cleaning up previous instances"
-
-    test -e ${NETALERTX_LOG} && sudo umount "${NETALERTX_LOG}" 2>/dev/null || true
-    test -e ${NETALERTX_API} && sudo umount "${NETALERTX_API}" 2>/dev/null || true
-    test -e ${NETALERTX_APP} && sudo rm -Rf ${NETALERTX_APP}/
-
-    echo "      -> Linking source to ${NETALERTX_APP}"
-    sudo ln -s ${SOURCE_DIR}/ ${NETALERTX_APP}
-
-    echo "      -> Mounting ramdisks for /log and /api"
-    mkdir -p ${NETALERTX_LOG} ${NETALERTX_API}
-    sudo mount -o uid=$(id -u netalertx),gid=$(id -g netalertx),mode=775 -t tmpfs -o size=256M tmpfs "${NETALERTX_LOG}"
-    sudo mount -o uid=$(id -u netalertx),gid=$(id -g netalertx),mode=775 -t tmpfs -o size=256M tmpfs "${NETALERTX_API}"
-    mkdir -p ${NETALERTX_PLUGINS_LOG}
-    touch ${NETALERTX_PLUGINS_LOG}/.dockerignore ${NETALERTX_API}/.dockerignore
-    # tmpfs mounts configured with netalertx ownership and 775 permissions above
-
-    touch /app/log/nginx_error.log
-    echo "      -> Empty log"|tee ${INSTALL_DIR}/log/app.log \
-        ${INSTALL_DIR}/log/app_front.log \
-        ${INSTALL_DIR}/log/stdout.log
-    touch ${INSTALL_DIR}/log/stderr.log \
-        ${INSTALL_DIR}/log/execution_queue.log
-    echo 0 > ${INSTALL_DIR}/log/db_is_locked.log
-    for f in ${INSTALL_DIR}/log/*.log; do
-        sudo chown netalertx:www-data $f
-        sudo chmod 664 $f
-        echo "" > $f
-    done
-
-    mkdir -p /app/log/plugins
-    sudo chown -R netalertx:www-data ${INSTALL_DIR}
-
-    
-    while ps ax | grep -v grep | grep python3 > /dev/null; do
-        killall python3 &>/dev/null
-        sleep 0.2
-    done
-    
-}
-
-# configure_php: configure PHP-FPM and enable dev debug options
-configure_php() {
-    echo "[3/4] Configuring PHP-FPM..."
-    sudo chown -R netalertx:netalertx  ${SYSTEM_SERVICES_RUN} 2>/dev/null || true
-
-}
-
-# start_services: start crond, PHP-FPM, nginx and the application
-start_services() {
-    echo "[4/4] Starting services"
-
-    sudo chmod +x /entrypoint.sh
-    setsid bash /entrypoint.sh&
-    sleep 1
-}
-
-
-sudo chmod 755 /app/
-echo "Development $(git rev-parse --short=8 HEAD)"| sudo tee /app/.VERSION
-# Run the main function
-main
-
-# create a services readme file
-echo "This folder is auto-generated by the container and devcontainer setup.sh script." > /services/README.md
-echo "Any changes here will be lost on rebuild. To make permanent changes, edit files in .devcontainer or production filesystem and rebuild the container." >> /services/README.md
-echo "Only make temporary/test changes in this folder, then perform a rebuild to reset." >> /services/README.md
 
 
 
+sudo rm -rf "${SYSTEM_NGINX_CONFIG}/conf.active"
+sudo ln -s "${SYSTEM_SERVICES_ACTIVE_CONFIG}" "${SYSTEM_NGINX_CONFIG}/conf.active"
+
+sudo rm -rf /entrypoint.d
+sudo ln -s "${SOURCE_DIR}/install/production-filesystem/entrypoint.d" /entrypoint.d
+
+sudo rm -rf "${NETALERTX_APP}"
+sudo ln -s "${SOURCE_DIR}/" "${NETALERTX_APP}"
+
+for dir in "${NETALERTX_DATA}" "${NETALERTX_CONFIG}" "${NETALERTX_DB}"; do
+  sudo install -d -m 777 "${dir}"
+done
+
+for dir in \
+  "${SYSTEM_SERVICES_RUN_LOG}" \
+  "${SYSTEM_SERVICES_ACTIVE_CONFIG}" \
+  "${NETALERTX_PLUGINS_LOG}" \
+  "/tmp/nginx/client_body" \
+  "/tmp/nginx/proxy" \
+  "/tmp/nginx/fastcgi" \
+  "/tmp/nginx/uwsgi" \
+  "/tmp/nginx/scgi"; do
+  sudo install -d -m 777 "${dir}"
+done
+
+# Create nginx temp subdirs with permissions
+sudo mkdir -p "${SYSTEM_SERVICES_RUN_TMP}/client_body" "${SYSTEM_SERVICES_RUN_TMP}/proxy" "${SYSTEM_SERVICES_RUN_TMP}/fastcgi" "${SYSTEM_SERVICES_RUN_TMP}/uwsgi" "${SYSTEM_SERVICES_RUN_TMP}/scgi"
+sudo chmod -R 777 "${SYSTEM_SERVICES_RUN_TMP}"
+
+for var in "${LOG_FILES[@]}"; do
+  path=${!var}
+  dir=$(dirname "${path}")
+  sudo install -d -m 777 "${dir}"
+  touch "${path}"
+done
+
+printf '0\n' | sudo tee "${LOG_DB_IS_LOCKED}" >/dev/null
+sudo chmod 777 "${LOG_DB_IS_LOCKED}"
+
+sudo pkill -f python3 2>/dev/null || true
+
+sudo chmod 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" "${NETALERTX_DATA}"/* 2>/dev/null || true
+
+sudo chmod 005 "${PY_SITE_PACKAGES}" 2>/dev/null || true
+
+sudo chown -R "${NETALERTX_USER}:${NETALERTX_GROUP}" "${NETALERTX_APP}"
+date +%s | sudo tee "${NETALERTX_FRONT}/buildtimestamp.txt" >/dev/null
+
+sudo chmod 755 "${NETALERTX_APP}"
+
+sudo chmod +x /entrypoint.sh
+setsid bash /entrypoint.sh &
+sleep 1
+
+echo "Development $(git rev-parse --short=8 HEAD)" | sudo tee "${NETALERTX_APP}/.VERSION" >/dev/null
+
+
 

.dockerignore

@@ -1,4 +1,5 @@
 .dockerignore
+**/.dockerignore
 .env
 .git
 .github

.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 180
+ignore = E221,E222,E251,E203

.github/ISSUE_TEMPLATE/i-have-an-issue.yml

@@ -46,7 +46,7 @@ body:
   attributes:
     label: app.conf
     description: |
-      Paste your `app.conf` (remove personal info)    
+      Paste relevant `app.conf`settings (remove sensitive info)    
     render: python
   validations:
     required: false
@@ -70,6 +70,13 @@ body:
       - Bare-metal (community only support - Check Discord)
   validations:
     required: true
+- type: checkboxes
+  attributes:
+    label: Debug or Trace enabled
+    description: I confirm I set `LOG_LEVEL` to `debug` or `trace`
+    options:
+    - label: I have read and followed the steps in the wiki link above and provided the required debug logs and the log section covers the time when the issue occurs.
+      required: true
 - type: textarea
   attributes:
     label: app.log
@@ -78,13 +85,14 @@ body:
       ***Generally speaking, all bug reports should have logs provided.***
       Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
       Additionally, any additional info? Screenshots? References? Anything that will give us more context about the issue you are encountering!
-      You can use `tail -100 /app/log/app.log` in the container if you have trouble getting to the log files. 
+      You can use `tail -100 /app/log/app.log` in the container if you have trouble getting to the log files or send them to netalertx@gmail.com with the issue number.
   validations:
     required: false
-- type: checkboxes
+- type: textarea
   attributes:
-    label: Debug enabled
+    label: Docker Logs
-    description: I confirm I enabled `debug`
+    description: |
-    options:
+     You can retrieve the logs from Portainer -> Containers -> your NetAlertX container -> Logs or by running `sudo docker logs netalertx`.
-    - label: I have read and followed the steps in the wiki link above and provided the required debug logs and the log section covers the time when the issue occurs.
+  validations:
-      required: true
+    required: true
+

.github/copilot-instructions.md

@@ -18,7 +18,7 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 ## Plugin patterns that matter
 - Manifest lives at `front/plugins/<code_name>/config.json`; `code_name` == folder, `unique_prefix` drives settings and filenames (e.g., `ARPSCAN`).
 - Control via settings: `<PREF>_RUN` (phase), `<PREF>_RUN_SCHD` (cron-like), `<PREF>_CMD` (script path), `<PREF>_RUN_TIMEOUT`, `<PREF>_WATCH` (diff columns).
-- Data contract: scripts write `/app/log/plugins/last_result.<PREF>.log` (pipe‑delimited: 9 required cols + optional 4). Use `front/plugins/plugin_helper.py`’s `Plugin_Objects` to sanitize text and normalize MACs, then `write_result_file()`.
+- Data contract: scripts write `/tmp/log/plugins/last_result.<PREF>.log` (pipe‑delimited: 9 required cols + optional 4). Use `front/plugins/plugin_helper.py`’s `Plugin_Objects` to sanitize text and normalize MACs, then `write_result_file()`.
 - Device import: define `database_column_definitions` when creating/updating devices; watched fields trigger notifications.
 
 ### Standard Plugin Formats
@@ -30,6 +30,7 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 * other: Miscellaneous plugins. Runs at various times. Data source: self / Template.
 
 ### Plugin logging & outputs
+- Always check relevant logs first.
 - Use logging as shown in other plugins.
 - Collect results with `Plugin_Objects.add_object(...)` during processing and call `plugin_objects.write_result_file()` exactly once at the end of the script.
 - Prefer to log a brief summary before writing (e.g., total objects added) to aid troubleshooting; keep logs concise at `info` level and use `verbose` or `debug` for extra context.
@@ -42,22 +43,32 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 ## Conventions & helpers to reuse
 - Settings: add/modify via `ccd()` in `server/initialise.py` or per‑plugin manifest. Never hardcode ports or secrets; use `get_setting_value()`.
 - Logging: use `logger.mylog(level, [message])`; levels: none/minimal/verbose/debug/trace.
-- Time/MAC/strings: `helper.py` (`timeNowTZ`, `normalize_mac`, sanitizers). Validate MACs before DB writes.
+- Time/MAC/strings: `helper.py` (`timeNowDB`, `normalize_mac`, sanitizers). Validate MACs before DB writes.
 - DB helpers: prefer `server/db/db_helper.py` functions (e.g., `get_table_json`, device condition helpers) over raw SQL in new paths.
 
 ## Dev workflow (devcontainer)
+- **Devcontainer philosophy: brutal simplicity.** One user, everything writable, completely idempotent. No permission checks, no conditional logic, no sudo needed. If something doesn't work, tear down the wall and rebuild - don't patch. We unit test permissions in the hardened build.
+- **Permissions:** Never `chmod` or `chown` during operations. Everything is already writable. If you need permissions, the devcontainer setup is broken - fix `.devcontainer/scripts/setup.sh` or `.devcontainer/resources/devcontainer-Dockerfile` instead.
+- **Files & Paths:** Use environment variables (`NETALERTX_DB`, `NETALERTX_LOG`, etc.) everywhere. `/data` for persistent config/db, `/tmp` for runtime logs/api/nginx state. Never hardcode `/data/db` or relative paths.
+- **Database reset:** Use the `[Dev Container] Wipe and Regenerate Database` task. Kills backend, deletes `/data/{db,config}/*`, runs first-time setup scripts. Clean slate, no questions.
 - Services: use tasks to (re)start backend and nginx/PHP-FPM. Backend runs with debugpy on 5678; attach a Python debugger if needed.
 - Run a plugin manually: `python3 front/plugins/<code_name>/script.py` (ensure `sys.path` includes `/app/front/plugins` and `/app/server` like the template).
 - Testing: pytest available via Alpine packages. Tests live in `test/`; app code is under `server/`. PYTHONPATH is preconfigured to include workspace and `/opt/venv` site‑packages.
+- **Subprocess calls:** ALWAYS set explicit timeouts. Default to 60s minimum unless plugin config specifies otherwise. Nested subprocess calls (e.g., plugins calling external tools) need their own timeout - outer plugin timeout won't save you.
 
 ## What “done right” looks like
-- When adding a plugin, start from `front/plugins/__template`, implement with `plugin_helper`, define manifest settings, and wire phase via `<PREF>_RUN`. Verify logs in `/app/log/plugins/` and data in `api/*.json`.
+- When adding a plugin, start from `front/plugins/__template`, implement with `plugin_helper`, define manifest settings, and wire phase via `<PREF>_RUN`. Verify logs in `/tmp/log/plugins/` and data in `api/*.json`.
 - When introducing new config, define it once (core `ccd()` or plugin manifest) and read it via helpers everywhere.
 - When exposing new server functionality, add endpoints in `server/api_server/*` and keep authorization consistent; update UI by reading/writing JSON cache rather than bypassing the pipeline.
 
 ## Useful references
 - Docs: `docs/PLUGINS_DEV.md`, `docs/SETTINGS_SYSTEM.md`, `docs/API_*.md`, `docs/DEBUG_*.md`
-- Logs: backend `/app/log/app.log`, plugin logs under `/app/log/plugins/`, nginx/php logs under `/var/log/*`
+- Logs: All logs are under `/tmp/log/`. Plugin logs are very shortly under `/tmp/log/plugins/` until picked up by the server.
+    - plugin logs: `/tmp/log/app.log`
+	- backend logs: `/tmp/log/stdout.log` and `/tmp/log/stderr.log`
+	- frontend commands logs: `/tmp/log/app_front.log`
+	- php errors: `/tmp/log/app.php_errors.log`
+	- nginx logs: `/tmp/log/nginx-access.log` and `/tmp/log/nginx-error.log`
 
 ## Assistant expectations:
 - Be concise, opinionated, and biased toward security and simplicity.

.github/workflows/docker_dev.yml

@@ -3,12 +3,12 @@ name: docker
 on:
   push:
     branches:
-      - main
+      - next_release
     tags:
       - '*.*.*'
   pull_request:
     branches:
-      - main
+      - next_release
 
 jobs:
   docker_dev:
@@ -20,6 +20,7 @@ jobs:
     if: >
       contains(github.event.head_commit.message, 'PUSHPROD') != 'True' &&
       github.repository == 'jokob-sk/NetAlertX'
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -30,6 +31,14 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # --- Generate timestamped dev version
+      - name: Generate timestamp version
+        id: timestamp
+        run: |
+          ts=$(date -u +'%Y%m%d-%H%M%S')
+          echo "version=dev-${ts}" >> $GITHUB_OUTPUT
+          echo "Generated version: dev-${ts}"
+
       - name: Set up dynamic build ARGs
         id: getargs
         run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
@@ -38,18 +47,20 @@ jobs:
         id: get_version
         run: echo "version=Dev" >> $GITHUB_OUTPUT
 
+      # --- Write the timestamped version to .VERSION file
       - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
+        run: echo "${{ steps.timestamp.outputs.version }}" > .VERSION
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: |
             ghcr.io/jokob-sk/netalertx-dev
             jokobsk/netalertx-dev
           tags: |
             type=raw,value=latest
+            type=raw,value=${{ steps.timestamp.outputs.version }}
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}

.github/workflows/docker_prod.yml

@@ -6,7 +6,6 @@
 # GitHub recommends pinning actions to a commit SHA.
 # To get a newer version, you will need to update the SHA.
 # You can also reference a tag or branch, but the action may change without warning.
-
 name: Publish Docker image
 
 on:
@@ -14,6 +13,7 @@ on:
     types: [published]
     tags:
       - '*.[1-9]+[0-9]?.[1-9]+*'
+
 jobs:
   docker:
     runs-on: ubuntu-latest
@@ -21,6 +21,7 @@ jobs:
     permissions:
       contents: read
       packages: write
+
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -31,42 +32,39 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Set up dynamic build ARGs
+      # --- Get release version from tag
-        id: getargs        
-        run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
-
       - name: Get release version
         id: get_version
-        run: echo "::set-output name=version::${GITHUB_REF#refs/tags/}"
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
+      # --- Write version to .VERSION file
       - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
+        run: echo "${{ steps.get_version.outputs.version }}" > .VERSION
 
+      # --- Generate Docker metadata and tags
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
-          # list of Docker images to use as base name for tags
           images: |
             ghcr.io/jokob-sk/netalertx
             jokobsk/netalertx
-          # generate Docker tags based on the following events/attributes
           tags: |
-            type=semver,pattern={{version}},value=${{ inputs.version }}
+            type=semver,pattern={{version}},value=${{ steps.get_version.outputs.version }}
-            type=semver,pattern={{major}}.{{minor}},value=${{ inputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ steps.get_version.outputs.version }}
-            type=semver,pattern={{major}},value=${{ inputs.version }}
+            type=semver,pattern={{major}},value=${{ steps.get_version.outputs.version }}
             type=ref,event=branch,suffix=-{{ sha }}
             type=ref,event=pr
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') }}
 
-      - name: Log in to Github Container registry
+      - name: Log in to Github Container Registry (GHCR)
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: jokob-sk
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Login to DockerHub
+      - name: Log in to DockerHub
         if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
@@ -81,6 +79,5 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          # # ⚠ disable cache if build is failing to download debian packages
           # cache-from: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache
           # cache-to: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache,mode=max

.github/workflows/docker_rewrite.yml

@@ -43,7 +43,7 @@ jobs:
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: |
             ghcr.io/jokob-sk/netalertx-dev-rewrite

.gitignore

@@ -1,16 +1,16 @@
+.coverage
 .vscode
 .dotnet
 .vscode-server
 .gitconfig
 .*CommandMarker
 deviceid
-.VERSION
+.DS_Store
-
-# Sensitive data
 .cache
 nohup.out
 config/*
 .ash_history
+.VERSION
 config/pialert.conf
 config/app.conf
 db/*
@@ -23,35 +23,23 @@ front/api/*
 /api/*
 **/plugins/**/*.log
 **/plugins/cloud_services/*
+**/%40eaDir/
+**/@eaDir/
+
+__pycache__/
+*.py[cod]
+*$py.class
+
 **/last_result.log
 **/script.log
 **/pialert.conf_bak
 **/pialert.db_bak
+.*.swp
 
-# future stuff
 front/img/cloud_services/*
 **/cloud_services.php
 **/cloud_services.js
 front/css/cloud_services.css
 
-# OS junk
+docker-compose.yml.ffsb42
-Thumbs.db
+.env.omada.ffsb42
-ehthumbs.db
-Desktop.ini
-**/%40eaDir/
-**/@eaDir/
-*/%40eaDir/
-*/@eaDir/
-.DS_Store
-.*.swp
-
-# Python junk
-venv/
-.env/
-__pycache__/
-*.py[cod]
-*$py.class
-
-# Build artifacts (if you ever package anything)
-dist/
-build/

.venv_import_check.py

@@ -1,23 +0,0 @@
-import sys, importlib
-mods = [
-    'json', 'simplejson',
-    'httplib', 'http.client',
-    'urllib2', 'urllib.request',
-    'Queue', 'queue',
-    'cStringIO', 'StringIO', 'io',
-    'md5', 'hashlib',
-    'ssl'
-]
-print('PYTHON_EXE:' + sys.executable)
-print('PYTHON_VER:' + sys.version.replace('\n', ' '))
-for m in mods:
-    try:
-        mod = importlib.import_module(m)
-        ver = getattr(mod, '__version__', None)
-        if ver is None:
-            # try common attributes
-            ver = getattr(mod, 'version', None)
-        info = (' version=' + str(ver)) if ver is not None else ''
-        print('OK %s%s' % (m, info))
-    except Exception as e:
-        print('MISSING %s %s: %s' % (m, e.__class__.__name__, e))

.vscode/launch.json

@@ -29,6 +29,14 @@
             "pathMappings": {
                 "/app": "${workspaceFolder}"
             }
+        },
+        {
+            "name": "Python: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true
         }
     ]
 }

.vscode/settings.json

@@ -11,13 +11,23 @@
     // Let the Python extension invoke pytest via the interpreter; avoid hardcoded paths
     // Removed python.testing.pytestPath and legacy pytest.command overrides
     
-    "terminal.integrated.defaultProfile.linux": "fish",
+    "terminal.integrated.defaultProfile.linux": "zsh",
     "terminal.integrated.profiles.linux": {
-      "fish": {
+      "zsh": {
-        "path": "/usr/bin/fish"
+        "path": "/bin/zsh"
       }
     }
     ,
     // Fallback for older VS Code versions or schema validators that don't accept custom profiles
-    "terminal.integrated.shell.linux": "/usr/bin/fish"
+    "terminal.integrated.shell.linux": "/usr/bin/zsh"
+  ,
+  "python.linting.flake8Enabled": true,
+  "python.linting.enabled": true,
+  "python.linting.flake8Args": [
+    "--config=.flake8"
+  ],
+  "python.formatting.provider": "black",
+  "python.formatting.blackArgs": [
+    "--line-length=180"
+  ]
 }

.vscode/tasks.json

@@ -1,16 +1,27 @@
 {
   "version": "2.0.0",
+  "inputs": [
+    {
+      "id": "confirmPrune",
+      "type": "promptString",
+      "description": "DANGER! Type YES to confirm pruning all unused Docker resources. This will destroy containers, images, volumes, and networks!",
+      "default": ""
+    }
+  ],
   "tasks": [
     {
       "label": "[Any POSIX] Generate Devcontainer Configs",
       "type": "shell",
       "command": ".devcontainer/scripts/generate-configs.sh",
+      "detail": "Generates devcontainer configs from the template. This must be run after changes to devcontainer to combine/merge them into the final config used by VS Code. Note- this has no bearing on the production or test image.",
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
-        "showReuseMessage": false
+        "showReuseMessage": false,
+        "group": "POSIX Tasks"
       },
+      
       "problemMatcher": [],
       "group": {
         "kind": "build",
@@ -24,12 +35,19 @@
     {
       "label": "[Any] Docker system and build Prune",
       "type": "shell",
-  "command": ".devcontainer/scripts/confirm-docker-prune.sh",
+      "command": ".devcontainer/scripts/confirm-docker-prune.sh",
+      "detail": "DANGER! Prunes all unused Docker resources (images, containers, volumes, networks). Any stopped container will be wiped and data will be lost.  Use with caution.",
+      "options": {
+        "env": {
+          "CONFIRM_PRUNE": "${input:confirmPrune}"
+        }
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
-        "showReuseMessage": false
+        "showReuseMessage": false,
+        "group": "Any"
       },
       "problemMatcher": [],
       "group": {
@@ -45,6 +63,7 @@
       "label": "[Dev Container] Re-Run Startup Script",
       "type": "shell",
       "command": "./isDevContainer.sh || exit 1;/workspaces/NetAlertX/.devcontainer/scripts/setup.sh",
+      "detail": "The startup script runs directly after the container is started. It reprovisions permissions, links folders, and performs other setup tasks. Run this if you have made changes to the setup script or need to reprovision the container.",
       "options": {
         "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
       },
@@ -65,6 +84,7 @@
       "label": "[Dev Container] Start Backend (Python)",
       "type": "shell",
       "command": "./isDevContainer.sh || exit 1; /services/start-backend.sh",
+      "detail": "Restarts the NetAlertX backend (Python) service in the dev container. This may take 5 seconds to be completely ready.",
       "options": {
         "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
       },
@@ -73,7 +93,8 @@
         "reveal": "always",
         "panel": "shared",
         "showReuseMessage": false,
-        "clear": false
+        "clear": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -85,6 +106,7 @@
       "label": "[Dev Container] Start CronD (Scheduler)",
       "type": "shell",
       "command": "./isDevContainer.sh || exit 1; /services/start-crond.sh",
+      "detail": "Stops and restarts the crond service.",
       "options": {
         "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
       },
@@ -93,7 +115,8 @@
         "reveal": "always",
         "panel": "shared",
         "showReuseMessage": false,
-        "clear": false
+        "clear": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -105,6 +128,7 @@
       "label": "[Dev Container] Start Frontend (nginx and PHP-FPM)",
       "type": "shell",
       "command": "./isDevContainer.sh || exit 1; /services/start-php-fpm.sh & /services/start-nginx.sh  &",
+      "detail": "Stops and restarts the NetAlertX frontend services (nginx and PHP-FPM) in the dev container. This launches almost instantly.",
       "options": {
         "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
 
@@ -114,7 +138,8 @@
         "reveal": "always",
         "panel": "shared",
         "showReuseMessage": false,
-        "clear": false
+        "clear": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -126,6 +151,7 @@
       "label": "[Dev Container] Stop Frontend & Backend Services",
       "type": "shell",
       "command": "./isDevContainer.sh || exit 1; pkill -f 'php-fpm83|nginx|crond|python3' || true",
+      "detail": "Stops all NetAlertX services running in the dev container.",
       "options": {
         "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
       },
@@ -133,7 +159,8 @@
         "echo": true,
         "reveal": "always",
         "panel": "shared",
-        "showReuseMessage": false
+        "showReuseMessage": false,
+        "group": "Devcontainer"
       },
       "problemMatcher": [],
       "icon": {
@@ -142,11 +169,54 @@
       }
     },
     {
-      "label": "[Dev Container] List NetAlertX Ports",
+      "label": "[Any] Build Unit Test Docker image",
       "type": "shell",
-      "command": "list-ports.sh",
+      "command": "docker buildx build -t netalertx-test . && echo '🧪 Unit Test Docker image built: netalertx-test'",
+      "detail": "This must be run after changes to the container.  Unit testing will not register changes until after this image is rebuilt. It takes about 30 seconds to build unless changes to the venv stage are made. venv takes 90s alone.",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Any"
+
+      },
+      "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
+      "icon": {
+        "id": "beaker",
+        "color": "terminal.ansiBlue"
+      }
+    },
+    {
+      "label": "[Dev Container] Wipe and Regenerate Database",
+      "type": "shell",
+      "command": "killall 'python3' || true && sleep 1 && rm -rf /data/db/* /data/config/* && bash /entrypoint.d/15-first-run-config.sh && bash /entrypoint.d/20-first-run-db.sh && echo '✅ Database and config wiped and regenerated'",
+      "detail": "Wipes devcontainer db and config. Provides a fresh start in devcontainer, run this task, then run the Rerun Startup Task",
+      "options": {},
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "shared",
+        "showReuseMessage": false,
+        "group": "Devcontainer"
+      },
+      "problemMatcher": [],
+      "icon": {
+        "id": "database",
+        "color": "terminal.ansiRed"
+      }
+    },
+    {
+      "label": "Build & Launch Prodcution Docker Container",
+      "type": "shell",
+      "command": "docker compose up -d --build --force-recreate",
+      "detail": "Before launching, ensure VSCode Ports are closed and services are stopped. Tasks: Stop Frontend & Backend Services & Remote: Close Unused Forwarded Ports to ensure proper operation of the new container.",
       "options": {
-        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
+        "cwd": "/workspaces/NetAlertX"
       },
       "presentation": {
         "echo": true,
@@ -155,8 +225,12 @@
         "showReuseMessage": false
       },
       "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      },
       "icon": {
-        "id": "output",
+        "id": "package",
         "color": "terminal.ansiBlue"
       }
     }

Dockerfile

@@ -43,14 +43,16 @@ ARG INSTALL_DIR=/app
 
 # NetAlertX app directories
 ENV NETALERTX_APP=${INSTALL_DIR}
-ENV NETALERTX_CONFIG=${NETALERTX_APP}/config
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
 ENV NETALERTX_FRONT=${NETALERTX_APP}/front
+ENV NETALERTX_PLUGINS=${NETALERTX_FRONT}/plugins
 ENV NETALERTX_SERVER=${NETALERTX_APP}/server
-ENV NETALERTX_API=${NETALERTX_APP}/api
+ENV NETALERTX_API=/tmp/api
-ENV NETALERTX_DB=${NETALERTX_APP}/db
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
 ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
 ENV NETALERTX_BACK=${NETALERTX_APP}/back
-ENV NETALERTX_LOG=${NETALERTX_APP}/log
+ENV NETALERTX_LOG=/tmp/log
 ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
 ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 
@@ -67,31 +69,35 @@ ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
 ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
 ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
 ENV LOG_CROND=${NETALERTX_LOG}/crond.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
 # System Services configuration files
+ENV ENTRYPOINT_CHECKS=/entrypoint.d
 ENV SYSTEM_SERVICES=/services
 ENV SYSTEM_SERVICES_SCRIPTS=${SYSTEM_SERVICES}/scripts
 ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
 ENV SYSTEM_NGINX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
 ENV SYSTEM_NGINX_CONFIG_FILE=${SYSTEM_NGINX_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
 ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
 ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
 ENV SYSTEM_SERVICES_CROND=${SYSTEM_SERVICES_CONFIG}/crond
-ENV SYSTEM_SERVICES_RUN=${SYSTEM_SERVICES}/run
+ENV SYSTEM_SERVICES_RUN=/tmp/run
 ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
 ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
 ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
 ENV READ_ONLY_FOLDERS="${NETALERTX_BACK} ${NETALERTX_FRONT} ${NETALERTX_SERVER} ${SYSTEM_SERVICES} \
-                       ${SYSTEM_SERVICES_CONFIG}"
+                       ${SYSTEM_SERVICES_CONFIG} ${ENTRYPOINT_CHECKS}"
-ENV READ_WRITE_FOLDERS="${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} ${NETALERTX_LOG} \
+ENV READ_WRITE_FOLDERS="${NETALERTX_DATA} ${NETALERTX_CONFIG} ${NETALERTX_DB} ${NETALERTX_API} \
-                       ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} ${SYSTEM_SERVICES_RUN_TMP} \
+                       ${NETALERTX_LOG} ${NETALERTX_PLUGINS_LOG} ${SYSTEM_SERVICES_RUN} \
-                       ${SYSTEM_SERVICES_RUN_LOG}"
+                       ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} \
+                       ${SYSTEM_SERVICES_ACTIVE_CONFIG}"
 
 #Python environment
 ENV PYTHONUNBUFFERED=1 
 ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
-ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${VIRTUAL_ENV}/lib/python3.12/site-packages
+ENV PYTHONPATH=${NETALERTX_APP}:${NETALERTX_SERVER}:${NETALERTX_PLUGINS}:${VIRTUAL_ENV}/lib/python3.12/site-packages
 ENV PATH="${SYSTEM_SERVICES}:${VIRTUAL_ENV_BIN}:$PATH" 
 
 # App Environment
@@ -99,7 +105,7 @@ ENV LISTEN_ADDR=0.0.0.0
 ENV PORT=20211
 ENV NETALERTX_DEBUG=0
 ENV VENDORSPATH=/app/back/ieee-oui.txt
-ENV VENDORSPATH_NEWEST=/services/run/tmp/ieee-oui.txt
+ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
 ENV ENVIRONMENT=alpine
 ENV READ_ONLY_USER=readonly READ_ONLY_GROUP=readonly
 ENV NETALERTX_USER=netalertx NETALERTX_GROUP=netalertx
@@ -123,11 +129,15 @@ COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} install/production-filesystem/
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 back ${NETALERTX_BACK}
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 front ${NETALERTX_FRONT}
 COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} --chmod=755 server ${NETALERTX_SERVER}
-RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 755 ${NETALERTX_API}  \
+
-    ${NETALERTX_LOG} ${SYSTEM_SERVICES_RUN_TMP} ${SYSTEM_SERVICES_RUN_LOG} && \
+# Create required folders with correct ownership and permissions
+RUN install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 ${READ_WRITE_FOLDERS} && \
     sh -c "find ${NETALERTX_APP} -type f \( -name '*.sh' -o -name 'speedtest-cli' \) \
     -exec chmod 750 {} \;"
 
+# Copy version information into the image
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .VERSION ${NETALERTX_APP}/.VERSION
+
 # Copy the virtualenv from the builder stage
 COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
@@ -181,7 +191,10 @@ RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     chmod -R 600 ${READ_WRITE_FOLDERS} && \
     find ${READ_WRITE_FOLDERS} -type d -exec chmod 700 {} + && \
     chown ${READ_ONLY_USER}:${READ_ONLY_GROUP} /entrypoint.sh /opt /opt/venv && \
-    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh /app /opt /opt/venv && \
+    chmod 005 /entrypoint.sh ${SYSTEM_SERVICES}/*.sh ${SYSTEM_SERVICES_SCRIPTS}/* ${ENTRYPOINT_CHECKS}/* /app /opt /opt/venv && \
+    for dir in ${READ_WRITE_FOLDERS}; do \
+        install -d -o ${NETALERTX_USER} -g ${NETALERTX_GROUP} -m 700 "$dir"; \
+    done && \
     apk del apk-tools && \
     rm -Rf /var /etc/sudoers.d/* /etc/shadow /etc/gshadow /etc/sudoers \
     /lib/apk /lib/firmware /lib/modules-load.d /lib/sysctl.d /mnt /home/ /root \

Dockerfile.debian

@@ -49,14 +49,15 @@ FROM debian:bookworm-slim
 # NetAlertX app directories
 ENV INSTALL_DIR=/app
 ENV NETALERTX_APP=${INSTALL_DIR}
-ENV NETALERTX_CONFIG=${NETALERTX_APP}/config
+ENV NETALERTX_DATA=/data
+ENV NETALERTX_CONFIG=${NETALERTX_DATA}/config
 ENV NETALERTX_FRONT=${NETALERTX_APP}/front
 ENV NETALERTX_SERVER=${NETALERTX_APP}/server
-ENV NETALERTX_API=${NETALERTX_APP}/api
+ENV NETALERTX_API=/tmp/api
-ENV NETALERTX_DB=${NETALERTX_APP}/db
+ENV NETALERTX_DB=${NETALERTX_DATA}/db
 ENV NETALERTX_DB_FILE=${NETALERTX_DB}/app.db
 ENV NETALERTX_BACK=${NETALERTX_APP}/back
-ENV NETALERTX_LOG=${NETALERTX_APP}/log
+ENV NETALERTX_LOG=/tmp/log
 ENV NETALERTX_PLUGINS_LOG=${NETALERTX_LOG}/plugins
 
 # NetAlertX log files
@@ -72,17 +73,19 @@ ENV LOG_EXECUTION_QUEUE=${NETALERTX_LOG}/execution_queue.log
 ENV LOG_REPORT_OUTPUT_JSON=${NETALERTX_LOG}/report_output.json
 ENV LOG_STDOUT=${NETALERTX_LOG}/stdout.log
 ENV LOG_CROND=${NETALERTX_LOG}/crond.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
 # System Services configuration files
 ENV SYSTEM_SERVICES=/services
 ENV SYSTEM_SERVICES_CONFIG=${SYSTEM_SERVICES}/config
 ENV SYSTEM_NGINIX_CONFIG=${SYSTEM_SERVICES_CONFIG}/nginx
 ENV SYSTEM_NGINX_CONFIG_FILE=${SYSTEM_NGINIX_CONFIG}/nginx.conf
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
 ENV NETALERTX_CONFIG_FILE=${NETALERTX_CONFIG}/app.conf
 ENV SYSTEM_SERVICES_PHP_FOLDER=${SYSTEM_SERVICES_CONFIG}/php
 ENV SYSTEM_SERVICES_PHP_FPM_D=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.d
 ENV SYSTEM_SERVICES_CROND=${SYSTEM_SERVICES_CONFIG}/crond
-ENV SYSTEM_SERVICES_RUN=${SYSTEM_SERVICES}/run
+ENV SYSTEM_SERVICES_RUN=/tmp/run
 ENV SYSTEM_SERVICES_RUN_TMP=${SYSTEM_SERVICES_RUN}/tmp
 ENV SYSTEM_SERVICES_RUN_LOG=${SYSTEM_SERVICES_RUN}/logs
 ENV PHP_FPM_CONFIG_FILE=${SYSTEM_SERVICES_PHP_FOLDER}/php-fpm.conf
@@ -94,7 +97,7 @@ ENV VIRTUAL_ENV=/opt/venv
 ENV VIRTUAL_ENV_BIN=/opt/venv/bin
 ENV PATH="${VIRTUAL_ENV}/bin:${PATH}:/services"
 ENV VENDORSPATH=/app/back/ieee-oui.txt
-ENV VENDORSPATH_NEWEST=/services/run/tmp/ieee-oui.txt
+ENV VENDORSPATH_NEWEST=${SYSTEM_SERVICES_RUN_TMP}/ieee-oui.txt
 
 
 # App Environment

README.md

@@ -6,21 +6,29 @@
 
 # NetAlertX - Network, presence scanner and alert framework
 
-Get visibility of what's going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT).
+Get visibility of what's going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT) and device inventory.
 
 ## 📋 Table of Contents
 
-- [Features](#-features)
+- [NetAlertX - Network, presence scanner and alert framework](#netalertx---network-presence-scanner-and-alert-framework)
-- [Documentation](#-documentation)
+  - [📋 Table of Contents](#-table-of-contents)
-- [Quick Start](#-quick-start)
+  - [🚀 Quick Start](#-quick-start)
-- [Alternative Apps](#-other-alternative-apps)
+  - [📦 Features](#-features)
-- [Security & Privacy](#-security--privacy)
+    - [Scanners](#scanners)
-- [FAQ](#-faq)
+    - [Notification gateways](#notification-gateways)
-- [Known Issues](#-known-issues)
+    - [Integrations and Plugins](#integrations-and-plugins)
-- [Donations](#-donations)
+    - [Workflows](#workflows)
-- [Contributors](#-contributors)
+  - [📚 Documentation](#-documentation)
-- [Translations](#-translations)
+  - [🔐 Security \& Privacy](#-security--privacy)
-- [License](#license)
+  - [❓ FAQ](#-faq)
+  - [🐞 Known Issues](#-known-issues)
+  - [📃 Everything else](#-everything-else)
+    - [📧 Get notified what's new](#-get-notified-whats-new)
+    - [🔀 Other Alternative Apps](#-other-alternative-apps)
+    - [💙 Donations](#-donations)
+    - [🏗 Contributors](#-contributors)
+    - [🌍 Translations](#-translations)
+    - [License](#license)
 
 
 ## 🚀 Quick Start
@@ -29,15 +37,23 @@ Start NetAlertX in seconds with Docker:
 
 ```bash
 docker run -d --rm --network=host \
-  -v local_path/config:/app/config \
+  -v local_path/config:/data/config \
-  -v local_path/db:/app/db \
+  -v local_path/db:/data/db \
-  --mount type=tmpfs,target=/app/api \
+  --mount type=tmpfs,target=/tmp/api \
   -e PUID=200 -e PGID=300 \
   -e TZ=Europe/Berlin \
   -e PORT=20211 \
   ghcr.io/jokob-sk/netalertx:latest
 ```
 
+To deploy a containerized instance directly from the source repository, execute the following BASH sequence:
+```bash
+git clone https://github.com/jokob-sk/NetAlertX.git
+cd NetAlertX
+docker compose up --force-recreate --build
+# To customize: edit docker-compose.yaml and run that last command again
+```
+
 Need help configuring it? Check the [usage guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) or [full documentation](https://jokob-sk.github.io/NetAlertX/).
 
 For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
@@ -45,7 +61,7 @@ For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistan
 For other install methods, check the [installation docs](#-documentation)
 
 
-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 
 
 ![showcase][showcase] 
@@ -87,7 +103,7 @@ The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORK
 
 Supported browsers: Chrome, Firefox
 
-- [[Installation] Docker](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) 
+- [[Installation] Docker](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) 
 - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) 
 - [[Installation] Bare metal](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 
 - [[Installation] Unraid App](https://unraid.net/community/apps) 
@@ -124,7 +140,7 @@ A: No. All scans and data remain local, unless you set up cloud-based notificati
 A: Yes! You can install it bare-metal. See the [bare metal installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md).
 
 **Q: Where is the data stored?**  
-A: In the `/config` and `/db` folders, mapped in Docker. Back up these folders regularly.
+A: In the `/data/config` and `/data/db` folders. Back up these folders regularly.
 
 
 ## 🐞 Known Issues

api

@@ -0,0 +1 @@
+/tmp/api

db/.gitignore

@@ -1,2 +0,0 @@
-*
-!.gitignore

docker-compose.yml

@@ -1,89 +1,75 @@
 services:
   netalertx:
-    network_mode: host                          # Use host networking for ARP scanning and other services
+  #use an environmental variable to set host networking mode if needed
+    network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services
     build:
-      context: .                                # Build context is the current directory   
+      context: .                                    # Build context is the current directory
-      dockerfile: Dockerfile                    # Specify the Dockerfile to use    
+      dockerfile: Dockerfile                        # Specify the Dockerfile to use
     image: netalertx:latest
-    container_name: netalertx                   # The name when you docker contiainer ls
+    container_name: netalertx                       # The name when you docker contiainer ls
-    read_only: true                             # Make the container filesystem read-only
+    read_only: true                                 # Make the container filesystem read-only
-    cap_drop:                                   # Drop all capabilities for enhanced security
+    cap_drop:                                       # Drop all capabilities for enhanced security
       - ALL
-    cap_add:                                    # Add only the necessary capabilities
+    cap_add:                                        # Add only the necessary capabilities
-      - NET_ADMIN                               # Required for ARP scanning
+      - NET_ADMIN                                   # Required for ARP scanning
-      - NET_RAW                                 # Required for raw socket operations
+      - NET_RAW                                     # Required for raw socket operations
-      - NET_BIND_SERVICE                        # Required to bind to privileged ports (nbtscan)
+      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
 
     volumes:
-      - type: bind
-        source: ${APP_DATA_LOCATION}/netalertx/config
-        target: /app/config
-        read_only: false
 
-      - type: bind
+      - type: volume                                # Persistent Docker-managed Named Volume for storage
-        source: ${APP_DATA_LOCATION}/netalertx/db
+        source: netalertx_data                      # the default name of the volume is netalertx_data
-        target: /app/db
+        target: /data                               # consolidated configuration and database storage
-        read_only: false
+        read_only: false                            # writable volume
 
-      - type: bind
+    # Example custom local folder called /home/user/netalertx_data
+    # - type: bind
+    #   source: /home/user/netalertx_data
+    #   target: /data
+    #   read_only: false
+    # ... or use the alternative format
+    # - /home/user/netalertx_data:/data:rw
+
+      - type: bind                           # Bind mount for timezone consistency
         source: /etc/localtime
         target: /etc/localtime
         read_only: true
 
-      # Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
+  # Use a custom Enterprise-configured nginx config for ldap or other settings
-      # - /path/on/host/log:/app/log
+  # - /custom-enterprise.conf:/tmp/nginx/active-config/netalertx.conf:ro
-      # Optional logs
-      # - type: bind
-      #   source: ${LOGS_LOCATION}
-      #   target: /app/log
-      #   read_only: false
-
-      # Optional development mounts
-      - type: bind
-        source: ${DEV_LOCATION}
-        target: /app/front/plugins/custom
-        read_only: false
-
-      # Use a custom Enterprise-configured nginx config for ldap or other settings
-      # - /custom-enterprise.conf:/services/config/nginx/conf.active/netalertx.conf:ro
 
       # Test your plugin on the production container
       # - /path/on/host:/app/front/plugins/custom
 
-    # Tempfs mounts for writable directories in a read-only container and improve system performance
+  # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
+  # - /path/on/host/log:/tmp/log
+
+    # tmpfs mounts for writable directories in a read-only container and improve system performance
+    # All writes now live under /tmp/* subdirectories which are created dynamically by entrypoint.d scripts
+    # uid=20211 and gid=20211 is the netalertx user inside the container
+    # mode=1700 gives rwx------ permissions to the netalertx user only
     tmpfs:
-      # Speed up logging. This can be commented out to retain logs between container restarts
-      - "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      # Speed up API access as frontend/backend API is very chatty
-      - "/app/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,sync,noatime,nodiratime"  
-      # Required for customization of the nginx listen addr/port without rebuilding the container
-      - "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      # /services/config/nginx/conf.d is required for nginx and php to start
-      - "/services/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      # /tmp is required by php for session save this should be reworked to /services/run/tmp
       - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
     environment:
-      LISTEN_ADDR: 0.0.0.0                          # Listen for connections on all interfaces
+      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                      # Listen for connections on all interfaces
-      PORT: ${PORT}                                 # Application port
+      PORT: ${PORT:-20211}                                      # Application port
-      ALWAYS_FRESH_INSTALL: ${ALWAYS_FRESH_INSTALL} # Set to true to reset your config and database on each container start
+      GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                      # GraphQL API port
-      NETALERTX_DEBUG: 0                            # 0=kill all services and restart if any dies. 1 keeps running dead services.
+      ALWAYS_FRESH_INSTALL: ${ALWAYS_FRESH_INSTALL:-false}      # Set to true to reset your config and database on each container start
-      TZ: ${TZ}                                     # Timezone, e.g. Europe/Paris
+      NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0}                    # 0=kill all services and restart if any dies. 1 keeps running dead services.
-      # APP_CONF_OVERRIDE={"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20223","UI_theme":"Light"} # (optional) app.conf settings override
-      # LOADED_PLUGINS=["DHCPLSS","PIHOLE","ASUSWRT","FREEBOX"] # (optional) default plugins to load
 
     # Resource limits to prevent resource exhaustion
-    mem_limit: 2048m
+    mem_limit: 2048m            # Maximum memory usage
-    mem_reservation: 1024m
+    mem_reservation: 1024m      # Soft memory limit
-    cpus: 4
+    cpu_shares: 512             # Relative CPU weight for CPU contention scenarios
-    pids_limit: 512
+    pids_limit: 512             # Limit the number of processes/threads to prevent fork bombs
     logging:
-      driver: "json-file"
+      driver: "json-file"       # Use JSON file logging driver
       options:
-        max-size: "10m"
+        max-size: "10m"         # Rotate log files after they reach 10MB
-        max-file: "3"
+        max-file: "3"           # Keep a maximum of 3 log files
+
+    # Always restart the container unless explicitly stopped
     restart: unless-stopped
 
-# volumes:
+volumes:                        # Persistent volume for configuration and database storage
-#   netalertx_config:
+  netalertx_data:
-#   netalertx_db:
- 

docs/API.md

@@ -64,8 +64,9 @@ http://<server>:<GRAPHQL_PORT>/
 * [Metrics](API_METRICS.md) – Prometheus metrics and per-device status
 * [Network Tools](API_NETTOOLS.md) – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
 * [Online History](API_ONLINEHISTORY.md) – Online/offline device records
-* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering
+* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering for Devices, Settings and Language Strings
 * [Sync](API_SYNC.md) – Synchronization between multiple NetAlertX instances
+* [Logs](API_LOGS.md) – Purging of logs and adding to the event execution queue for user triggered events
 * [DB query](API_DBQUERY.md) (⚠ Internal) - Low level database access - use other endpoints if possible
 
 See [Testing](API_TESTS.md) for example requests and usage.

docs/API_GRAPHQL.md

@@ -1,9 +1,10 @@
 # GraphQL API Endpoint
 
-GraphQL queries are **read-optimized for speed**. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allows you to access the following objects:
+GraphQL queries are **read-optimized for speed**. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allow you to access the following objects:
 
-- Devices
+* Devices
-- Settings
+* Settings
+* Language Strings (LangStrings)
 
 ## Endpoints
 
@@ -190,11 +191,74 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
 }
 ```
 
+
+---
+
+## LangStrings Query
+
+The **LangStrings query** provides access to localized strings. Supports filtering by `langCode` and `langStringKey`. If the requested string is missing or empty, you can optionally fallback to `en_us`.
+
+### Sample Query
+
+```graphql
+query GetLangStrings {
+  langStrings(langCode: "de_de", langStringKey: "settings_other_scanners") {
+    langStrings {
+      langCode
+      langStringKey
+      langStringText
+    }
+    count
+  }
+}
+```
+
+### Query Parameters
+
+| Parameter        | Type    | Description                                                                              |
+| ---------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `langCode`       | String  | Optional language code (e.g., `en_us`, `de_de`). If omitted, all languages are returned. |
+| `langStringKey`  | String  | Optional string key to retrieve a specific entry.                                        |
+| `fallback_to_en` | Boolean | Optional (default `true`). If `true`, empty or missing strings fallback to `en_us`.      |
+
+### `curl` Example
+
+```sh
+curl 'http://host:GRAPHQL_PORT/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer API_TOKEN' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetLangStrings { langStrings(langCode: \"de_de\", langStringKey: \"settings_other_scanners\") { langStrings { langCode langStringKey langStringText } count } }"
+  }'
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "langStrings": {
+      "count": 1,
+      "langStrings": [
+        {
+          "langCode": "de_de",
+          "langStringKey": "settings_other_scanners",
+          "langStringText": "Other, non-device scanner plugins that are currently enabled."  // falls back to en_us if empty
+        }
+      ]
+    }
+  }
+}
+```
+
 ---
 
 ## Notes
 
-* Device and settings queries can be combined in one request since GraphQL supports batching.
+* Device, settings, and LangStrings queries can be combined in **one request** since GraphQL supports batching.
+* The `fallback_to_en` feature ensures UI always has a value even if a translation is missing.
+* Data is **cached in memory** per JSON file; changes to language or plugin files will only refresh after the cache detects a file modification.
 * The `setOverriddenByEnv` flag helps identify setting values that are locked at container runtime.
 * The schema is **read-only** — updates must be performed through other APIs or configuration management. See the other [API](API.md) endpoints for details. 
 

docs/API_LOGS.md

@@ -0,0 +1,179 @@
+# Logs API Endpoints
+
+Manage or purge application log files stored under `/app/log` and manage the execution queue. These endpoints are primarily used for maintenance tasks such as clearing accumulated logs or adding system actions without restarting the container.
+
+Only specific, pre-approved log files can be purged for security and stability reasons.
+
+---
+
+## Delete (Purge) a Log File
+
+* **DELETE** `/logs?file=<log_file>` → Purge the contents of an allowed log file.
+
+**Query Parameter:**
+
+* `file` → The name of the log file to purge (e.g., `app.log`, `stdout.log`)
+
+**Allowed Files:**
+
+```
+app.log
+app_front.log
+IP_changes.log
+stdout.log
+stderr.log
+app.php_errors.log
+execution_queue.log
+db_is_locked.log
+```
+
+**Authorization:**
+Requires a valid API token in the `Authorization` header.
+
+---
+
+### `curl` Example (Success)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=app.log' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "[clean_log] File app.log purged successfully"
+}
+```
+
+---
+
+### `curl` Example (Not Allowed)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=not_allowed.log' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": false,
+  "message": "[clean_log] File not_allowed.log is not allowed to be purged"
+}
+```
+
+---
+
+### `curl` Example (Unauthorized)
+
+```sh
+curl -X DELETE 'http://<server_ip>:<GRAPHQL_PORT>/logs?file=app.log' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "error": "Forbidden"
+}
+```
+
+---
+
+## Add an Action to the Execution Queue
+
+* **POST** `/logs/add-to-execution-queue` → Add a system action to the execution queue.
+
+**Request Body (JSON):**
+
+```json
+{
+  "action": "update_api|devices"
+}
+```
+
+**Authorization:**
+Requires a valid API token in the `Authorization` header.
+
+---
+
+### `curl` Example (Success)
+
+The below will update the API cache for Devices
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data '{"action": "update_api|devices"}'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "[UserEventsQueueInstance] Action \"update_api|devices\" added to the execution queue."
+}
+```
+
+---
+
+### `curl` Example (Missing Parameter)
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data '{}'
+```
+
+**Response:**
+
+```json
+{
+  "success": false,
+  "message": "Missing parameters",
+  "error": "Missing required 'action' field in JSON body"
+}
+```
+
+---
+
+### `curl` Example (Unauthorized)
+
+```sh
+curl -X POST 'http://<server_ip>:<GRAPHQL_PORT>/logs/add-to-execution-queue' \
+  -H 'Content-Type: application/json' \
+  --data '{"action": "update_api|devices"}'
+```
+
+**Response:**
+
+```json
+{
+  "error": "Forbidden"
+}
+```
+
+---
+
+## Notes
+
+* Only predefined files in `/app/log` can be purged — arbitrary paths are **not permitted**.
+* When a log file is purged:
+
+  * Its content is replaced with a short marker text: `"File manually purged"`.
+  * A backend log entry is created via `mylog()`.
+  * A frontend notification is generated via `write_notification()`.
+* Execution queue actions are appended to `execution_queue.log` and can be processed asynchronously by background tasks or workflows.
+* Unauthorized or invalid attempts are safely logged and rejected.
+* For advanced log retrieval, analysis, or structured querying, use the frontend log viewer.
+* Always ensure that sensitive or production logs are handled carefully — purging cannot be undone.

docs/API_OLD.md

@@ -141,7 +141,7 @@ The endpoints are updated when objects in the API endpoints are changed.
 
 ### Location of the endpoints
 
-In the container, these files are located under the `/app/api/` folder. You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
+In the container, these files are located under the API directory (default: `/tmp/api/`, configurable via `NETALERTX_API` environment variable). You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
 
 ### Available endpoints
 
@@ -332,7 +332,7 @@ Grafana template sample: [Download json](./samples/API/Grafana_Dashboard.json)
 
 ## API Endpoint: /log files
 
-This API endpoint retrieves files from the `/app/log` folder. 
+This API endpoint retrieves files from the `/tmp/log` folder. 
 
 - Endpoint URL: `php/server/query_logs.php?file=<file name>`
 - Host: `same as front end (web ui)`
@@ -357,7 +357,7 @@ This API endpoint retrieves files from the `/app/log` folder.
 
 ## API Endpoint: /config files
 
-To retrieve files from the `/app/config` folder. 
+To retrieve files from the `/data/config` folder. 
 
 - Endpoint URL: `php/server/query_config.php?file=<file name>`
 - Host: `same as front end (web ui)`

docs/BACKUPS.md

@@ -1,90 +1,162 @@
-# Backing things up
+# Backing Things Up
 
 > [!NOTE]
-> To backup 99% of your configuration backup at least the `/app/config` folder. Please read the whole page (or at least "Scenario 2: Corrupted database") for details.
+> To back up 99% of your configuration, back up at least the `/data/config` folder.
-> Note that database definitions might change over time. The safest way is to restore your older backups into the **same version** of the app they were taken from and then gradually upgarde between releases to the latest version.
+> Database definitions can change between releases, so the safest method is to restore backups using the **same app version** they were taken from, then upgrade incrementally.
 
-There are 4 artifacts that can be used to backup the application:
+---
 
-| File                  | Description                   | Limitations                   |
+## What to Back Up
-|-----------------------|-------------------------------|-------------------------------|
-| `/db/app.db`       | Database file(s)  | The database file might be in an uncommitted state or corrupted |
-| `/config/app.conf` | Configuration file |  Can be overridden with the [`APP_CONF_OVERRIDE` env variable](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables).  |
-| `/config/devices.csv`  | CSV file containing device information |     Doesn't contain historical data        |
-| `/config/workflows.json`  | A JSON file containing your workflows |     N/A        |
 
+There are four key artifacts you can use to back up your NetAlertX configuration:
 
-## Backup strategies
+| File                     | Description                         | Limitations                                                                                                                                          |
+| ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/db/app.db`             | The application database            | Might be in an uncommitted state or corrupted                                                                                                        |
+| `/config/app.conf`       | Configuration file                  | Can be overridden using the [`APP_CONF_OVERRIDE`](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables) variable |
+| `/config/devices.csv`    | CSV file containing device data     | Does not include historical data                                                                                                                     |
+| `/config/workflows.json` | JSON file containing your workflows | N/A                                                                                                                                                  |
 
-The safest approach to backups is to backup everything, by taking regular file system backups of the `/db` and `/config` folders (I use [Kopia](https://github.com/kopia/kopia)). 
+---
 
-Arguably, the most time is spent setting up the device list, so if only one file is kept I'd recommend to have a latest backup of the `devices_<timestamp>.csv` or `devices.csv` file, followed by the `app.conf` and `workflows.json` files. You can also download `app.conf` and `devices.csv` file in the Maintenance section:
+## Where the Data Lives
 
-![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png)
+Understanding where your data is stored helps you plan your backup strategy.
-
-### Scenario 1: Full backup
-
-End-result: Full restore
-
-#### 💾 Source artifacts:
-
-- `/app/db/app.db` (uncorrupted)
-- `/app/config/app.conf`
-- `/app/config/workflows.json`
-
-#### 📥 Recovery:
-
-To restore the application map the above files as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths). 
-
-
-### Scenario 2: Corrupted database
-
-End-result: Partial restore (historical data and some plugin data will be missing)
-
-#### 💾 Source artifacts:
-
-- `/app/config/app.conf`
-- `/app/config/devices_<timestamp>.csv` or `/app/config/devices.csv`
-- `/app/config/workflows.json`
-
-#### 📥 Recovery:
-
-Even with a corrupted database you can recover what I would argue is 99% of the configuration. 
-
-- upload the `app.conf` and `workflows.json` files into the mounted `/app/config/` folder as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
-- rename the `devices_<timestamp>.csv` to `devices.csv` and place it in the `/app/config` folder
-- Restore the `devices.csv` backup via the [Maintenance section](./DEVICES_BULK_EDITING.md)
-
-## Data and backup storage
-
-To decide on a backup strategy, check where the data is stored:
 
 ### Core Configuration
 
-The core application configuration is in the `app.conf` file (See [Settings System](./SETTINGS_SYSTEM.md) for details), such as:
+Stored in `/data/config/app.conf`.
+This includes settings for:
 
-- Notification settings
+* Notifications
-- Scanner settings
+* Scanning
-- Scheduled maintenance settings
+* Scheduled maintenance
-- UI configuration
+* UI preferences
 
-### Core Device Data
+(See [Settings System](./SETTINGS_SYSTEM.md) for details.)
 
-The core device data is backed up to the `devices_<timestamp>.csv` or `devices.csv` file via the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup). This file contains data, such as:
+### Device Data
 
-- Device names
+Stored in `/data/config/devices_<timestamp>.csv` or `/data/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup).
-- Device icons
+Contains:
-- Device network configuration
-- Device categorization 
-- Device custom properties data
 
-### Historical data
+* Device names, icons, and categories
+* Network configuration
+* Custom properties
 
-Historical data is stored in the `app.db` database (See [Database overview](./DATABASE.md) for details). This data includes:
+### Historical Data
 
-- Plugin objects
+Stored in `/data/db/app.db` (see [Database Overview](./DATABASE.md)).
-- Plugin historical entries
+Contains:
-- History of Events, Notifications, Workflow Events
-- Presence history
 
+* Plugin data and historical entries
+* Event and notification history
+* Device presence history
 
+---
+
+## Backup Strategies
+
+The safest approach is to back up **both** the `/db` and `/config` folders regularly. Tools like [Kopia](https://github.com/kopia/kopia) make this simple and efficient.
+
+If you can only keep a few files, prioritize:
+
+1. The latest `devices_<timestamp>.csv` or `devices.csv`
+2. `app.conf`
+3. `workflows.json`
+
+You can also download the `app.conf` and `devices.csv` files from the **Maintenance** section:
+
+![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png)
+
+---
+
+## Scenario 1: Full Backup and Restore
+
+**Goal:** Full recovery of your configuration and data.
+
+### 💾 What to Back Up
+
+* `/data/db/app.db` (uncorrupted)
+* `/data/config/app.conf`
+* `/data/config/workflows.json`
+
+### 📥 How to Restore
+
+Map these files into your container as described in the [Setup documentation](./DOCKER_INSTALLATION.md).
+
+---
+
+## Scenario 2: Corrupted Database
+
+**Goal:** Recover configuration and device data when the database is lost or corrupted.
+
+### 💾 What to Back Up
+
+* `/data/config/app.conf`
+* `/data/config/workflows.json`
+* `/data/config/devices_<timestamp>.csv` (rename to `devices.csv` during restore)
+
+### 📥 How to Restore
+
+1. Copy `app.conf` and `workflows.json` into `/data/config/`
+2. Rename and place `devices_<timestamp>.csv` → `/data/config/devices.csv`
+3. Restore via the **Maintenance** section under *Devices → Bulk Editing*
+
+This recovers nearly all configuration, workflows, and device metadata.
+
+---
+
+## Docker-Based Backup and Restore
+
+For users running NetAlertX via Docker, you can back up or restore directly from your host system — a convenient and scriptable option.
+
+### Full Backup (File-Level)
+
+1. **Stop the container:**
+
+   ```bash
+   docker stop netalertx
+   ```
+
+2. **Create a compressed archive** of your configuration and database volumes:
+
+   ```bash
+   docker run --rm -v local_path/config:/config -v local_path/db:/db alpine tar -cz /config /db > netalertx-backup.tar.gz
+   ```
+
+3. **Restart the container:**
+
+   ```bash
+   docker start netalertx
+   ```
+
+### Restore from Backup
+
+1. **Stop the container:**
+
+   ```bash
+   docker stop netalertx
+   ```
+
+2. **Restore from your backup file:**
+
+   ```bash
+   docker run --rm -i -v local_path/config:/config -v local_path/db:/db alpine tar -C / -xz < netalertx-backup.tar.gz
+   ```
+
+3. **Restart the container:**
+
+   ```bash
+   docker start netalertx
+   ```
+
+> This approach uses a temporary, minimal `alpine` container to access Docker-managed volumes. The `tar` command creates or extracts an archive directly from your host’s filesystem, making it fast, clean, and reliable for both automation and manual recovery.
+
+---
+
+## Summary
+
+* Back up `/data/config` for configuration and devices; `/data/db` for history
+* Keep regular backups, especially before upgrades
+* For Docker setups, use the lightweight `alpine`-based backup method for consistency and portability

docs/BUILDS.md

@@ -0,0 +1,82 @@
+# NetAlertX Builds: Choose Your Path
+
+NetAlertX provides different installation methods for different needs. This guide helps you choose the right path for security, experimentation, or development.
+
+## 1. Hardened Appliance (Default Production)
+
+> [!NOTE]
+> Use this image if: You want to use NetAlertX securely.
+
+### Who is this for?
+
+All users who want a stable, secure, "set-it-and-forget-it" appliance.
+
+### Methodology
+
+- Multi-stage Alpine build
+- Aggressively "amputated"
+- Locked down for max security
+
+### Source
+
+`Dockerfile (hardened target)`
+
+## 2. "Tinkerer's" Image (Insecure VM-Style)
+
+> [!NOTE]
+> Use this image if: You want to experiment with NetAlertX.
+
+### Who is this for?
+
+Power users, developers, and "tinkerers" wanting a familiar "VM-like" experience.
+
+### Methodology
+
+- Traditional Debian build
+- Includes full un-hardened OS
+- Contains `apt`, `sudo`, `git`
+
+### Source
+
+`Dockerfile.debian`
+
+## 3. Contributor's Devcontainer (Project Developers)
+
+> [!NOTE]
+> Use this image if: You want to develop NetAlertX itself.
+
+### Who is this for?
+
+Project contributors who are actively writing and debugging code for NetAlertX.
+
+### Methodology
+
+
+- Builds `FROM runner` stage
+- Loaded by VS Code
+- Full debug tools: `xdebug`, `pytest`
+
+
+### Source
+
+`Dockerfile (devcontainer target)`
+
+# Visualizing the Trade-Offs
+
+This chart compares the three builds across key attributes. A higher score means "more of" that attribute. Notice the clear trade-offs between security and development features.
+
+![tradeoffs](./img/BUILDS/build_images_options_tradeoffs.png)
+
+
+# Build Process & Origins
+
+The final images originate from two different files and build paths. The main `Dockerfile` uses stages to create *both* the hardened and development container images.
+
+## Official Build Path
+
+Dockerfile -> builder (Stage 1) -> runner (Stage 2) ->  hardened (Final Stage) (Production Image) + devcontainer (Final Stage) (Developer Image)
+
+
+## Legacy Build Path
+
+Dockerfile.debian -> "Tinkerer's" Image (Insecure VM-Style Image)

docs/COMMON_ISSUES.md

@@ -14,9 +14,9 @@ The app uses the MAC address as an unique identifier for devices. If a new MAC i
 
 Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly.
 
-* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/app/log`. 
+* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/tmp/log`. 
-* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /app/db/app.db`. 
+* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /data/db/app.db`. 
-* If still facing issues, try to map the app.db file (⚠ not folder) to `:/app/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details)
+* If still facing issues, try to map the app.db file (⚠ not folder) to `:/data/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details)
 
 ### Container restarts / crashes
 
@@ -49,7 +49,7 @@ Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your d
 
 ### Losing my settings and devices after an update
 
-If you lose your devices and/or settings after an update that means you don't have the `/app/db` and `/app/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command.
+If you lose your devices and/or settings after an update that means you don't have the `/data/db` and `/data/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command.
 
 
 ### The application is slow

docs/DEBUG_PHP.md

@@ -27,7 +27,7 @@ Sometimes, the UI might not be accessible. In that case, you can access the logs
 3. **Check the PHP application error log:**
 
    ```bash
-   cat /app/log/app.php_errors.log
+   cat /tmp/log/app.php_errors.log
    ```
 
 These logs will help identify syntax issues, fatal errors, or startup problems when the UI fails to load properly.

docs/DEBUG_TIPS.md

@@ -14,8 +14,8 @@ Start the container via the **terminal** with a command similar to this one:
 
 ```bash
 docker run --rm --network=host \
-  -v local/path/netalertx/config:/app/config \
+  -v local/path/netalertx/config:/data/config \
-  -v local/path/netalertx/db:/app/db \
+  -v local/path/netalertx/db:/data/db \
   -e TZ=Europe/Berlin \
   -e PORT=20211 \
   ghcr.io/jokob-sk/netalertx:latest

docs/DOCKER_COMPOSE.md

@@ -1,203 +1,234 @@
-# `docker-compose.yaml` Examples
+# NetAlertX and Docker Compose
+
+> [!WARNING]
+> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
+> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container.  
+> These docs reflect the latest development version and may differ from the production image.
+
+Great care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.Good care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system. 
 
 > [!NOTE] 
-> The container needs to run in `network_mode:"host"`. This also means that not all functionality is supported on a Windows host as Docker for Windows doesn't support this networking option. 
+> The container needs to run in `network_mode:"host"` to access Layer 2 networking such as arp, nmap and others. Due to lack of support for this feature, Windows host is not a supported operating system. 
 
-### Example 1
+## Baseline Docker Compose
+
+There is one baseline for NetAlertX. That's the default security-enabled official distribution. 
 
 ```yaml
 services:
   netalertx:
-    container_name: netalertx
+  #use an environmental variable to set host networking mode if needed
-    # use the below line if you want to test the latest dev image
+    container_name: netalertx                       # The name when you docker contiainer ls
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: ghcr.io/jokob-sk/netalertx-dev:latest
-    image: "ghcr.io/jokob-sk/netalertx:latest"      
+    network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services
-    network_mode: "host"        
+
-    restart: unless-stopped
+    read_only: true                                 # Make the container filesystem read-only
+    cap_drop:                                       # Drop all capabilities for enhanced security
+      - ALL
+    cap_add:                                        # Add only the necessary capabilities
+      - NET_ADMIN                                   # Required for ARP scanning
+      - NET_RAW                                     # Required for raw socket operations
+      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
+
     volumes:
-      - local_path/config:/app/config
+      - type: volume                                # Persistent Docker-managed named volume for config + database
-      - local_path/db:/app/db      
+        source: netalertx_data
-      # (optional) useful for debugging if you have issues setting up the container
+        target: /data                               # `/data/config` and `/data/db` live inside this mount
-      - local_path/logs:/app/log
+        read_only: false
-      # (API: OPTION 1) use for performance
+
-      - type: tmpfs
+    # Example custom local folder called /home/user/netalertx_data
-        target: /app/api
+    # - type: bind
-      # (API: OPTION 2) use when debugging issues 
+    #   source: /home/user/netalertx_data
-      # -  local_path/api:/app/api
+    #   target: /data
+    #   read_only: false
+    # ... or use the alternative format
+    # - /home/user/netalertx_data:/data:rw
+
+      - type: bind                                  # Bind mount for timezone consistency
+        source: /etc/localtime                      # Alternatively add environment TZ: America/New York
+        target: /etc/localtime
+        read_only: true
+
+      # Mount your DHCP server file into NetAlertX for a plugin to access
+      # - path/on/host/to/dhcp.file:/resources/dhcp.file
+
+    # tmpfs mount consolidates writable state for a read-only container and improves performance
+    # uid=20211 and gid=20211 is the netalertx user inside the container
+    # mode=1700 grants rwx------ permissions to the netalertx user only
+    tmpfs:
+      # Comment out to retain logs between container restarts - this has a server performance impact.
+      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+
+      # Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts
+      # Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.
+      # - /path/on/host/log:/tmp/log
+      # - "/tmp/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - "/tmp/nginx:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - "/tmp/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+
     environment:
-      - TZ=Europe/Berlin      
+      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                   # Listen for connections on all interfaces
-      - PORT=20211
+      PORT: ${PORT:-20211}                                   # Application port
+      GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                   # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)
+  #    NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0}                 # 0=kill all services and restart if any dies. 1 keeps running dead services.
+
+    # Resource limits to prevent resource exhaustion
+    mem_limit: 2048m            # Maximum memory usage
+    mem_reservation: 1024m      # Soft memory limit
+    cpu_shares: 512             # Relative CPU weight for CPU contention scenarios
+    pids_limit: 512             # Limit the number of processes/threads to prevent fork bombs
+    logging:
+      driver: "json-file"       # Use JSON file logging driver
+      options:
+        max-size: "10m"         # Rotate log files after they reach 10MB
+        max-file: "3"           # Keep a maximum of 3 log files
+
+    # Always restart the container unless explicitly stopped
+    restart: unless-stopped
+
+volumes:                        # Persistent volume for configuration and database storage
+  netalertx_data:
 ```
 
-To run the container execute: `sudo docker-compose up -d`
+Run or re-run it:
 
-### Example 2
+```sh
-
+docker compose up --force-recreate
-Example by [SeimuS](https://github.com/SeimusS).
-
-```yaml
-services:
-  netalertx:
-    container_name: NetAlertX
-    hostname: NetAlertX
-    privileged: true
-    # use the below line if you want to test the latest dev image
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
-    image: ghcr.io/jokob-sk/netalertx:latest
-    environment:
-      - TZ=Europe/Bratislava
-    restart: always
-    volumes:
-      - ./netalertx/db:/app/db
-      - ./netalertx/config:/app/config
-    network_mode: host
 ```
 
-To run the container execute: `sudo docker-compose up -d`
+### Customize with Environmental Variables
 
-### Example 3
+You can override the default settings by passing environmental variables to the `docker compose up` command.
 
-`docker-compose.yml` 
+**Example using a single variable:**
+
+This command runs NetAlertX on port 8080 instead of the default 20211.
+
+```sh
+PORT=8080 docker compose up
+```
+
+**Example using all available variables:**
+
+This command demonstrates overriding all primary environmental variables: running with host networking, on port 20211, GraphQL on 20212, and listening on all IPs.
+
+```sh
+NETALERTX_NETWORK_MODE=host \
+LISTEN_ADDR=0.0.0.0 \
+PORT=20211 \
+GRAPHQL_PORT=20212 \
+NETALERTX_DEBUG=0 \
+docker compose up
+```
+
+## `docker-compose.yaml` Modifications
+
+### Modification 1: Use a Local Folder (Bind Mount)
+
+By default, the baseline compose file uses "named volumes" (`netalertx_config`, `netalertx_db`). **This is the preferred method** because NetAlertX is designed to manage all configuration and database settings directly from its web UI. Named volumes let Docker handle this data cleanly without you needing to manage local file permissions or paths.
+
+However, if you prefer to have direct, file-level access to your configuration for manual editing, a "bind mount" is a simple alternative. This tells Docker to use a specific folder from your computer (the "host") inside the container.
+
+**How to make the change:**
+
+1. Choose a location on your computer. For example, `/home/adam/netalertx-files`.
+
+2. Create the subfolders: `mkdir -p /home/adam/netalertx-files/config` and `mkdir -p /home/adam/netalertx-files/db`.
+
+3. Edit your `docker-compose.yml` and find the `volumes:` section (the one *inside* the `netalertx:` service).
+
+4. Comment out (add a `#` in front) or delete the `type: volume` blocks for `netalertx_config` and `netalertx_db`.
+
+5. Add new lines pointing to your local folders.
+
+**Before (Using Named Volumes - Preferred):**
 
 ```yaml
+...
+    volumes:
+      - netalertx_config:/data/config:rw #short-form volume (no /path is a short volume)
+      - netalertx_db:/data/db:rw
+...
+```
+
+**After (Using a Local Folder / Bind Mount):**
+Make sure to replace `/home/adam/netalertx-files` with your actual path. The format is `<path_on_your_computer>:<path_inside_container>:<options>`.
+
+```yaml
+...
+    volumes:
+#      - netalertx_config:/data/config:rw
+#      - netalertx_db:/data/db:rw
+      - /home/adam/netalertx-files/config:/data/config:rw
+      - /home/adam/netalertx-files/db:/data/db:rw
+...
+```
+
+Now, any files created by NetAlertX in `/data/config` will appear in your `/home/adam/netalertx-files/config` folder.
+
+This same method works for mounting other things, like custom plugins or enterprise NGINX files, as shown in the commented-out examples in the baseline file.
+
+## Example Configuration Summaries
+
+Here are the essential modifications for common alternative setups.
+
+### Example 2: External `.env` File for Paths
+
+This method is useful for keeping your paths and other settings separate from your main compose file, making it more portable.
+
+**`docker-compose.yml` changes:**
+
+```yaml
+...
 services:
   netalertx:
-    container_name: netalertx
-    # use the below line if you want to test the latest dev image
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
-    image: "ghcr.io/jokob-sk/netalertx:latest"      
-    network_mode: "host"        
-    restart: unless-stopped
-    volumes:
-      - ${APP_CONFIG_LOCATION}/netalertx/config:/app/config
-      - ${APP_DATA_LOCATION}/netalertx/db/:/app/db/      
-      # (optional) useful for debugging if you have issues setting up the container
-      - ${LOGS_LOCATION}:/app/log
-      # (API: OPTION 1) use for performance
-      - type: tmpfs
-        target: /app/api
-      # (API: OPTION 2) use when debugging issues 
-      # -  local/path/api:/app/api
     environment:
       - TZ=${TZ}
       - PORT=${PORT}
+      
+...
 ```
 
-`.env` file
+**`.env` file contents:**
-
-```yaml
-#GLOBAL PATH VARIABLES
-
-APP_DATA_LOCATION=/path/to/docker_appdata
-APP_CONFIG_LOCATION=/path/to/docker_config
-LOGS_LOCATION=/path/to/docker_logs
-
-#ENVIRONMENT VARIABLES
 
+```sh
 TZ=Europe/Paris
 PORT=20211
-
+NETALERTX_NETWORK_MODE=host
-#DEVELOPMENT VARIABLES
+LISTEN_ADDR=0.0.0.0
-
+PORT=20211
-DEV_LOCATION=/path/to/local/source/code
+GRAPHQL_PORT=20212
 ```
 
-To run the container execute: `sudo docker-compose --env-file /path/to/.env up`
+Run with: `sudo docker-compose --env-file /path/to/.env up`
 
+### Example 3: Docker Swarm
 
-### Example 4: Docker swarm
+This is for deploying on a Docker Swarm cluster. The key differences from the baseline are the removal of `network_mode:` from the service, and the addition of `deploy:` and `networks:` blocks at both the service and top-level.
 
-Notice how the host network is defined in a swarm setup:
+Here are the *only* changes you need to make to the baseline compose file to make it Swarm-compatible.
 
 ```yaml
 services:
   netalertx:
-    # Use the below line if you want to test the latest dev image
+    ...
-    # image: "jokobsk/netalertx-dev:latest"
+    #    network_mode: ${NETALERTX_NETWORK_MODE:-host} # <-- DELETE THIS LINE
-    image: "ghcr.io/jokob-sk/netalertx:latest"
+    ...
-    volumes:
+
-      - /mnt/MYSERVER/netalertx/config:/config:rw
+    # 2. ADD a 'networks:' block INSIDE the service to connect to the external host network.
-      - /mnt/MYSERVER/netalertx/db:/netalertx/db:rw
-      - /mnt/MYSERVER/netalertx/logs:/netalertx/front/log:rw
-    environment:
-      - TZ=Europe/London
-      - PORT=20211
     networks:
       - outside
+    # 3. ADD a 'deploy:' block to manage the service as a swarm replica.
     deploy:
       mode: replicated
       replicas: 1
       restart_policy:
         condition: on-failure
 
+
+# 4. ADD a new top-level 'networks:' block at the end of the file to define 'outside' as the external 'host' network.
 networks:
   outside:
     external:
       name: "host"
-
-
 ```
-
-### Example 5: same as 3 but with a top-level root directory; also works in Portainer as-is
-
-`docker-compose.yml` 
-
-```yaml
-services:
-  netalertx:
-    container_name: netalertx
-    # use the below line if you want to test the latest dev image instead of the stable release
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
-    image: "ghcr.io/jokob-sk/netalertx:latest"      
-
-    network_mode: "host"        
-    restart: unless-stopped
-    volumes:
-      - ${APP_FOLDER}/netalertx/config:/app/config
-      - ${APP_FOLDER}/netalertx/db:/app/db     
-      # (optional) useful for debugging if you have issues setting up the container
-      - ${APP_FOLDER}/netalertx/log:/app/log
-      # (API: OPTION 1) default -> use for performance
-      - type: tmpfs
-        target: /app/api
-      # (API: OPTION 2) use when debugging issues 
-      # -  ${APP_FOLDER}/netalertx/api:/app/api
-    environment:
-
-      - TZ=${TZ}
-      - PORT=${PORT}
-      - PUID=${PUID}
-      - PGID=${PGID}
-      - LISTEN_ADDR=${LISTEN_ADDR}
-```
-
-`.env` file
-
-```yaml
-APP_FOLDER=/path/to/local/NetAlertX/location
-
-#ENVIRONMENT VARIABLES
-
-PUID=200
-PGID=300
-
-TZ=America/New_York
-LISTEN_ADDR=0.0.0.0
-PORT=20211
-#GLOBAL PATH VARIABLE
-
-# you may want to create a dedicated user and group to run the container with 
-# sudo groupadd -g 300 nax-g 
-# sudo useradd -u 200 -g 300 nax-u
-# mkdir -p $APP_FOLDER/{db,config,log} 
-# chown -R 200:300 $APP_FOLDER
-# chmod -R 775 $APP_FOLDER
-
-# DEVELOPMENT VARIABLES
-# you can create  multiple env files called .env.dev1, .env.dev2 etc and use them by running:
-# docker compose --env-file .env.dev1 up -d
-# you can then clone  multiple dev copies of NetAlertX just make sure to change the APP_FOLDER and PORT variables in each .env.devX file
-
-```
-
-To run the container execute: `sudo docker-compose --env-file /path/to/.env up`

docs/DOCKER_INSTALLATION.md

@@ -6,7 +6,7 @@
 
 # NetAlertX - Network scanner & notification framework
 
-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 
 
 <a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
@@ -25,9 +25,9 @@ Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and scree
 
 ```yaml
 docker run -d --rm --network=host \
-  -v local_path/config:/app/config \
+  -v local_path/config:/data/config \
-  -v local_path/db:/app/db \
+  -v local_path/db:/data/db \
-  --mount type=tmpfs,target=/app/api \
+  --mount type=tmpfs,target=/tmp/api \
   -e PUID=200 -e PGID=300 \
   -e TZ=Europe/Berlin \
   -e PORT=20211 \
@@ -58,10 +58,10 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
 
 | Required | Path | Description |
 | :------------- | :------------- | :-------------| 
-| ✅ | `:/app/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files  | 
+| ✅ | `:/data/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files  | 
-| ✅ | `:/app/db` | Folder which will contain the `app.db` database file  | 
+| ✅ | `:/data/db` | Folder which will contain the `app.db` database file  | 
-| | `:/app/log` |  Logs folder useful for debugging if you have issues setting up the container  | 
+| | `:/tmp/log` |  Logs folder useful for debugging if you have issues setting up the container  | 
-| | `:/app/api` |  A simple [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files.   | 
+| | `:/tmp/api` |  A simple [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable.   | 
 | | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).  | 
 | | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REVERSE_DNS.md).  | 
 
@@ -70,7 +70,7 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
 ### Initial setup
 
 - If unavailable, the app generates a default `app.conf` and `app.db` file on the first run.
-- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/app/config/` folder directly 
+- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/data/config/` folder directly 
 
 #### Setting up scanners
 

docs/DOCKER_MAINTENANCE.md

@@ -0,0 +1,205 @@
+# The NetAlertX Container Operator's Guide
+
+> [!WARNING]
+> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
+> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container.  
+> These docs reflect the latest development version and may differ from the production image.
+
+This guide assumes you are starting with the official `docker-compose.yml` file provided with the project. We strongly recommend you start with or migrate to this file as your baseline and modify it to suit your specific needs (e.g., changing file paths). While there are many ways to configure NetAlertX, the default file is designed to meet the mandatory security baseline with layer-2 networking capabilities while operating securely and without startup warnings.
+
+This guide provides direct, concise solutions for common NetAlertX administrative tasks. It is structured to help you identify a problem, implement the solution, and understand the details.
+
+## Guide Contents
+ 
+- Using a Local Folder for Configuration  
+- Migrating from a Local Folder to a Docker Volume  
+- Applying a Custom Nginx Configuration  
+- Mounting Additional Files for Plugins  
+
+
+> [!NOTE]
+>
+>  Other relevant resources
+>  - [Fixing Permission Issues](./FILE_PERMISSIONS.md)
+>  - [Handling Backups](./BACKUPS.md)
+>  - [Accessing Application Logs](./LOGGING.md)
+
+---
+
+## Task: Using a Local Folder for Configuration
+
+### Problem
+
+You want to edit your `app.conf` and other configuration files directly from your host machine, instead of using a Docker-managed volume.
+
+### Solution
+
+1. Stop the container:
+
+   ```bash
+   docker-compose down
+   ```
+2. (Optional but Recommended) Back up your data using the method in Part 1.
+3. Create a local folder on your host machine (e.g., `/data/netalertx_config`).
+4. Edit `docker-compose.yml`:
+
+   * **Comment out** the `netalertx_config` volume entry.
+   * **Uncomment** and **set the path** for the "Example custom local folder" bind mount entry.
+
+   ```yaml
+   ...
+       volumes:
+         # - type: volume
+         #   source: netalertx_config
+         #   target: /data/config
+         #   read_only: false
+   ...
+       # Example custom local folder called /data/netalertx_config
+       - type: bind
+         source: /data/netalertx_config
+         target: /data/config
+         read_only: false
+   ...
+   ```
+5. (Optional) Restore your backup.
+6. Restart the container:
+
+   ```bash
+   docker-compose up -d
+   ```
+
+### About This Method
+
+This replaces the Docker-managed volume with a "bind mount." This is a direct mapping between a folder on your host computer (`/data/netalertx_config`) and a folder inside the container (`/data/config`), allowing you to edit the files directly.
+
+---
+
+## Task: Migrating from a Local Folder to a Docker Volume
+
+### Problem
+
+You are currently using a local folder (bind mount) for your configuration (e.g., `/data/netalertx_config`) and want to switch to the recommended Docker-managed volume (`netalertx_config`).
+
+### Solution
+
+1. Stop the container:
+
+   ```bash
+   docker-compose down
+   ```
+2. Edit `docker-compose.yml`:
+
+   * **Comment out** the bind mount entry for your local folder.
+   * **Uncomment** the `netalertx_config` volume entry.
+
+   ```yaml
+   ...
+       volumes:
+         - type: volume
+           source: netalertx_config
+           target: /data/config
+           read_only: false
+   ...
+       # Example custom local folder called /data/netalertx_config
+       # - type: bind
+       #   source: /data/netalertx_config
+       #   target: /data/config
+       #   read_only: false
+   ...
+   ```
+3. (Optional) Initialize the volume:
+
+   ```bash
+   docker-compose up -d && docker-compose down
+   ```
+4. Run the migration command (**replace `/data/netalertx_config` with your actual path**):
+
+   ```bash
+   docker run --rm -v netalertx_config:/config -v /data/netalertx_config:/local-config alpine \
+     sh -c "tar -C /local-config -c . | tar -C /config -x"
+   ```
+5. Restart the container:
+
+   ```bash
+   docker-compose up -d
+   ```
+
+### About This Method
+
+This uses a temporary `alpine` container that mounts *both* your source folder (`/local-config`) and destination volume (`/config`). The `tar ... | tar ...` command safely copies all files, including hidden ones, preserving structure.
+
+---
+
+## Task: Applying a Custom Nginx Configuration
+
+### Problem
+
+You need to override the default Nginx configuration to add features like LDAP, SSO, or custom SSL settings.
+
+### Solution
+
+1. Stop the container:
+
+   ```bash
+   docker-compose down
+   ```
+2. Create your custom config file on your host (e.g., `/data/my-netalertx.conf`).
+3. Edit `docker-compose.yml`:
+
+   ```yaml
+   ...
+       # Use a custom Enterprise-configured nginx config for ldap or other settings
+       - /data/my-netalertx.conf:/tmp/nginx/active-config/netalertx.conf:ro
+   ...
+   ```
+4. Restart the container:
+
+   ```bash
+   docker-compose up -d
+   ```
+
+### About This Method
+
+Docker’s bind mount overlays your host file (`my-netalertx.conf`) on top of the default file inside the container. The container remains read-only, but Nginx reads your file as if it were the default.
+
+---
+
+## Task: Mounting Additional Files for Plugins
+
+### Problem
+
+A plugin (like `DHCPLSS`) needs to read a file from your host machine (e.g., `/var/lib/dhcp/dhcpd.leases`).
+
+### Solution
+
+1. Stop the container:
+
+   ```bash
+   docker-compose down
+   ```
+2. Edit `docker-compose.yml` and add a new line under the `volumes:` section:
+
+   ```yaml
+   ...
+       volumes:
+   ...
+         # Mount for DHCPLSS plugin
+         - /var/lib/dhcp/dhcpd.leases:/mnt/dhcpd.leases:ro
+   ...
+   ```
+3. Restart the container:
+
+   ```bash
+   docker-compose up -d
+   ```
+4. In the NetAlertX web UI, configure the plugin to read from:
+
+   ```
+   /mnt/dhcpd.leases
+   ```
+
+### About This Method
+
+This maps your host file to a new, read-only (`:ro`) location inside the container. The plugin can then safely read this file without exposing anything else on your host filesystem.
+
+

docs/DOCKER_PORTAINER.md

@@ -45,18 +45,18 @@ services:
     restart: unless-stopped
 
     volumes:
-      - ${APP_FOLDER}/netalertx/config:/app/config
+      - ${APP_FOLDER}/netalertx/config:/data/config
-      - ${APP_FOLDER}/netalertx/db:/app/db
+      - ${APP_FOLDER}/netalertx/db:/data/db
       # Optional: logs (useful for debugging setup issues, comment out for performance)
-      - ${APP_FOLDER}/netalertx/log:/app/log
+      - ${APP_FOLDER}/netalertx/log:/tmp/log
 
       # API storage options:
       # (Option 1) tmpfs (default, best performance)
       - type: tmpfs
-        target: /app/api
+        target: /tmp/api
 
       # (Option 2) bind mount (useful for debugging)
-      # - ${APP_FOLDER}/netalertx/api:/app/api
+      # - ${APP_FOLDER}/netalertx/api:/tmp/api
 
     environment:
       - TZ=${TZ}

docs/DOCKER_SWARM.md

@@ -44,9 +44,9 @@ services:
     ports:
       - 20211:20211
     volumes:
-      - /mnt/YOUR_SERVER/netalertx/config:/app/config:rw
+      - /mnt/YOUR_SERVER/netalertx/config:/data/config:rw
-      - /mnt/YOUR_SERVER/netalertx/db:/netalertx/app/db:rw
+      - /mnt/YOUR_SERVER/netalertx/db:/netalertx/data/db:rw
-      - /mnt/YOUR_SERVER/netalertx/logs:/netalertx/app/log:rw
+      - /mnt/YOUR_SERVER/netalertx/logs:/netalertx/tmp/log:rw
     environment:
       - TZ=Europe/London
       - PORT=20211

docs/FILE_PERMISSIONS.md

@@ -1,23 +1,76 @@
-# Managing File Permissions for NetAlertX on Nginx with Docker
+# Managing File Permissions for NetAlertX on a Read-Only Container
 
 > [!TIP]
-> If you are facing permission issues, try to start the container without mapping your volumes. If that works, then the issue is permission related. You can try e.g., the following command: 
+> NetAlertX runs in a **secure, read-only Alpine-based container** under a dedicated `netalertx` user (UID 20211, GID 20211). All writable paths are either mounted as **persistent volumes** or **`tmpfs` filesystems**. This ensures consistent file ownership and prevents privilege escalation.
->  ``` 
->  docker run -d --rm --network=host \
->  -e TZ=Europe/Berlin \
->  -e PUID=200 -e PGID=200 \
->  -e PORT=20211 \
->  ghcr.io/jokob-sk/netalertx:latest
-> ```
-NetAlertX runs on an Nginx web server. On Alpine Linux, Nginx operates as the `nginx` user (if PUID and GID environment variables are not specified, nginx user UID will be set to 102, and its supplementary group `www-data` ID to 82). Consequently, files accessed or written by the NetAlertX application are owned by `nginx:www-data`.
 
-Upon starting, NetAlertX changes nginx user UID and www-data GID to specified values (or defaults), and the ownership of files on the host system mapped to `/app/config` and `/app/db` in the container to `nginx:www-data`. This ensures that Nginx can access and write to these files. Since the user in the Docker container is mapped to a user on the host system by ID:GID, the files in `/app/config` and `/app/db` on the host system are owned by a user with the same ID and GID (defaults are ID 102 and GID 82). On different systems, this ID:GID may belong to different users, or there may not be a group with ID 82 at all.
+---
 
-Option to set specific user UID and GID can be useful for host system users needing to access these files (e.g., backup scripts).
+## Writable Paths
+
+NetAlertX requires certain paths to be writable at runtime. These paths should be mounted either as **host volumes** or **`tmpfs`** in your `docker-compose.yml` or `docker run` command:
+
+| Path                                 | Purpose                             | Notes                                                  |
+| ------------------------------------ | ----------------------------------- | ------------------------------------------------------ |
+| `/data/config`                        | Application configuration           | Persistent volume recommended                          |
+| `/data/db`                            | Database files                      | Persistent volume recommended                          |
+| `/tmp/log`                           | Logs                                | Lives under `/tmp`; optional host bind to retain logs  |
+| `/tmp/api`                           | API cache                           | Subdirectory of `/tmp`                                 |
+| `/tmp/nginx/active-config` | Active nginx configuration override | Mount `/tmp` (or override specific file)               |
+| `/tmp/run`                      | Runtime directories for nginx & PHP | Subdirectory of `/tmp`                                 |
+| `/tmp`                               | PHP session save directory          | Backed by `tmpfs` for runtime writes                   |
+
+> Mounting `/tmp` as `tmpfs` automatically covers all of its subdirectories (`log`, `api`, `run`, `nginx/active-config`, etc.).
+
+> All these paths will have **UID 20211 / GID 20211** inside the container. Files on the host will appear owned by `20211:20211`.
+
+---
+
+## Fixing Permission Problems
+
+Sometimes, permission issues arise if your existing host directories were created by a previous container running as root or another UID. The container will fail to start with "Permission Denied" errors.
+
+### Solution
+
+1. **Run the container once as root** (`--user "0"`) to allow it to correct permissions automatically:
+
+```bash
+docker run -it --rm --name netalertx --user "0" \
+  -v local/path/config:/data/config \
+  -v local/path/db:/data/db \
+  ghcr.io/jokob-sk/netalertx:latest
+```
+
+2. Wait for logs showing **permissions being fixed**. The container will then **hang intentionally**.
+3. Press **Ctrl+C** to stop the container.
+4. Start the container normally with your `docker-compose.yml` or `docker run` command.
+
+> The container startup script detects `root` and runs `chown -R 20211:20211` on all volumes, fixing ownership for the secure `netalertx` user.
+
+---
+
+## Example: docker-compose.yml with `tmpfs`
+
+```yaml
+services:
+  netalertx:                                  
+    container_name: netalertx                
+    image: "ghcr.io/jokob-sk/netalertx"  
+    network_mode: "host"       
+    cap_add:
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/data/config         
+      - local/path/db:/data/db                 
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+    tmpfs:
+      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+```
+
+> This setup ensures all writable paths are either in `tmpfs` or host-mounted, and the container never writes outside of controlled volumes.
 
-### Permissions Table for Individual Folders
 
-| Folder         | User   | User ID | Group     | Group ID | Permissions | Notes                                                               |
-|----------------|--------|---------|-----------|----------|-------------|---------------------------------------------------------------------|
-| `/app/config`  | nginx  | PUID (default 102)     | www-data  | PGID (default 82)       | rwxr-xr-x   | Ensure `nginx` can read/write; other users can read if in `www-data` |
-| `/app/db`      | nginx  | PUID (default 102)     | www-data  | PGID (default 82)       | rwxr-xr-x   | Same as above                                                       |

docs/INSTALLATION.md

@@ -4,10 +4,10 @@
 
 NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal. 
 
-- [[Installation] Docker (recommended)](./INSTALLATION_DOCKER.md) 
+- [[Installation] Docker (recommended)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) 
 - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) 
 - [[Installation] Unraid App](https://unraid.net/community/apps) 
-- [[Installation] Bare metal (experimental - looking for maintainers)](./HW_INSTALL.md) 
+- [[Installation] Bare metal (experimental - looking for maintainers)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 
 
 
 ## Help

docs/LOGGING.md

@@ -1,17 +1,15 @@
 # Logging
 
-NetAlertX comes with several logs that help to identify application issues. 
+NetAlertX comes with several logs that help to identify application issues. These include nginx logs, app, or plugin logs. For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
-
-For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
-
-When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
 
+> [!NOTE]
+> When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
 
 ## Main logs
 
 You can find most of the logs exposed in the UI under _Maintenance -> Logs_. 
 
-If the UI is inaccessible, you can access them under `/app/log`.
+If the UI is inaccessible, you can access them under `/tmp/log`.
 
 ![Logs](./img/LOGGING/maintenance_logs.png)
 
@@ -24,3 +22,54 @@ If a Plugin supplies data to the main app it's done either vie a SQL query or vi
 The data is in most of the cases then displayed in the application under _Integrations -> Plugins_ (or _Device -> Plugins_ if the plugin is supplying device-specific data). 
 
 ![Plugin objects](./img/LOGGING/logging_integrations_plugins.png)
+
+## Viewing Logs on the File System
+
+You cannot find any log files on the filesystem. The container is `read-only` and writes logs to a temporary in-memory filesystem (`tmpfs`) for security and performance. The application follows container best-practices by writing all logs to the standard output (`stdout`) and standard error (`stderr`) streams. Docker's logging driver (set in `docker-compose.yml`) captures this stream automatically, allowing you to access it with the `docker logs <image_name>` command.
+
+* **To see all logs since the last restart:**
+
+  ```bash
+  docker logs netalertx
+  ```
+* **To watch the logs live (live feed):**
+
+  ```bash
+  docker logs -f netalertx
+  ```
+## Enabling Persistent File-Based Logs
+
+The default logs are erased every time the container restarts because they are stored in temporary in-memory storage (`tmpfs`). If you need to keep a persistent, file-based log history, follow the steps below.
+
+> [!NOTE]
+> This might lead to performance degradation so this approach is only suggested when actively debugging issues. See the [Performance optimization](./PERFORMANCE.md) documentation for details.
+
+1. Stop the container:
+
+   ```bash
+   docker-compose down
+   ```
+
+2. Edit your `docker-compose.yml` file:
+
+   * **Comment out** the `/tmp/log` line under the `tmpfs:` section.
+   * **Uncomment** the "Retain logs" line under the `volumes:` section and set your desired host path.
+
+   ```yaml
+   ...
+       tmpfs:
+         # - "/tmp/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+   ...
+       volumes:
+   ...
+         # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
+         - /home/adam/netalertx_logs:/tmp/log
+   ...
+   ```
+3. Restart the container:
+
+   ```bash
+   docker-compose up -d
+   ```
+
+This change stops Docker from mounting a temporary in-memory volume at `/tmp/log`. Instead, it "bind mounts" a persistent folder from your host computer (e.g., `/data/netalertx_logs`) to that *same location* inside the container. 

docs/MIGRATION.md

@@ -1,32 +1,58 @@
-# Migration form PiAlert to NetAlertX
+# Migration 
 
 > [!WARNING]
-> Follow this guide only after you you downloaded and started a version of NetAlertX prior to v25.6.7 (e.g. `docker pull ghcr.io/jokob-sk/netalertx:25.5.24`) at least once after previously using the PiAlert image. Later versions don't support migration and devices and settings will have to migrated manually, e.g. via [CSV import](./DEVICES_BULK_EDITING.md).
+> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
+> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container.  
+> These docs reflect the latest development version and may differ from the production image.
 
-## STEPS: 
+
+When upgrading from older versions of NetAlertX (or PiAlert by jokob-sk), follow the migration steps below to ensure your data and configuration are properly transferred.
 
 > [!TIP]
-> In short: The application will auto-migrate the database, config, and all device information. A ticker message on top will be displayed until you update your docker mount points. It's always good to have a [backup strategy](./BACKUPS.md) in place.
+> It's always important to have a [backup strategy](./BACKUPS.md) in place.
 
-1. Backup your current config and database (optional `devices.csv` to have a backup) (See bellow tip if facing issues)
+## Migration scenarios
-2. Stop the container 
+
-2. Update the Docker file mount locations in your `docker-compose.yml` or docker run command (See bellow **New Docker mount locations**). 
+- You are running PiAlert (by jokob-sk)  
-3. Rename the DB and conf files to `app.db` and `app.conf` and place them in the appropriate location.
+  → [Read the 1.1 Migration from PiAlert to NetAlertX `v25.5.24`](#11-migration-from-pialert-to-netalertx-v25524)
-4. Start the Container
+
+- You are running NetAlertX (by jokob-sk) `25.5.24` or older  
+  → [Read the 1.2 Migration from NetAlertX `v25.5.24`](#12-migration-from-netalertx-v25524)
+
+- You are running NetAlertX (by jokob-sk) (`v25.6.7` to `v25.10.1`)  
+  → [Read the 1.3 Migration from NetAlertX `v25.10.1`](#13-migration-from-netalertx-v25101)
+
+
+### 1.0 Manual Migration
+
+You can migrate data manually, for example by exporting and importing devices using the [CSV import](./DEVICES_BULK_EDITING.md) method.
+
+
+### 1.1 Migration from PiAlert to NetAlertX `v25.5.24`
+
+#### STEPS: 
+
+The application will automatically migrate the database, configuration, and all device information.
+A banner message will appear at the top of the web UI reminding you to update your Docker mount points.
+
+1. Stop the container 
+2. [Back up your setup](./BACKUPS.md) 
+3. Update the Docker file mount locations in your `docker-compose.yml` or docker run command (See below **New Docker mount locations**). 
+4. Rename the DB and conf files to `app.db` and `app.conf` and place them in the appropriate location.
+5. Start the container
 
 
 > [!TIP] 
-> If you have troubles accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container:  `cp -r /app/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` conatining all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over. 
+> If you have trouble accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container:  `cp -r /data/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` containing all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over. 
 
+#### New Docker mount locations
 
-### New Docker mount locations
+The internal application path in the container has changed from `/home/pi/pialert` to `/app`. Update your volume mounts as follows:
-
-The application installation folder in the docker container has changed from `/home/pi/pialert` to `/app`. That means the new mount points are:
 
  | Old mount point | New mount point | 
  |----------------------|---------------| 
- | `/home/pi/pialert/config` | `/app/config` |
+ | `/home/pi/pialert/config` | `/data/config` |
- | `/home/pi/pialert/db` | `/app/db` |
+ | `/home/pi/pialert/db` | `/data/db` |
 
 
  If you were mounting files directly, please note the file names have changed:
@@ -38,16 +64,16 @@ The application installation folder in the docker container has changed from `/h
 
 
 > [!NOTE] 
-> The application uses symlinks linking the old db and config locations to the new ones, so data loss should not occur. [Backup strategies](./BACKUPS.md) are still recommended to backup your setup.
+> The application automatically creates symlinks from the old database and config locations to the new ones, so data loss should not occur. Read the [backup strategies](./BACKUPS.md) guide to backup your setup.
 
 
-# Examples
+#### Examples
 
 Examples of docker files with the new mount points.
 
-## Example 1: Mapping folders
+##### Example 1: Mapping folders
 
-### Old docker-compose.yml
+###### Old docker-compose.yml
 
 ```yaml
 services:
@@ -68,34 +94,32 @@ services:
       - PORT=20211
 ```
 
-### New docker-compose.yml
+###### New docker-compose.yml
 
 ```yaml
 services:
-  netalertx:                                  # ⚠  This has changed (🟡optional) 
+  netalertx:                                  # 🆕 This has changed  
-    container_name: netalertx                 # ⚠  This has changed (🟡optional) 
+    container_name: netalertx                 # 🆕 This has changed  
-    # use the below line if you want to test the latest dev image
+    image: "ghcr.io/jokob-sk/netalertx:25.5.24"         # 🆕 This has changed  
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
-    image: "ghcr.io/jokob-sk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
     network_mode: "host"        
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         # ⚠  This has changed (🔺required) 
+      - local/path/config:/data/config         # 🆕 This has changed  
-      - local/path/db:/app/db                 # ⚠  This has changed (🔺required) 
+      - local/path/db:/data/db                 # 🆕 This has changed  
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log        # ⚠  This has changed (🟡optional) 
+      - local/path/logs:/tmp/log        # 🆕 This has changed  
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211
 ```
 
 
-## Example 2: Mapping files
+##### Example 2: Mapping files
 
 > [!NOTE] 
 > The recommendation is to map folders as in Example 1, map files directly only when needed. 
 
-### Old docker-compose.yml
+###### Old docker-compose.yml
 
 ```yaml
 services:
@@ -116,23 +140,151 @@ services:
       - PORT=20211
 ```
 
-### New docker-compose.yml
+###### New docker-compose.yml
 
 ```yaml
 services:
-  netalertx:                                  # ⚠  This has changed (🟡optional) 
+  netalertx:                                  # 🆕 This has changed  
-    container_name: netalertx                 # ⚠  This has changed (🟡optional) 
+    container_name: netalertx                 # 🆕 This has changed  
-    # use the below line if you want to test the latest dev image
+    image: "ghcr.io/jokob-sk/netalertx:25.5.24"         # 🆕 This has changed  
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
-    image: "ghcr.io/jokob-sk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
     network_mode: "host"        
     restart: unless-stopped
     volumes:
-      - local/path/config/app.conf:/app/config/app.conf # ⚠  This has changed (🔺required) 
+      - local/path/config/app.conf:/data/config/app.conf # 🆕 This has changed  
-      - local/path/db/app.db:/app/db/app.db             # ⚠  This has changed (🔺required) 
+      - local/path/db/app.db:/data/db/app.db             # 🆕 This has changed  
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log                  # ⚠  This has changed (🟡optional) 
+      - local/path/logs:/tmp/log                  # 🆕 This has changed  
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211
 ```
+
+
+### 1.2 Migration from NetAlertX `v25.5.24`
+
+Versions before `v25.10.1` require an intermediate migration through `v25.5.24` to ensure database compatibility. Skipping this step may cause compatibility issues due to database schema changes introduced after `v25.5.24`.
+
+#### STEPS: 
+
+1. Stop the container 
+2. [Back up your setup](./BACKUPS.md) 
+3. Upgrade to `v25.5.24` by pinning the release version (See Examples below)
+4. Start the container and verify everything works as expected.
+5. Stop the container 
+6. Upgrade to `v25.10.1` by pinning the release version (See Examples below)
+7. Start the container and verify everything works as expected.
+
+#### Examples
+
+Examples of docker files with the tagged version.
+
+##### Example 1: Mapping folders
+
+###### docker-compose.yml changes
+
+```yaml
+services:
+  netalertx:                                  
+    container_name: netalertx                
+    image: "ghcr.io/jokob-sk/netalertx:25.5.24"         # 🆕 This is important  
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/data/config         
+      - local/path/db:/data/db                 
+      # (optional) useful for debugging if you have issues setting up the container
+      - local/path/logs:/tmp/log        
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+```yaml
+services:
+  netalertx:                                  
+    container_name: netalertx                
+    image: "ghcr.io/jokob-sk/netalertx:25.10.1"         # 🆕 This is important  
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/data/config         
+      - local/path/db:/data/db                 
+      # (optional) useful for debugging if you have issues setting up the container
+      - local/path/logs:/tmp/log        
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+### 1.3 Migration from NetAlertX `v25.10.1`
+
+Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). 
+
+#### STEPS: 
+
+1. Stop the container 
+2. [Back up your setup](./BACKUPS.md) 
+3. Upgrade to `v25.10.1` by pinning the release version (See the example below)
+
+```yaml
+services:
+  netalertx:                                  
+    container_name: netalertx                
+    image: "ghcr.io/jokob-sk/netalertx:25.10.1"         # 🆕 This is important  
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/data/config         
+      - local/path/db:/data/db                 
+      # (optional) useful for debugging if you have issues setting up the container
+      - local/path/logs:/tmp/log        
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+4. Start the container and verify everything works as expected.
+5. Stop the container.
+6. Perform a one-off migration to the latest `netalertx` image and `20211` user:
+
+> [!NOTE]
+> The example below assumes your `/config` and `/db` folders are stored in `local/path`.  
+> Replace this path with your actual configuration directory. `netalertx` is the container name, which might differ from your setup.
+
+```sh
+docker run -it --rm --name netalertx --user "0" \
+  -v local/path/config:/data/config \
+  -v local/path/db:/data/db \
+  ghcr.io/jokob-sk/netalertx:latest
+```
+
+7. Stop the container
+8. Update the `docker-compose.yml` as per example below.
+
+```yaml
+services:
+  netalertx:                                  
+    container_name: netalertx                
+    image: "ghcr.io/jokob-sk/netalertx"         # 🆕 This is important  
+    network_mode: "host"       
+    cap_add:                          # 🆕 New line
+      - NET_RAW                       # 🆕 New line 
+      - NET_ADMIN                     # 🆕 New line
+      - NET_BIND_SERVICE              # 🆕 New line 
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/data/config         
+      - local/path/db:/data/db                 
+      # (optional) useful for debugging if you have issues setting up the container
+      #- local/path/logs:/tmp/log        
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+    # 🆕 New "tmpfs" section START 🔽
+    tmpfs:
+      # All writable runtime state resides under /tmp; comment out to persist logs between restarts
+      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+    # 🆕 New "tmpfs" section END  🔼
+```
+
+9. Start the container and verify everything works as expected.

docs/NOTIFICATIONS.md

@@ -44,10 +44,13 @@ In Notification Processing settings, you can specify blanket rules. These allow
 
 1. Notify on (`NTFPRCS_INCLUDED_SECTIONS`) allows you to specify which events trigger notifications. Usual setups will have `new_devices`, `down_devices`, and possibly `down_reconnected` set. Including `plugin` (dependenton the Plugin `<plugin>_WATCH` and `<plugin>_REPORT_ON` settings) and `events` (dependent on the on-device **Alert Events** setting) might be too noisy for most setups. More info in the [NTFPRCS plugin](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/notification_processing/README.md) on what events these selections include. 
 2. Alert down after (`NTFPRCS_alert_down_time`) is useful if you want to wait for some time before the system sends out a down notification for a device. This is related to the on-device **Alert down** setting and only devices with this checked will trigger a down notification.
-3. A filter to allow you to set device-specific exceptions to New devices being added to the app.
-4. A filter to allow you to set device-specific exceptions to generated Events.
 
-## Ignoring devices 🔕
+You can filter out unwanted notifications globally. This could be because of a misbehaving device (GoogleNest/GoogleHub (See also [ARPSAN docs and the `--exclude-broadcast` flag](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/arp_scan#ip-flipping-on-google-nest-devices))) which flips between IP addresses, or because you want to ignore new device notifications of a certain pattern.
+
+1. Events Filter (`NTFPRCS_event_condition`) - Filter out Events from notifications.
+2. New Devices Filter (`NTFPRCS_new_dev_condition`) - Filter out New Devices from notifications, but log and keep a new device in the system.
+
+## Ignoring devices 💻
 
 ![Ignoring new devices](./img/NOTIFICATIONS/NEWDEV_ignores.png)
 
@@ -55,3 +58,5 @@ You can completely ignore detected devices globally. This could be because your
 
 1. Ignored MACs (`NEWDEV_ignored_MACs`) - List of MACs to ignore.
 2. Ignored IPs (`NEWDEV_ignored_IPs`) - List of IPs to ignore. 
+
+

docs/PERFORMANCE.md

@@ -62,7 +62,7 @@ For example, the **ICMP plugin** allows you to specify a regular expression to s
 
 ## Storing Temporary Files in Memory
 
-On systems with slower I/O speeds, you can optimize performance by storing temporary files in memory. This primarily applies to the `/app/api` and `/app/log` folders.
+On systems with slower I/O speeds, you can optimize performance by storing temporary files in memory. This primarily applies to the API directory (default: `/tmp/api`, configurable via `NETALERTX_API`) and `/tmp/log` folders.
 
 Using `tmpfs` reduces disk writes and improves performance. However, it should be **disabled** if persistent logs or API data storage are required.
 
@@ -80,15 +80,15 @@ services:
     network_mode: "host"        
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config
+      - local/path/config:/data/config
-      - local/path/db:/app/db      
+      - local/path/db:/data/db      
       # (Optional) Useful for debugging setup issues
-      - local/path/logs:/app/log
+      - local/path/logs:/tmp/log
       # (API: OPTION 1) Store temporary files in memory (recommended for performance)
       - type: tmpfs              # ◀ 🔺
-        target: /app/api         # ◀ 🔺
+        target: /tmp/api         # ◀ 🔺
       # (API: OPTION 2) Store API data on disk (useful for debugging)
-      # - local/path/api:/app/api
+      # - local/path/api:/tmp/api
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211

docs/PIHOLE_GUIDE.md

@@ -1,6 +1,6 @@
 # Integration with PiHole
 
-NetAlertX comes with 2 plugins suitable for integarting with your existing PiHole instace. One plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine both approaches and also supplement it with other [plugins](/docs/PLUGINS.md). 
+NetAlertX comes with 2 plugins suitable for integrating with your existing PiHole instance. One plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine both approaches and also supplement it with other [plugins](/docs/PLUGINS.md). 
 
 ## Approach 1: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file
 

docs/PLUGINS_DEV_CONFIG.md

@@ -1,146 +1,192 @@
-## config.json Lifecycle in NetAlertX
+# Plugins Implementation Details
 
-This document describes on a high level how `config.json` is read, processed, and used by the NetAlertX core and plugins. It also outlines the plugin output contract and the main plugin types.
+Plugins provide data to the NetAlertX core, which processes it to detect changes, discover new devices, raise alerts, and apply heuristics.
 
-> [!NOTE]
+---
-> For a deep-dive on the specific configuration options and sections of the `config.json` plugin manifest, consult the [Plugins Development Guide](PLUGINS_DEV.md).
+
+## Overview: Plugin Data Flow
+
+1. Each plugin runs on a defined schedule.
+2. Aligning all plugin schedules is recommended so they execute in the same loop.
+3. During execution, all plugins write their collected data into the **`CurrentScan`** table.
+4. After all plugins complete, the `CurrentScan` table is evaluated to detect **new devices**, **changes**, and **triggers**.
+
+Although plugins run independently, they contribute to the shared `CurrentScan` table.
+To inspect its contents, set `LOG_LEVEL=trace` and check for the log section:
+
+```
+================ CurrentScan table content ================
+```
+
+---
+
+## `config.json` Lifecycle
+
+This section outlines how each plugin’s `config.json` manifest is read, validated, and used by the core and plugins.
+It also describes plugin output expectations and the main plugin categories.
+
+> [!TIP]
+> For detailed schema and examples, see the [Plugin Development Guide](PLUGINS_DEV.md).
 
 ---
 
 ### 1. Loading
 
-* On startup, the app core loads `config.json` for each plugin.
+* On startup, the core loads `config.json` for each plugin.
-* The `config.json` represents a plugin manifest, that contains metadata and runtime settings.
+* The file acts as a **plugin manifest**, defining metadata, runtime configuration, and database mappings.
 
 ---
 
 ### 2. Validation
 
-* The core checks that each required settings key (such as `RUN`) for a plugin exists.
+* The core validates required keys (for example, `RUN`).
-* Invalid or missing values may be replaced with defaults, or the plugin may be disabled.
+* Missing or invalid entries may be replaced with defaults or cause the plugin to be disabled.
 
 ---
 
 ### 3. Preparation
 
-* The plugin’s settings (paths, commands, parameters) are prepared.
+* Plugin parameters (paths, commands, and options) are prepared for execution.
-* Database mappings (`mapped_to_table`, `database_column_definitions`) for data ingestion into the core app are parsed.
+* Database mappings (`mapped_to_table`, `database_column_definitions`) are parsed to define how data integrates with the main app.
 
 ---
 
 ### 4. Execution
 
-* Plugins can be run at different core app execution points, such as on schedule, once on start, after a notification, etc. 
+* Plugins may run:
-* At runtime, the scheduler triggers plugins according to their `interval`.
+
-* The plugin executes its command or script.
+  * On a fixed schedule.
+  * Once at startup.
+  * After a notification or other trigger.
+* The scheduler executes plugins according to their `interval`.
 
 ---
 
 ### 5. Parsing
 
-* Plugin output is expected in **pipe (`|`)-delimited format**.
+* Plugin output must be **pipe-delimited (`|`)**.
-* The core parses lines into fields, matching the **plugin interface contract**.
+* The core parses each output line following the **Plugin Interface Contract**, splitting and mapping fields accordingly.
 
 ---
 
 ### 6. Mapping
 
-* Each parsed field is moved into the `Plugins_` database tables and can be mapped into a configured database table.
+* Parsed fields are inserted into the plugin’s `Plugins_*` table.
-* Controlled by `database_column_definitions` and `mapped_to_table`.
+* Data can be mapped into other tables (e.g., `Devices`, `CurrentScan`) as defined by:
-* Example: `Object_PrimaryID → Devices.MAC`.
+
+  * `database_column_definitions`
+  * `mapped_to_table`
+
+**Example:** `Object_PrimaryID → devMAC`
 
 ---
 
 ### 6a. Plugin Output Contract
 
-Each plugin must output results in the **plugin interface contract format**, pipe (`|`)-delimited values, in the column order described under [Plugin Interface Contract](PLUGINS_DEV.md)
+All plugins must follow the **Plugin Interface Contract** defined in `PLUGINS_DEV.md`.
+Output values are pipe-delimited in a fixed order.
 
-#### IDs
+#### Identifiers
 
-  * `Object_PrimaryID` and `Object_SecondaryID` identify the record (e.g. `MAC|IP`).
+* `Object_PrimaryID` and `Object_SecondaryID` uniquely identify records (for example, `MAC|IP`).
 
-#### **Watched values (`Watched_Value1–4`)**
+#### Watched Values (`Watched_Value1–4`)
 
-  * Used by the core to detect changes between runs.
+* Used by the core to detect changes between runs.
-  * Changes here can trigger **notifications**.
+* Changes in these fields can trigger notifications.
 
-#### **Extra value (`Extra`)**
+#### Extra Field (`Extra`)
 
-  * Optional, extra field.
+* Optional additional value.
-  * Stored in the database but **not used for alerts**.
+* Stored in the database but not used for alerts.
 
-#### **Helper values (`Helper_Value1–3`)**
+#### Helper Values (`Helper_Value1–3`)
 
-  * Added for cases where more than IDs + watched + extra are needed.
+* Optional auxiliary data (for display or plugin logic).
-  * Can be made visible in the UI.
+* Stored but not alert-triggering.
-  * Stored in the database but **not used for alerts**.
 
-#### **Mapping matters**
+#### Mapping
 
-  * While the plugin output is free-form, the `database_column_definitions` and `mapped_to_table` settings in `config.json` determine the **target columns and data types** in NetAlertX.
+* While the output format is flexible, the plugin’s manifest determines the destination and type of each field.
 
 ---
 
 ### 7. Persistence
 
-* Data is upserted into the database.
+* Parsed data is **upserted** into the database.
-* Conflicts are resolved using `Object_PrimaryID` + `Object_SecondaryID`.
+* Conflicts are resolved using the combined key: `Object_PrimaryID + Object_SecondaryID`.
 
 ---
 
-### 8. Plugin Types and Expected Outputs
+## Plugin Categories
 
-Beyond the `data_source` setting, plugins fall into functional categories. Each has its own input requirements and output expectations:
+Plugins fall into several functional categories depending on their purpose and expected outputs.
 
-#### **Device discovery plugins**
+### 1. Device Discovery Plugins
 
-  * **Inputs:** `N/A`, subnet, or API for discovery service, or similar.
+* **Inputs:** None, subnet, or discovery API.
-  * **Outputs:** At minimum `MAC` and `IP` that results in a new or updated device records in the `Devices` table.
+* **Outputs:** `MAC` and `IP` for new or updated device records in `Devices`.
-  * **Mapping:** Must be mapped to the `CurrentScan` table via `database_column_definitions` and `data_filters`.
+* **Mapping:** Required – usually into `CurrentScan`.
-  * **Examples:** ARP-scan, NMAP device discovery (e.g., `ARPSCAN`, `NMAPDEV`).
+* **Examples:** `ARPSCAN`, `NMAPDEV`.
-
-#### **Device-data enrichment plugins**
-
-  * **Inputs:** Device identifier (usually `MAC`, `IP`).
-  * **Outputs:** Additional data for that device (e.g. open ports).
-  * **Mapping:** Controlled via `database_column_definitions` and `data_filters`.
-  * **Examples:** Ports, MQTT messages (e.g., `NMAP`, `MQTT`)
-
-#### **Name resolver plugins**
-
-  * **Inputs:** Device identifiers (MAC, IP, or hostname).
-  * **Outputs:** Updated `devName` and `devFQDN` fields.
-  * **Mapping:** Not expected.
-  * **Note:** Currently requires **core app modification** to add new plugins, not fully driven by the plugins’ `config.json`.
-  * **Examples:** Avahiscan (e.g., `NBTSCAN`, `NSLOOKUP`).
-
-#### **Generic plugins**
-
-  * **Inputs:** Whatever the script or query provides.
-  * **Outputs:** Data shown only in **Integrations → Plugins**, not tied to devices.
-  * **Mapping:** Not expected.
-  * **Examples:** External monitoring data (e.g., `INTRSPD`)
-
-#### **Configuration-only plugins**
-
-  * **Inputs/Outputs:** None at runtime.
-  * **Mapping:** Not expected. 
-  * **Examples:** Used to provide additional settings or execute scripts (e.g., `MAINT`, `CSVBCKP`).
 
 ---
 
-### 9. Post-Processing
+### 2. Device Data Enrichment Plugins
 
-* Notifications are generated if watched values change.
+* **Inputs:** Device identifiers (`MAC`, `IP`).
-* UI is updated with new or updated records.
+* **Outputs:** Additional metadata (for example, open ports or sensors).
-* All values that are configured to be shown in teh UI appear in the Plugins section.
+* **Mapping:** Controlled via manifest definitions.
+* **Examples:** `NMAP`, `MQTT`.
 
 ---
 
-### 10. Summary
+### 3. Name Resolver Plugins
 
-The lifecycle of `config.json` entries is:
+* **Inputs:** Device identifiers (`MAC`, `IP`, hostname`).
+* **Outputs:** Updated `devName` and `devFQDN`.
+* **Mapping:** Typically none.
+* **Note:** Adding new resolvers currently requires a core change.
+* **Examples:** `NBTSCAN`, `NSLOOKUP`.
+
+---
+
+### 4. Generic Plugins
+
+* **Inputs:** Custom, based on the plugin logic or script.
+* **Outputs:** Data displayed under **Integrations → Plugins** only.
+* **Mapping:** Not required.
+* **Examples:** `INTRSPD`, custom monitoring scripts.
+
+---
+
+### 5. Configuration-Only Plugins
+
+* **Inputs/Outputs:** None at runtime.
+* **Purpose:** Used for configuration or maintenance tasks.
+* **Examples:** `MAINT`, `CSVBCKP`.
+
+---
+
+## Post-Processing
+
+After persistence:
+
+* The core generates notifications for any watched value changes.
+* The UI updates with new or modified data.
+* Plugins with UI-enabled data display under **Integrations → Plugins**.
+
+---
+
+## Summary
+
+The lifecycle of a plugin configuration is:
 
 **Load → Validate → Prepare → Execute → Parse → Map → Persist → Post-process**
 
-Plugins must follow the **output contract**, and their category (discovery, specific, resolver, generic, config-only) defines what inputs they require and what outputs are expected.
+Each plugin must:
+
+* Follow the **output contract**.
+* Declare its type and expected output structure.
+* Define mappings and watched values clearly in `config.json`.
+
+

docs/README.md

@@ -13,7 +13,7 @@ There is also an in-app Help / FAQ section that should be answering frequently a
 
 #### 🐳 Docker (Fully supported)
 
-- The main installation method is as a [docker container - follow these instructions here](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md). 
+- The main installation method is as a [docker container - follow these instructions here](./DOCKER_INSTALLATION.md). 
 
 #### 💻 Bare-metal / On-server (Experimental/community supported 🧪)
 

docs/REVERSE_DNS.md

@@ -42,9 +42,9 @@ services:
     image: "ghcr.io/jokob-sk/netalertx:latest"
     restart: unless-stopped
     volumes:
-      -  /home/netalertx/config:/app/config
+      -  /home/netalertx/config:/data/config
-      -  /home/netalertx/db:/app/db
+      -  /home/netalertx/db:/data/db
-      -  /home/netalertx/log:/app/log
+      -  /home/netalertx/log:/tmp/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -68,9 +68,9 @@ services:
     image: "ghcr.io/jokob-sk/netalertx:latest"
     restart: unless-stopped
     volumes:
-      - ./config/app.conf:/app/config/app.conf
+      - ./config/app.conf:/data/config/app.conf
-      - ./db:/app/db
+      - ./db:/data/db
-      - ./log:/app/log
+      - ./log:/tmp/log
       - ./config/resolv.conf:/etc/resolv.conf                          # Mapping the /resolv.conf file for better name resolution
     environment:
       - TZ=Europe/Berlin

docs/REVERSE_PROXY.md

@@ -499,8 +499,8 @@ Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/def
 ```bash
 docker run -d --rm --network=host \
   --name=netalertx \
-  -v /appl/docker/netalertx/config:/app/config \
+  -v /appl/docker/netalertx/config:/data/config \
-  -v /appl/docker/netalertx/db:/app/db \
+  -v /appl/docker/netalertx/db:/data/db \
   -v /appl/docker/netalertx/default:/etc/nginx/sites-available/default \
   -e TZ=Europe/Amsterdam \
   -e PORT=20211 \

docs/SECURITY_FEATURES.md

@@ -0,0 +1,85 @@
+# NetAlertX Security: A Layered Defense
+
+Your network security monitor has the "keys to the kingdom," making it a prime target for attackers. If it gets compromised, the game is over.
+
+NetAlertX is engineered from the ground up to prevent this. It's not just an app; it's a purpose-built **security appliance.** Its core design is built on a **zero-trust** philosophy, which is a modern way of saying we **assume a breach will happen** and plan for it. This isn't a single "lock on the door"; it's a **"defense-in-depth"** strategy, more like a medieval castle with a moat, high walls, and guards at every door.
+
+Here’s a breakdown of the defensive layers you get, right out of the box using the default configuration.
+
+## Feature 1: The "Digital Concrete" Filesystem
+
+**Methodology:** The core application and its system files are treated as immutable. Once built, the app's code is "set in concrete," preventing attackers from modifying it or planting malware.
+
+* **Immutable Filesystem:** At runtime, the container's entire filesystem is set to `read_only: true`. The application code, system libraries, and all other files are literally frozen. This single control neutralizes a massive range of common attacks.
+
+* **"Ownership-as-a-Lock" Pattern:** During the build, all system files are assigned to a special `readonly` user. This user has no login shell and no power to write to *any* files, even its own. It’s a clever, defense-in-depth locking mechanism.
+
+* **Data Segregation:** All user-specific data (like configurations and the device database) is stored completely outside the container in Docker volumes. The application is disposable; the data is persistent.
+
+**What's this mean to you:** Even if an attacker gets in, they **cannot modify the application code or plant malware.** It's like the app is set in digital concrete.
+
+## Feature 2: Surgical, "Keycard-Only" Access
+
+**Methodology:** The principle of least privilege is strictly enforced. Every process gets only the absolute minimum set of permissions needed for its specific job.
+
+* **Non-Privileged Execution:** The entire NetAlertX stack runs as a dedicated, low-power, non-root user (`netalertx`). No "god mode" privileges are available to the application.
+
+* **Kernel-Level Capability Revocation:** The container is launched with `cap_drop: - ALL`, which tells the Linux kernel to revoke *all* "root-like" special powers.
+
+* **Binary-Specific Privileges (setcap):** This is the "keycard" metaphor in action. After revoking all powers, the system uses `setcap` to grant specific, necessary permissions *only* to the binaries that absolutely require them (like `nmap` and `arp-scan`). This means that even if an attacker compromises the web server, they can't start scanning the network. The web server's "keycard" doesn't open the "scanning" door.
+
+**What's this mean to you:** A security breach is **firewalled.** An attacker who gets into the web UI **does not have the "keycard"** to start scanning your network or take over the system. The breach is contained.
+
+## Feature 3: Attack Surface "Amputation"
+
+**Methodology:** The potential attack surface is aggressively minimized by removing every non-essential tool an attacker would want to use.
+
+* **Package Manager Removal:** The `hardened` build stage explicitly deletes the Alpine package manager (`apk del apk-tools`). This makes it impossible for an attacker to simply `apk add` their malicious toolkit.
+
+* **`sudo` Neutralization:** All `sudo` configurations are removed, and the `/usr/bin/sudo` command is replaced with a non-functional shim. Any attempt to escalate privileges this way will fail.
+
+* **Build Toolchain Elimination:** The `Dockerfile` uses a multi-stage build. The initial "builder" stage, which contains all the powerful compilers (`gcc`) and development tools, is completely discarded. The final production image is lean and contains no build tools.
+
+* **Minimal User & Group Files:** The `hardened` stage scrubs the system's `passwd` and `group` files, removing all default system users to minimize potential avenues for privilege escalation.
+
+**What's this mean to you:** An attacker who breaks in finds themselves in an **empty room with no tools.** They have no `sudo` to get more power, no package manager to download weapons, and no compilers to build new ones.
+
+## Feature 4: "Self-Cleaning" Writable Areas
+
+**Methodology:** All writable locations are treated as untrusted, temporary, and non-executable by default.
+
+* **In-Memory Volatile Storage:** The `docker-compose.yml` configuration maps all temporary directories (e.g., `/tmp/log`, `/tmp/api`, `/tmp`) to in-memory `tmpfs` filesystems. They do not exist on the host's disk.
+
+* **Volatile Data:** Because these locations exist only in RAM, their contents are **instantly and irrevocably erased** when the container is stopped. This provides a "self-cleaning" mechanism that purges any attacker-dropped files or payloads on every single restart.
+
+* **Secure Mount Flags:** These in-memory mounts are configured with the `noexec` flag. This is a critical security control: it **prohibits the execution of any binary or script** from a location that is writable.
+
+**What's this mean to you:** Any malicious file an attacker *does* manage to drop is **written in invisible, non-permanent ink.** The file is written to RAM, not disk, so it **vaporizes the instant you restart** the container. Even worse for them, the `noexec` flag means they **can't even run the file** in the first place.
+
+## Feature 5: Built-in Resource Guardrails
+
+**Methodology:** The container is constrained by resource limits to function as a "good citizen" on the host system. This prevents a compromised or runaway process from consuming excessive resources, a common vector for Denial of Service (DoS) attacks.
+
+* **Process Limiting:** The `docker-compose.yml` defines a `pids_limit: 512`. This directly mitigates "fork bomb" attacks, where a process attempts to crash the host by recursively spawning thousands of new processes.
+
+* **Memory & CPU Limits:** The configuration file defines strict resource limits to prevent any single process from exhausting the host's available system resources.
+
+**What's this mean to you:** NetAlertX is a "good neighbor" and **can't be used to crash your host machine.** Even if a process is compromised, it's in a digital straitjacket and **cannot** pull a "denial of service" attack by hogging all your CPU or memory.
+
+## Feature 6: The "Pre-Flight" Self-Check
+
+**Methodology:** Before any services start, NetAlertX runs a comprehensive "pre-flight" check to ensure its own security and configuration are sound. It's like a built-in auditor who verifies its own defenses.
+
+* **Active Self-Diagnosis:** On every single boot, NetAlertX runs a series of startup pre-checks—and it's fast. The entire self-check process typically completes in less than a second, letting you get to the web UI in about three seconds from startup.
+
+* **Validates Its Own Security:** These checks actively inspect the other security features. For example, `check-0-permissions.sh` validates that all the "Digital Concrete" files are locked down and all the "Self-Cleaning" areas are writable, just as they should be. It also checks that the correct `netalertx` user is running the show, not `root`.
+
+* **Catches Misconfigurations:** This system acts as a "safety inspector" that catches misconfigurations *before* they can become security holes. If you've made a mistake in your configuration (like a bad folder permission or incorrect network mode), NetAlertX will tell you in the logs *why* it can't start, rather than just failing silently.
+
+**What's this mean to you:** The system is **self-aware and checks its own work.** You get instant feedback if a setting is wrong, and you get peace of mind on every single boot knowing all these security layers are **active and verified,** all in about one second.
+
+## Conclusion: Security by Default
+
+No single security control is a silver bullet. The robust security posture of NetAlertX is achieved through **defense in depth**, layering these methodologies.
+
+An adversary must not only gain initial access but must also find a way to write a payload to a non-executable, in-memory location, without access to any standard system tools, `sudo`, or a package manager. And they must do this while operating as an unprivileged user in a resource-limited environment where the application code is immutable and *actively checks its own integrity on every boot*.

docs/SYNOLOGY_GUIDE.md

@@ -40,10 +40,10 @@ services:
     network_mode: "host"        
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config
+      - local/path/config:/data/config
-      - local/path/db:/app/db      
+      - local/path/db:/data/db      
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log
+      - local/path/logs:/tmp/log
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211
@@ -57,10 +57,10 @@ services:
 
 ```yaml
  volumes:
-      - /volume1/app_storage/netalertx/config:/app/config
+      - /volume1/app_storage/netalertx/config:/data/config
-      - /volume1/app_storage/netalertx/db:/app/db      
+      - /volume1/app_storage/netalertx/db:/data/db      
       # (optional) useful for debugging if you have issues setting up the container
-      # - local/path/logs:/app/log <- commented out with # ⚠
+      # - local/path/logs:/tmp/log <- commented out with # ⚠
 ```
 
 ![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png)

docs/WEB_UI_PORT_DEBUG.md

@@ -15,7 +15,7 @@ The **Web UI** is served by an **nginx** server, while the **API backend** runs
   APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20212"}
   ```
 
-For more information, check the [Docker installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md).
+For more information, check the [Docker installation guide](./DOCKER_INSTALLATION.md).
 
 ## Possible issues and troubleshooting
 
@@ -62,11 +62,11 @@ In the container execute and investigate:
 
 `cat /var/log/nginx/error.log`
 
-`cat /app/log/app.php_errors.log`
+`cat /tmp/log/app.php_errors.log`
 
 ### 8. Make sure permissions are correct
 
 > [!TIP]
-> You can try to start the container without mapping the `/app/config` and `/app/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. 
+> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. 
 
-Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/app/db` and `app/config` directories. 
+Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories. 

docs/docker-troubleshooting/excessive-capabilities.md

@@ -0,0 +1,32 @@
+# Excessive Capabilities
+
+## Issue Description
+
+Excessive Linux capabilities are detected beyond the necessary NET_ADMIN, NET_BIND_SERVICE, and NET_RAW. This may indicate overly permissive container configuration.
+
+## Security Ramifications
+
+While the detected capabilities might not directly harm operation, running with more privileges than necessary increases the attack surface. If the container is compromised, additional capabilities could allow broader system access or privilege escalation.
+
+## Why You're Seeing This Issue
+
+This occurs when your Docker configuration grants more capabilities than required for network monitoring. The application only needs specific network-related capabilities for proper function.
+
+## How to Correct the Issue
+
+Limit capabilities to only those required:
+
+- In docker-compose.yml, specify only needed caps:
+  ```yaml
+  cap_add:
+    - NET_RAW
+    - NET_ADMIN
+    - NET_BIND_SERVICE
+  ```
+- Remove any unnecessary `--cap-add` or `--privileged` flags from docker run commands
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/file-permissions.md

@@ -0,0 +1,27 @@
+# File Permission Issues
+
+## Issue Description
+
+NetAlertX cannot read from or write to critical configuration and database files. This prevents the application from saving data, logs, or configuration changes.
+
+## Security Ramifications
+
+Incorrect file permissions can expose sensitive configuration data or database contents to unauthorized access. Network monitoring tools handle sensitive information about devices on your network, and improper permissions could lead to information disclosure.
+
+## Why You're Seeing This Issue
+
+This occurs when the mounted volumes for configuration and database files don't have proper ownership or permissions set for the netalertx user (UID 20211). The container expects these files to be accessible by the service account, not root or other users.
+
+## How to Correct the Issue
+
+Fix permissions on the host system for the mounted directories:
+
+- Ensure the config and database directories are owned by the netalertx user: `chown -R 20211:20211 /path/to/config /path/to/db`
+- Set appropriate permissions: `chmod -R 755 /path/to/config /path/to/db` for directories, `chmod 644` for files
+- Alternatively, restart the container with root privileges temporarily to allow automatic permission fixing, then switch back to the default user
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/incorrect-user.md

@@ -0,0 +1,28 @@
+# Incorrect Container User
+
+## Issue Description
+
+NetAlertX is running as UID:GID other than the expected 20211:20211. This bypasses hardened permissions, file ownership, and runtime isolation safeguards.
+
+## Security Ramifications
+
+The application is designed with security hardening that depends on running under a dedicated, non-privileged service account. Using a different user account can silently fail future upgrades and removes crucial isolation between the container and host system.
+
+## Why You're Seeing This Issue
+
+This occurs when you override the container's default user with custom `user:` directives in docker-compose.yml or `--user` flags in docker run commands. The container expects to run as the netalertx user for proper security isolation.
+
+## How to Correct the Issue
+
+Restore the container to the default user:
+
+- Remove any `user:` overrides from docker-compose.yml
+- Avoid `--user` flags in docker run commands
+- Allow the container to run with its default UID:GID 20211:20211
+- Recreate the container so volume ownership is reset automatically
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/missing-capabilities.md

@@ -0,0 +1,32 @@
+# Missing Network Capabilities
+
+## Issue Description
+
+Raw network capabilities (NET_RAW, NET_ADMIN, NET_BIND_SERVICE) are missing. Tools that rely on these capabilities (e.g., nmap -sS, arp-scan, nbtscan) will not function.
+
+## Security Ramifications
+
+Network scanning and monitoring requires low-level network access that these capabilities provide. Without them, the application cannot perform essential functions like ARP scanning, port scanning, or passive network discovery, severely limiting its effectiveness.
+
+## Why You're Seeing This Issue
+
+This occurs when the container doesn't have the necessary Linux capabilities granted. Docker containers run with limited capabilities by default, and network monitoring tools need elevated network privileges.
+
+## How to Correct the Issue
+
+Add the required capabilities to your container:
+
+- In docker-compose.yml:
+  ```yaml
+  cap_add:
+    - NET_RAW
+    - NET_ADMIN
+    - NET_BIND_SERVICE
+  ```
+- For docker run: `--cap-add=NET_RAW --cap-add=NET_ADMIN --cap-add=NET_BIND_SERVICE`
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/mount-configuration-issues.md

@@ -0,0 +1,36 @@
+# Mount Configuration Issues
+
+## Issue Description
+
+NetAlertX has detected configuration issues with your Docker volume mounts. These may include write permission problems, data loss risks, or performance concerns marked with ❌ in the table.
+
+## Security Ramifications
+
+Improper mount configurations can lead to data loss, performance degradation, or security vulnerabilities. For persistent data (database and configuration), using non-persistent storage like tmpfs can result in complete data loss on container restart. For temporary data, using persistent storage may unnecessarily expose sensitive logs or cache data.
+
+## Why You're Seeing This Issue
+
+This occurs when your Docker Compose or run configuration doesn't properly map host directories to container paths, or when the mounted volumes have incorrect permissions. The application requires specific paths to be writable for operation, and some paths should use persistent storage while others should be temporary.
+
+## How to Correct the Issue
+
+Review and correct your volume mounts in docker-compose.yml:
+
+- Ensure `${NETALERTX_DB}` and `${NETALERTX_CONFIG}` use persistent host directories
+- Ensure `${NETALERTX_API}`, `${NETALERTX_LOG}` have appropriate permissions
+- Avoid mounting sensitive paths to non-persistent filesystems like tmpfs for critical data
+- Use bind mounts with proper ownership (netalertx user: 20211:20211)
+
+Example volume configuration:
+```yaml
+volumes:
+  - ./data/db:/data/db
+  - ./data/config:/data/config
+  - ./data/log:/tmp/log
+```
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/network-mode.md

@@ -0,0 +1,27 @@
+# Network Mode Configuration
+
+## Issue Description
+
+NetAlertX is not running with `--network=host`. Bridge networking blocks passive discovery (ARP, NBNS, mDNS) and active scanning accuracy.
+
+## Security Ramifications
+
+Host networking is required for comprehensive network monitoring. Bridge mode isolates the container from raw network access needed for ARP scanning, passive discovery protocols, and accurate device detection. Without host networking, the application cannot fully monitor your network.
+
+## Why You're Seeing This Issue
+
+This occurs when your Docker configuration uses bridge networking instead of host networking. Network monitoring requires direct access to the host's network interfaces to perform passive discovery and active scanning.
+
+## How to Correct the Issue
+
+Enable host networking mode:
+
+- In docker-compose.yml, add: `network_mode: host`
+- For docker run, use: `--network=host`
+- Ensure the container has required capabilities: `--cap-add=NET_RAW --cap-add=NET_ADMIN --cap-add=NET_BIND_SERVICE`
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/nginx-configuration-mount.md

@@ -0,0 +1,36 @@
+# Nginx Configuration Mount Issues
+
+## Issue Description
+
+You've configured a custom port for NetAlertX, but the required nginx configuration mount is missing or not writable. Without this mount, the container cannot apply your port changes and will fall back to the default port 20211.
+
+## Security Ramifications
+
+Running in read-only mode (as recommended) prevents the container from modifying its own nginx configuration. Without a writable mount, custom port configurations cannot be applied, potentially exposing the service on unintended ports or requiring fallback to defaults.
+
+## Why You're Seeing This Issue
+
+This occurs when you set a custom PORT environment variable (other than 20211) but haven't provided a writable mount for nginx configuration. The container needs to write custom nginx config files when running in read-only mode.
+
+## How to Correct the Issue
+
+If you want to use a custom port, create a bind mount for the nginx configuration:
+
+- Create a directory on your host: `mkdir -p /path/to/nginx-config`
+- Add to your docker-compose.yml:
+  ```yaml
+  volumes:
+    - /path/to/nginx-config:/tmp/nginx/active-config
+  environment:
+    - PORT=your_custom_port
+  ```
+- Ensure it's owned by the netalertx user: `chown -R 20211:20211 /path/to/nginx-config`
+- Set permissions: `chmod -R 700 /path/to/nginx-config`
+
+If you don't need a custom port, simply omit the PORT environment variable and the container will use 20211 by default.
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/port-conflicts.md

@@ -0,0 +1,86 @@
+# Port Conflicts
+
+## Issue Description
+
+The configured application port (default 20211) or GraphQL API port (default 20212) is already in use by another service. This commonly occurs when you already have another NetAlertX instance running.
+
+## Security Ramifications
+
+Port conflicts prevent the application from starting properly, leaving network monitoring services unavailable. Running multiple instances on the same ports can also create configuration confusion and potential security issues if services are inadvertently exposed.
+
+## Why You're Seeing This Issue
+
+This error typically occurs when:
+
+- **You already have NetAlertX running** - Another Docker container or devcontainer instance is using the default ports 20211 and 20212
+- **Port conflicts with other services** - Other applications on your system are using these ports
+- **Configuration error** - Both PORT and GRAPHQL_PORT environment variables are set to the same value
+
+## How to Correct the Issue
+
+### Check for Existing NetAlertX Instances
+
+First, check if you already have NetAlertX running:
+
+```bash
+# Check for running NetAlertX containers
+docker ps | grep netalertx
+
+# Check for devcontainer processes
+ps aux | grep netalertx
+
+# Check what services are using the ports
+netstat -tlnp | grep :20211
+netstat -tlnp | grep :20212
+```
+
+### Stop Conflicting Instances
+
+If you find another NetAlertX instance:
+
+```bash
+# Stop specific container
+docker stop <container_name>
+
+# Stop all NetAlertX containers
+docker stop $(docker ps -q --filter ancestor=jokob-sk/netalertx)
+
+# Stop devcontainer services
+# Use VS Code command palette: "Dev Containers: Rebuild Container"
+```
+
+### Configure Different Ports
+
+If you need multiple instances, configure unique ports:
+
+```yaml
+environment:
+  - PORT=20211          # Main application port
+  - GRAPHQL_PORT=20212  # GraphQL API port
+```
+
+For a second instance, use different ports:
+
+```yaml
+environment:
+  - PORT=20213          # Different main port
+  - GRAPHQL_PORT=20214  # Different API port
+```
+
+### Alternative: Use Different Container Names
+
+When running multiple instances, use unique container names:
+
+```yaml
+services:
+  netalertx-primary:
+    # ... existing config
+  netalertx-secondary:
+    # ... config with different ports
+```
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/read-only-filesystem.md

@@ -0,0 +1,27 @@
+# Read-Only Filesystem Mode
+
+## Issue Description
+
+The container is running as read-write instead of read-only mode. This reduces the security hardening of the appliance.
+
+## Security Ramifications
+
+Read-only root filesystem is a security best practice that prevents malicious modifications to the container's filesystem. Running read-write allows potential attackers to modify system files or persist malware within the container.
+
+## Why You're Seeing This Issue
+
+This occurs when the Docker configuration doesn't mount the root filesystem as read-only. The application is designed as a security appliance that should prevent filesystem modifications.
+
+## How to Correct the Issue
+
+Enable read-only mode:
+
+- In docker-compose.yml, add: `read_only: true`
+- For docker run, use: `--read-only`
+- Ensure necessary directories are mounted as writable volumes (tmp, logs, etc.)
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/docker-troubleshooting/running-as-root.md

@@ -0,0 +1,29 @@
+# Running as Root User
+
+## Issue Description
+
+NetAlertX has detected that the container is running with root privileges (UID 0). This configuration bypasses all built-in security hardening measures designed to protect your system.
+
+## Security Ramifications
+
+Running security-critical applications like network monitoring tools as root grants unrestricted access to your host system. A successful compromise here could jeopardize your entire infrastructure, including other containers, host services, and potentially your network.
+
+## Why You're Seeing This Issue
+
+This typically occurs when you've explicitly overridden the container's default user in your Docker configuration, such as using `user: root` or `--user 0:0` in docker-compose.yml or docker run commands. The application is designed to run under a dedicated, non-privileged service account for security.
+
+## How to Correct the Issue
+
+Switch to the dedicated 'netalertx' user by removing any custom user directives:
+
+- Remove `user:` entries from your docker-compose.yml
+- Avoid `--user` flags in docker run commands
+- Ensure the container runs with the default UID 20211:20211
+
+After making these changes, restart the container. The application will automatically adjust ownership of required directories.
+
+## Additional Resources
+
+Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
+
+For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

docs/index.md

@@ -21,7 +21,7 @@ The app can be installed different ways, with the best support of the docker-bas
 
 NetAlertX is fully supported in Docker environments, allowing for easy setup and configuration. Follow the official guide to get started:
 
-- [Docker Installation Guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md)
+- [Docker Installation Guide](./DOCKER_INSTALLATION.md)
 
 This guide will take you through the process of setting up NetAlertX using Docker Compose or standalone Docker commands.
 

front/devices.php

@@ -15,9 +15,22 @@
 <?php
 
   require 'php/templates/header.php';
+  
   // check permissions
-  $dbPath = "../db/app.db";
+  // Use environment-aware paths with fallback to legacy locations
-  $confPath = "../config/app.conf";
+  $dbFolderPath = rtrim(getenv('NETALERTX_DB') ?: '/data/db', '/');
+  $configFolderPath = rtrim(getenv('NETALERTX_CONFIG') ?: '/data/config', '/');
+
+  $dbPath = $dbFolderPath . '/app.db';
+  $confPath = $configFolderPath . '/app.conf';
+
+  // Fallback to legacy paths if new locations don't exist
+  if (!file_exists($dbPath) && file_exists('../db/app.db')) {
+      $dbPath = '../db/app.db';
+  }
+  if (!file_exists($confPath) && file_exists('../config/app.conf')) {
+      $confPath = '../config/app.conf';
+  }
 
   checkPermissions([$dbPath, $confPath]);
 ?>
@@ -990,7 +1003,7 @@ function initializeDatatable (status) {
 
           // search only after idle
           var typingTimer;  // Timer identifier
-          var debounceTime = 500;  // Delay in milliseconds
+          var debounceTime = 750;  // Delay in milliseconds
 
           $('input[aria-controls="tableDevices"]').off().on('keyup', function () {
               clearTimeout(typingTimer);  // Clear the previous timer

front/js/common.js

@@ -12,7 +12,7 @@ var timerRefreshData = ''
 
 var   emptyArr      = ['undefined', "", undefined, null, 'null'];
 var   UI_LANG       = "English (en_us)";
-const allLanguages  = ["ar_ar","ca_ca","cs_cz","de_de","en_us","es_es","fa_fa","fr_fr","it_it","nb_no","pl_pl","pt_br","pt_pt","ru_ru","tr_tr","uk_ua","zh_cn"]; // needs to be same as in lang.php
+const allLanguages  = ["ar_ar","ca_ca","cs_cz","de_de","en_us","es_es","fa_fa","fr_fr","it_it","nb_no","pl_pl","pt_br","pt_pt","ru_ru","sv_sv","tr_tr","uk_ua","zh_cn"]; // needs to be same as in lang.php
 var   settingsJSON  = {}
 
 
@@ -337,6 +337,9 @@ function getLangCode() {
       case 'Turkish (tr_tr)':
         lang_code = 'tr_tr';
         break;
+      case 'Swedish (sv_sv)':
+        lang_code = 'sv_sv';
+        break;
       case 'Italian (it_it)':
         lang_code = 'it_it';
         break;

front/maintenance.php

@@ -17,11 +17,12 @@
 
 // Size and last mod of DB ------------------------------------------------------
 
-$nax_db = str_replace('front', 'db', getcwd()).'/app.db';
+$dbBasePath = rtrim(getenv('NETALERTX_DB') ?: '/data/db', '/');
-$nax_wal = str_replace('front', 'db', getcwd()).'/app.db-wal';
+$nax_db = $dbBasePath . '/app.db';
-$nax_db_size = number_format((filesize($nax_db) / 1000000),2,",",".") . ' MB';
+$nax_wal = $dbBasePath . '/app.db-wal';
-$nax_wal_size = number_format((filesize($nax_wal) / 1000000),2,",",".") . ' MB';
+$nax_db_size = file_exists($nax_db) ? number_format((filesize($nax_db) / 1000000),2,",",".") . ' MB' : '0 MB';
-$nax_db_mod = date ("F d Y H:i:s", filemtime($nax_db));
+$nax_wal_size = file_exists($nax_wal) ? number_format((filesize($nax_wal) / 1000000),2,",",".") . ' MB' : '0 MB';
+$nax_db_mod = file_exists($nax_db) ? date ("F d Y H:i:s", filemtime($nax_db)) : 'N/A';
 
 
 // Table sizes -----------------------------------------------------------------
@@ -334,7 +335,7 @@ $db->close();
 var emptyArr = ['undefined', "", undefined, null];
 var selectedTab                 = 'tab_DBTools_id';
 
-initializeTabs();
+// initializeTabs() is called in window.onload
 
 // -----------------------------------------------------------
 // delete devices with emty macs
@@ -704,7 +705,7 @@ function renderLogs(customData) {
 window.onload = function asyncFooter() {
   renderLogs();
 
-  // initializeTabs();
+  initializeTabs();
 
   try {
     $("#lastCommit").append('<a href="https://github.com/jokob-sk/NetAlertX/commits" target="_blank"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/jokob-sk/netalertx/main?logo=github"></a>');

front/php/components/logs.php

@@ -2,30 +2,60 @@
 
 require '../server/init.php';
 
+$logBasePath = rtrim(getenv('NETALERTX_LOG') ?: '/tmp/log', '/');
+
+function resolveLogPath($path)
+{
+    global $logBasePath;
+
+    if ($path === null || $path === '') {
+        return $path;
+    }
+
+    $placeholder = '__NETALERTX_LOG__';
+    if (strpos($path, $placeholder) === 0) {
+        return $logBasePath . substr($path, strlen($placeholder));
+    }
+
+    return $path;
+}
+
 //------------------------------------------------------------------------------
 // check if authenticated
 require_once  $_SERVER['DOCUMENT_ROOT'] . '/php/templates/security.php';
 
 // Function to render the log area component
 function renderLogArea($params) {
+    global $logBasePath;
+
     $fileName = isset($params['fileName']) ? $params['fileName'] : '';
     $filePath = isset($params['filePath']) ? $params['filePath'] : '';
     $textAreaCssClass = isset($params['textAreaCssClass']) ? $params['textAreaCssClass'] : '';
     $buttons = isset($params['buttons']) ? $params['buttons'] : [];
     $content = "";
+    $fileSize = 0;
 
-    if (filesize($filePath) > 2000000) {
+    $filePath = resolveLogPath($filePath);
+
+    if (!is_file($filePath)) {
+        $content = "";
+        $fileSizeMb = 0.0;
+    } elseif (filesize($filePath) > 2000000) {
         $content = file_get_contents($filePath, false, null, -2000000);
+        $fileSizeMb = filesize($filePath) / 1000000;
     } else {
         $content = file_get_contents($filePath);
+        $fileSizeMb = filesize($filePath) / 1000000;
     }
 
-    // Prepare the download button HTML if filePath starts with /app
+    // Prepare the download button HTML if filePath resides under the active log base path
     $downloadButtonHtml = '';
-    if (strpos($filePath, '/app') === 0) {
+    $logPrefix = $logBasePath . '/';
+    if ($logPrefix !== '/' && strpos($filePath, $logPrefix) === 0) {
+        $downloadName = basename($filePath);
         $downloadButtonHtml = '
             <span class="span-padding">
-                <a href="' . htmlspecialchars(str_replace('/app/log/', '/php/server/query_logs.php?file=', $filePath)) . '" target="_blank">
+                <a href="' . htmlspecialchars('/php/server/query_logs.php?file=' . rawurlencode($downloadName)) . '" target="_blank">
                     <i class="fa fa-download"></i>
                 </a>
             </span>';
@@ -34,13 +64,7 @@ function renderLogArea($params) {
     // Prepare buttons HTML
     $buttonsHtml = '';
     $totalButtons = count($buttons);
-    if ($totalButtons > 0) {
+    $colClass = $totalButtons > 0 ? (12 / $totalButtons) : 12;
-        $colClass = 12 / $totalButtons;
-        // Use $colClass in your HTML generation or further logic
-    } else {
-        // Handle case where $buttons array is empty
-        $colClass = 12;
-    }
 
     foreach ($buttons as $button) {
         $labelStringCode = isset($button['labelStringCode']) ? $button['labelStringCode'] : '';
@@ -52,8 +76,7 @@ function renderLogArea($params) {
             </div>';
     }
 
-
+    // Render HTML
-    // Render the log area HTML
     $html = '
         <div class="log-area box box-solid box-primary">
             <div class="row logs-row col-sm-12 col-xs-12">
@@ -63,7 +86,7 @@ function renderLogArea($params) {
             </div>
             <div class="row logs-row">
                 <div class="log-file col-sm-6 col-xs-12">' . htmlspecialchars($filePath) . '
-                    <div class="logs-size">' . number_format((filesize($filePath) / 1000000), 2, ",", ".") . ' MB'
+                    <div class="logs-size">' . number_format($fileSizeMb, 2, ",", ".") . ' MB'
                     . $downloadButtonHtml .
                     '</div>
                 </div>

front/php/components/logs_defaults.json

@@ -10,8 +10,8 @@
                 "event": "askRestartBackend()"
             }
         ],
-        "fileName": "app.log",
+    "fileName": "app.log",
-        "filePath": "/app/log/app.log",
+    "filePath": "__NETALERTX_LOG__/app.log",
         "textAreaCssClass": "logs"
 
     },
@@ -22,8 +22,8 @@
                 "event": "logManage('app_front.log', 'cleanLog')"
             }
         ],
-        "fileName": "app_front.log",
+    "fileName": "app_front.log",
-        "filePath": "/app/log/app_front.log",
+    "filePath": "__NETALERTX_LOG__/app_front.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
@@ -33,8 +33,8 @@
                 "event": "logManage('app.php_errors.log', 'cleanLog')"
             }
         ],
-        "fileName": "app.php_errors.log",
+    "fileName": "app.php_errors.log",
-        "filePath": "/app/log/app.php_errors.log",
+    "filePath": "__NETALERTX_LOG__/app.php_errors.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
@@ -44,15 +44,19 @@
                 "event": "logManage('execution_queue.log', 'cleanLog')"
             }
         ],
-        "fileName": "execution_queue.log",
+    "fileName": "execution_queue.log",
-        "filePath": "/app/log/execution_queue.log",
+    "filePath": "__NETALERTX_LOG__/execution_queue.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
         "buttons": [
+            {
+                "labelStringCode": "Maint_PurgeLog",
+                "event": "logManage('nginx-error.log', 'cleanLog')"
+            }
         ],
-        "fileName": "nginx/error.log",
+        "fileName": "nginx-error.log",
-        "filePath": "/var/log/nginx/error.log",
+        "filePath": "__NETALERTX_LOG__/nginx-error.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
@@ -62,8 +66,8 @@
                 "event": "logManage('db_is_locked.log', 'cleanLog')"
             }
         ],
-        "fileName": "db_is_locked.log",
+    "fileName": "db_is_locked.log",
-        "filePath": "/app/log/db_is_locked.log",
+    "filePath": "__NETALERTX_LOG__/db_is_locked.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
@@ -73,8 +77,8 @@
                 "event": "logManage('stdout.log', 'cleanLog')"
             }
         ],
-        "fileName": "stdout.log",
+    "fileName": "stdout.log",
-        "filePath": "/app/log/stdout.log",
+    "filePath": "__NETALERTX_LOG__/stdout.log",
         "textAreaCssClass": "logs logs-small"
     },
     {
@@ -84,8 +88,30 @@
                 "event": "logManage('stderr.log', 'cleanLog')"
             }
         ],
-        "fileName": "stderr.log",
+    "fileName": "stderr.log",
-        "filePath": "/app/log/stderr.log",
+    "filePath": "__NETALERTX_LOG__/stderr.log",
+        "textAreaCssClass": "logs logs-small"
+    },
+    {
+        "buttons": [
+            {
+                "labelStringCode": "Maint_PurgeLog",
+                "event": "logManage('IP_changes.log', 'cleanLog')"
+            }
+        ],
+    "fileName": "IP_changes.log",
+    "filePath": "__NETALERTX_LOG__/IP_changes.log",
+        "textAreaCssClass": "logs logs-small"
+    },
+    {
+        "buttons": [
+            {
+                "labelStringCode": "Maint_PurgeLog",
+                "event": "logManage('crond.log', 'cleanLog')"
+            }
+        ],
+    "fileName": "crond.log",
+    "filePath": "__NETALERTX_LOG__/crond.log",
         "textAreaCssClass": "logs logs-small"
     }
 ]

front/php/server/db.php

@@ -13,8 +13,35 @@
 // $DBFILE = dirname(__FILE__).'/../../../db/app.db';
 // $DBFILE_LOCKED_FILE = dirname(__FILE__).'/../../../log/db_is_locked.log';
 $scriptDir = realpath(dirname(__FILE__)); // Resolves symlinks to the actual physical path
-$DBFILE = $scriptDir . '/../../../db/app.db';
+$legacyDbPath = $scriptDir . '/../../../db/app.db';
-$DBFILE_LOCKED_FILE = $scriptDir . '/../../../log/db_is_locked.log';
+$legacyLogDir = $scriptDir . '/../../../log';
+
+$dbFolderPath = rtrim(getenv('NETALERTX_DB') ?: '/data/db', '/');
+$logFolderPath = rtrim(getenv('NETALERTX_LOG') ?: '/tmp/log', '/');
+
+// Fallback to legacy layout if the new location is missing but the legacy file still exists
+if (!is_dir($dbFolderPath) && file_exists($legacyDbPath)) {
+    $dbFolderPath = dirname($legacyDbPath);
+}
+
+if (!is_dir($dbFolderPath)) {
+    @mkdir($dbFolderPath, 0775, true);
+}
+
+$DBFILE = rtrim($dbFolderPath, '/') . '/app.db';
+if (!file_exists($DBFILE) && file_exists($legacyDbPath)) {
+    $DBFILE = $legacyDbPath;
+}
+
+if (!is_dir($logFolderPath) && is_dir($legacyLogDir)) {
+    $logFolderPath = $legacyLogDir;
+}
+
+if (!is_dir($logFolderPath)) {
+    @mkdir($logFolderPath, 0775, true);
+}
+
+$DBFILE_LOCKED_FILE = rtrim($logFolderPath, '/') . '/db_is_locked.log';
 
 
 //------------------------------------------------------------------------------
@@ -39,8 +66,10 @@ function SQLite3_connect($trytoreconnect = true, $retryCount = 0) {
         if (!file_exists($DBFILE)) {
             die("Database file not found: $DBFILE");
         }
-        if (!file_exists(dirname($DBFILE_LOCKED_FILE))) {
+
-            die("Log directory not found: " . dirname($DBFILE_LOCKED_FILE));
+        $lockDir = dirname($DBFILE_LOCKED_FILE);
+        if (!is_dir($lockDir) && !@mkdir($lockDir, 0775, true)) {
+            die("Log directory not found and could not be created: $lockDir");
         }
        
 
@@ -130,6 +159,7 @@ class CustomDatabaseWrapper {
         $message = 'Error executing query (attempts: ' . $attempts . '), query: ' . $query;        
         // write_notification($message);
         error_log("Query failed after {$this->maxRetries} attempts: " . $this->sqlite->lastErrorMsg());        
+        return false;
     }
 
     public function query_log_add($query)
@@ -187,7 +217,7 @@ function OpenDB($DBPath = null) {
 
     if (strlen($DBFILE) == 0) {
         $message = 'Database not available';
-        echo '<script>alert('.$message.')</script>';
+        echo '<script>alert("'.$message.'")</script>';
         write_notification($message);
         
         die('<div style="padding-left:150px">'.$message.'</div>');
@@ -197,7 +227,7 @@ function OpenDB($DBPath = null) {
         $db = new CustomDatabaseWrapper($DBFILE);
     } catch (Exception $e) {
         $message = "Error connecting to the database";
-        echo '<script>alert('.$message.'": ' . $e->getMessage() . '")</script>';
+        echo '<script>alert("'.$message.': '.$e->getMessage().'")</script>';
         write_notification($message);
         die('<div style="padding-left:150px">'.$message.'</div>');
     }

front/php/server/init.php

@@ -1,5 +1,6 @@
 <?php
-ini_set('error_log', '../../log/app.php_errors.log'); // initializing the app.php_errors.log file for the maintenance section
+$logPath = rtrim(getenv('NETALERTX_LOG') ?: '/tmp/log', '/') . '/app.php_errors.log';
+ini_set('error_log', $logPath); // initializing the app.php_errors.log file for the maintenance section
 require dirname(__FILE__).'/../templates/globals.php';
 require dirname(__FILE__).'/db.php';
 require dirname(__FILE__).'/util.php';

front/php/server/query_config.php

@@ -18,7 +18,8 @@ if ($_SERVER['REQUEST_METHOD'] === 'GET') {
     // Check if file parameter is provided
     if ($file) {
         // Define the folder where files are located
-        $filePath = "/app/config/" . basename($file);
+        $configRoot = getenv('NETALERTX_CONFIG') ?: '/data/config';
+        $filePath = rtrim($configRoot, '/') . "/" . basename($file);
 
         // Check if the file exists and is readable
         if (file_exists($filePath) && is_readable($filePath)) {

front/php/server/query_json.php

@@ -11,6 +11,8 @@ require dirname(__FILE__).'/../server/init.php';
 //------------------------------------------------------------------------------
 // Handle incoming requests
 if ($_SERVER['REQUEST_METHOD'] === 'GET') {
+    $configRoot = getenv('NETALERTX_CONFIG') ?: '/data/config';
+    $apiRoot = getenv('NETALERTX_API') ?: '/tmp/api';
     // Get query string parameter ?file=settings_table.json
     $file = isset($_GET['file']) ? $_GET['file'] : null;
 
@@ -19,10 +21,10 @@ if ($_SERVER['REQUEST_METHOD'] === 'GET') {
         // Define the folder where files are located
         if ($file == "workflows.json") 
         {
-            $filePath = "/app/config/" . basename($file);
+            $filePath = rtrim($configRoot, '/') . "/" . basename($file);
         } else
         {       
-            $filePath = "/app/api/" . basename($file);
+            $filePath = rtrim($apiRoot, '/') . "/" . basename($file);
         }
 
         // Check if the file exists
@@ -59,7 +61,8 @@ if ($_SERVER['REQUEST_METHOD'] === 'GET') {
     }
     
     $file = $_GET['file'];
-    $filePath = "/app/config/" . basename($file);
+    $configRoot = getenv('NETALERTX_CONFIG') ?: '/data/config';
+    $filePath = rtrim($configRoot, '/') . "/" . basename($file);
 
     // Save new workflows.json (replace existing content)
     if (file_put_contents($filePath, json_encode($decodedData, JSON_PRETTY_PRINT))) {

front/php/server/query_logs.php

@@ -16,8 +16,9 @@ if ($_SERVER['REQUEST_METHOD'] === 'GET') {
 
     // Check if file parameter is provided
     if ($file) {
-        // Define the folder where files are located
+    // Define the folder where files are located
-        $filePath = "/app/log/" . basename($file);
+    $logBasePath = rtrim(getenv('NETALERTX_LOG') ?: '/tmp/log', '/');
+    $filePath = $logBasePath . '/' . basename($file);
 
         // Check if the file exists
         if (file_exists($filePath)) {

front/php/server/util.php

@@ -11,6 +11,7 @@
 require dirname(__FILE__).'/../templates/globals.php';
 require dirname(__FILE__).'/../templates/skinUI.php';
 
+
 //------------------------------------------------------------------------------
 // check if authenticated
 require_once  $_SERVER['DOCUMENT_ROOT'] . '/php/templates/security.php';
@@ -176,7 +177,10 @@ function checkPermissions($files)
 }
 
 // ----------------------------------------------------------------------------------------
-
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
+// check server/api_server/api_server_start.py for equivalents
+// equivalent: /messaging/in-app/write
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
 function displayMessage($message, $logAlert = FALSE, $logConsole = TRUE, $logFile = TRUE, $logEcho = FALSE)
 {
   global $logFolderPath, $log_file, $timestamp;
@@ -234,7 +238,10 @@ function displayMessage($message, $logAlert = FALSE, $logConsole = TRUE, $logFil
 
 }
 
-
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
+// check server/api_server/api_server_start.py for equivalents
+// equivalent: /logs/add-to-execution-queue
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
 // ----------------------------------------------------------------------------------------
 // Adds an action to perform into the execution_queue.log file
 function addToExecutionQueue($action)
@@ -257,13 +264,17 @@ function addToExecutionQueue($action)
 
 
 // ----------------------------------------------------------------------------------------
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
+// check server/api_server/api_server_start.py for equivalents
+// equivalent: /logs DELETE
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
 function cleanLog($logFile)
 {  
   global $logFolderPath, $timestamp;
 
   $path = "";
 
-  $allowedFiles = ['app.log', 'app_front.log', 'IP_changes.log', 'stdout.log', 'stderr.log', 'app.php_errors.log', 'execution_queue.log', 'db_is_locked.log'];
+  $allowedFiles = ['app.log', 'app_front.log', 'IP_changes.log', 'stdout.log', 'stderr.log', 'app.php_errors.log', 'execution_queue.log', 'db_is_locked.log', 'nginx-error.log', 'crond.log'];
   
   if(in_array($logFile, $allowedFiles))
   {
@@ -312,7 +323,7 @@ function saveSettings()
 
   $txt = $txt."#-----------------AUTOGENERATED FILE-----------------#\n";
   $txt = $txt."#                                                    #\n";
-  $txt = $txt."#         Generated:  ".$timestamp."            #\n";
+  $txt = $txt."#         Generated:  ".$timestamp."                 #\n";
   $txt = $txt."#                                                    #\n";
   $txt = $txt."#   Config file for the LAN intruder detection app:  #\n";
   $txt = $txt."#      https://github.com/jokob-sk/NetAlertX         #\n";
@@ -321,7 +332,12 @@ function saveSettings()
 
   // collect all groups
 
-  $decodedSettings = json_decode($SETTINGS, true);
+  $decodedSettings = json_decode((string)$SETTINGS, true);
+
+  if ($decodedSettings === null) {
+      echo "Error: Invalid JSON in settings data.";
+      return;
+  }
 
   foreach ($decodedSettings as $setting) { 
     if( in_array($setting[0] , $groups) == false) {
@@ -418,6 +434,10 @@ function saveSettings()
 }
 
 // -------------------------------------------------------------------------------------------
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
+// check server/api_server/api_server_start.py for equivalents
+// equivalent: /graphql LangStrings endpoint
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
 function getString ($setKey, $default) {
 
   $result = lang($setKey);
@@ -430,9 +450,14 @@ function getString ($setKey, $default) {
   return $default;
 }
 // -------------------------------------------------------------------------------------------
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
+// check server/api_server/api_server_start.py for equivalents
+// equivalent: /settings/<key>
+// 🔺----- API ENDPOINTS SUPERSEDED -----🔺
 function getSettingValue($setKey) {
   // Define the JSON endpoint URL
-  $url = dirname(__FILE__).'/../../../api/table_settings.json';  
+  $apiRoot = rtrim(getenv('NETALERTX_API') ?: '/tmp/api', '/');
+  $url = $apiRoot . '/table_settings.json';
 
   // Fetch the JSON data
   $json = file_get_contents($url);

front/php/server/utilNotification.php

@@ -7,6 +7,11 @@
 
 require dirname(__FILE__).'/../templates/globals.php';
 
+function get_notification_store_path(): string {
+    $apiRoot = getenv('NETALERTX_API') ?: '/tmp/api';
+    return rtrim($apiRoot, '/') . '/user_notifications.json';
+}
+
 //------------------------------------------------------------------------------
 // check if authenticated
 require_once  $_SERVER['DOCUMENT_ROOT'] . '/php/templates/security.php';
@@ -69,7 +74,7 @@ function generate_guid() {
 // ----------------------------------------------------------------------------------------
 // Logs a notification in in-app notification system
 function write_notification($content, $level = "interrupt") {
-    $NOTIFICATION_API_FILE = '/app/api/user_notifications.json';
+    $NOTIFICATION_API_FILE = get_notification_store_path();
 
     // Generate GUID
     $guid = generate_guid();
@@ -102,7 +107,7 @@ function write_notification($content, $level = "interrupt") {
 // ----------------------------------------------------------------------------------------
 // Removes a notification based on GUID
 function remove_notification($guid) {
-    $NOTIFICATION_API_FILE = '/app/api/user_notifications.json';
+    $NOTIFICATION_API_FILE = get_notification_store_path();
 
     // Read existing notifications
     $notifications = json_decode(file_get_contents($NOTIFICATION_API_FILE), true);
@@ -119,7 +124,7 @@ function remove_notification($guid) {
 // ----------------------------------------------------------------------------------------
 // Deletes all notifications
 function notifications_clear() {
-    $NOTIFICATION_API_FILE = '/app/api/user_notifications.json';
+    $NOTIFICATION_API_FILE = get_notification_store_path();
 
     // Clear notifications by writing an empty array to the file
     file_put_contents($NOTIFICATION_API_FILE, json_encode(array()));
@@ -128,7 +133,7 @@ function notifications_clear() {
 // ----------------------------------------------------------------------------------------
 // Mark a notification read based on GUID
 function mark_notification_as_read($guid) {
-    $NOTIFICATION_API_FILE = '/app/api/user_notifications.json';
+    $NOTIFICATION_API_FILE = get_notification_store_path();
     $max_attempts = 3;
     $attempts = 0;
 
@@ -177,7 +182,7 @@ function notifications_mark_all_read() {
 
 // ----------------------------------------------------------------------------------------
 function get_unread_notifications() {
-    $NOTIFICATION_API_FILE = '/app/api/user_notifications.json';
+    $NOTIFICATION_API_FILE = get_notification_store_path();
 
     // Read existing notifications
     if (file_exists($NOTIFICATION_API_FILE) && is_readable($NOTIFICATION_API_FILE)) {

front/php/templates/auth.php

@@ -15,7 +15,19 @@ if (isset($_SESSION["login"]) && $_SESSION["login"] == 1) {
 
 // Check if a valid cookie is present
 $CookieSaveLoginName = "NetAlertX_SaveLogin";
-$config_file = "../../../config/app.conf"; // depends on where this file is called from
+
+// Use environment-aware config path
+$configFolderPath = rtrim(getenv('NETALERTX_CONFIG') ?: '/data/config', '/');
+$config_file = $configFolderPath . '/app.conf';
+
+// Fallback to legacy path if new location doesn't exist
+if (!file_exists($config_file)) {
+    $legacyPath = "../../../config/app.conf";
+    if (file_exists($legacyPath)) {
+        $config_file = $legacyPath;
+    }
+}
+
 $config_file_lines = file($config_file);
 $config_file_lines = array_values(preg_grep('/^SETPWD_password.*=/', $config_file_lines));
 $password_line = explode("'", $config_file_lines[0]);

front/php/templates/globals.php

@@ -4,8 +4,8 @@
 // ## Global constants and TimeZone processing
 // ######################################################################
 
-$configFolderPath = "/app/config/";
+$configFolderPath = rtrim(getenv('NETALERTX_CONFIG') ?: '/data/config', '/') . '/';
-$logFolderPath = "/app/log/";
+$logFolderPath = rtrim(getenv('NETALERTX_LOG') ?: '/tmp/log', '/') . '/';
 
 $config_file = "app.conf";
 $workflows_file = "workflows.json";

front/php/templates/language/ca_ca.json

@@ -674,7 +674,7 @@
     "Systeminfo_System_Uptime": "Uptime:",
     "Systeminfo_This_Client": "Aquest Client",
     "Systeminfo_USB_Devices": "Dispositius USB",
-    "TICKER_MIGRATE_TO_NETALERTX": "⚠ S'han detectat punts muntatge antics. Ves a <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">aquesta guia</a> per migrar les noves <code>/app/config</code> i <code>/app/db</code> carpetes i al <code>netalertx</code> contenidor.",
+    "TICKER_MIGRATE_TO_NETALERTX": "⚠ S'han detectat punts muntatge antics. Ves a <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">aquesta guia</a> per migrar les noves <code>/data/config</code> i <code>/data/db</code> carpetes i al <code>netalertx</code> contenidor.",
     "TIMEZONE_description": "Fus horari per mostrar les estadístiques correctament. <a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/List_of_tz_database_time_zones\" rel=\"nofollow\">aquí</a>.",
     "TIMEZONE_name": "Fus horari",
     "UI_DEV_SECTIONS_description": "Seleccioneu quins elements de la interfície d'usuari per ocultar a les pàgines de dispositius.",

front/php/templates/language/cs_cz.json

@@ -9,7 +9,7 @@
     "About_Exit": "Odhlásit",
     "About_Title": "Scanner síťové bezpečnosti a framework pro upozornění",
     "AppEvents_AppEventProcessed": "Zpracováno",
-    "AppEvents_DateTimeCreated": "Objeveno",
+    "AppEvents_DateTimeCreated": "Zaznamenáno",
     "AppEvents_Extra": "Extra",
     "AppEvents_GUID": "",
     "AppEvents_Helper1": "",
@@ -25,8 +25,8 @@
     "AppEvents_ObjectStatus": "",
     "AppEvents_ObjectStatusColumn": "",
     "AppEvents_ObjectType": "",
-    "AppEvents_Plugin": "",
+    "AppEvents_Plugin": "Zásuvný modul",
-    "AppEvents_Type": "",
+    "AppEvents_Type": "Typ",
     "BackDevDetail_Actions_Ask_Run": "",
     "BackDevDetail_Actions_Not_Registered": "",
     "BackDevDetail_Actions_Title_Run": "Spustit akci",
@@ -74,7 +74,7 @@
     "DevDetail_DisplayFields_Title": "",
     "DevDetail_EveandAl_AlertAllEvents": "",
     "DevDetail_EveandAl_AlertDown": "",
-    "DevDetail_EveandAl_Archived": "",
+    "DevDetail_EveandAl_Archived": "Archivováno",
     "DevDetail_EveandAl_NewDevice": "",
     "DevDetail_EveandAl_NewDevice_Tooltip": "",
     "DevDetail_EveandAl_RandomMAC": "",
@@ -85,10 +85,10 @@
     "DevDetail_EveandAl_Title": "",
     "DevDetail_Events_CheckBox": "",
     "DevDetail_GoToNetworkNode": "",
-    "DevDetail_Icon": "",
+    "DevDetail_Icon": "Ikona",
     "DevDetail_Icon_Descr": "",
-    "DevDetail_Loading": "",
+    "DevDetail_Loading": "Načítání…",
-    "DevDetail_MainInfo_Comments": "",
+    "DevDetail_MainInfo_Comments": "Komentáře",
     "DevDetail_MainInfo_Favorite": "",
     "DevDetail_MainInfo_Group": "",
     "DevDetail_MainInfo_Location": "",

front/php/templates/language/de_de.json

@@ -9,7 +9,7 @@
     "About_Exit": "Abmelden",
     "About_Title": "Netzwerksicherheitsscanner und Benachrichtigungsframework",
     "AppEvents_AppEventProcessed": "Verarbeitet",
-    "AppEvents_DateTimeCreated": "Entdeckt am",
+    "AppEvents_DateTimeCreated": "Protokolliert",
     "AppEvents_Extra": "Extra",
     "AppEvents_GUID": "Anwendungsereignis-GUID",
     "AppEvents_Helper1": "Helfer 1",

front/php/templates/language/en_us.json

@@ -674,7 +674,7 @@
     "Systeminfo_System_Uptime": "Uptime:",
     "Systeminfo_This_Client": "This Client",
     "Systeminfo_USB_Devices": "USB devices",
-    "TICKER_MIGRATE_TO_NETALERTX": "⚠ Old mount locations detected. Follow <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">this guide</a> to migrate to the new <code>/app/config</code> and <code>/app/db</code> folders and the <code>netalertx</code> container.",
+    "TICKER_MIGRATE_TO_NETALERTX": "⚠ Old mount locations detected. Follow <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">this guide</a> to migrate to the new <code>/data/config</code> and <code>/data/db</code> folders and the <code>netalertx</code> container.",
     "TIMEZONE_description": "Time zone to display stats correctly. Find your time zone <a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/List_of_tz_database_time_zones\" rel=\"nofollow\">here</a>.",
     "TIMEZONE_name": "Time zone",
     "UI_DEV_SECTIONS_description": "Select which UI elements to hide in the devices pages.",

front/php/templates/language/es_es.json

@@ -734,7 +734,7 @@
     "Systeminfo_System_Uptime": "Tiempo de actividad:",
     "Systeminfo_This_Client": "Este cliente",
     "Systeminfo_USB_Devices": "Dispositivos USB",
-    "TICKER_MIGRATE_TO_NETALERTX": "⚠ Ubicaciones de montaje antiguas detectadas. Siga <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">esta guía</a> para migrar a las nuevas carpetas <code>/app/config</code> y <code>/app/db</code> y el contenedor <code>netalertx</code>.",
+    "TICKER_MIGRATE_TO_NETALERTX": "⚠ Ubicaciones de montaje antiguas detectadas. Siga <a href=\"https://github.com/jokob-sk/NetAlertX/blob/main/docs/MIGRATION.md\" target=\"_blank\">esta guía</a> para migrar a las nuevas carpetas <code>/data/config</code> y <code>/data/db</code> y el contenedor <code>netalertx</code>.",
     "TIMEZONE_description": "La zona horaria para mostrar las estadísticas correctamente. Encuentra tu zona horaria <a target=\"_blank\" href=\"https://en.wikipedia.org/wiki/List_of_tz_database_time_zones\" rel=\"nofollow\">aquí</a>.",
     "TIMEZONE_name": "Zona horaria",
     "UI_DEV_SECTIONS_description": "Seleccione los elementos de la interfaz de usuario que desea ocultar en las páginas de dispositivos.",

front/php/templates/language/fa_fa.json

@@ -1,6 +1,6 @@
 {
     "API_CUSTOM_SQL_description": "",
-    "API_CUSTOM_SQL_name": "",
+    "API_CUSTOM_SQL_name": "مقصده سفارشی",
     "API_TOKEN_description": "",
     "API_TOKEN_name": "",
     "API_display_name": "",