Merge pull request #1321 from jokob-sk/main

sync

.devcontainer/Dockerfile

@@ -35,7 +35,7 @@ RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev o
 # Create virtual environment owned by root, but readable by everyone else. This makes it easy to copy 
 # into hardened stage without worrying about permissions and keeps image size small. Keeping the commands
 # together makes for a slightly smaller image size.
-RUN pip install -r /tmp/requirements.txt && \
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
     chmod -R u-rwx,g-rwx /opt
 
 # second stage is the main runtime stage with just the minimum required to run the application
@@ -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
 
@@ -69,7 +71,8 @@ ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
 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_CRON=${NETALERTX_LOG}/cron.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
 # System Services configuration files
 ENV ENTRYPOINT_CHECKS=/entrypoint.d
@@ -77,26 +80,28 @@ 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_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
-ENV SYSTEM_SERVICES_ACTIVE_CONFIG=${SYSTEM_NGINX_CONFIG}/conf.active
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.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=/tmp/run
-ENV SYSTEM_SERVICES_RUN=${SYSTEM_SERVICES}/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} ${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
@@ -104,7 +109,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
@@ -114,7 +119,7 @@ ENV LANG=C.UTF-8
 RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap \
     nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
     sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
-    nginx shadow && \
+    nginx supercronic shadow && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
     addgroup -g 20211 ${NETALERTX_GROUP} && \
@@ -128,11 +133,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} .[V]ERSION ${NETALERTX_APP}/.VERSION
+
 # Copy the virtualenv from the builder stage
 COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
@@ -141,20 +150,26 @@ COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 # This is done after the copy of the venv to ensure the venv is in place
 # although it may be quicker to do it before the copy, it keeps the image
 # layers smaller to do it after.
-RUN apk add libcap && \
+RUN if [ -f '.VERSION' ]; then \
+        cp '.VERSION' "${NETALERTX_APP}/.VERSION"; \
+    else \
+        echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/.VERSION"; \
+    fi && \
+    chown 20212:20212 "${NETALERTX_APP}/.VERSION" && \
+    apk add --no-cache libcap && \
     setcap cap_net_raw+ep /bin/busybox && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
     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 $(readlink -f ${VIRTUAL_ENV_BIN}/python) && \
+    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-cron.sh && \
     /bin/sh /build/init-backend.sh && \
     rm -rf /build && \
     apk del libcap && \
-    date +%s > ${NETALERTX_FRONT}/buildtimestamp.txt
+    date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
 
 
 ENTRYPOINT ["/bin/sh","/entrypoint.sh"]
@@ -171,13 +186,15 @@ ENV UMASK=0077
 # AI may claim this is stupid, but it's actually least possible permissions as 
 # read-only user cannot login, cannot sudo, has no write permission, and cannot even
 # read the files it owns. The read-only user is ownership-as-a-lock hardening pattern.
-RUN addgroup -g 20212 ${READ_ONLY_GROUP} && \
+RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
-    adduser -u 20212 -G ${READ_ONLY_GROUP} -D -h /app ${READ_ONLY_USER}
+    adduser -u 20212 -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
 
 
 # reduce permissions to minimum necessary for all NetAlertX files and folders
 # Permissions 005 and 004 are not typos, they enable read-only. Everyone can
 # read the read-only files, and nobody can write to them, even the readonly user.
+
+# hadolint ignore=SC2114
 RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     chmod -R 004 ${READ_ONLY_FOLDERS} && \
     find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
@@ -196,7 +213,7 @@ RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     /srv /media && \
     sed -i "/^\(${READ_ONLY_USER}\|${NETALERTX_USER}\):/!d" /etc/passwd && \
     sed -i "/^\(${READ_ONLY_GROUP}\|${NETALERTX_GROUP}\):/!d" /etc/group && \
-    echo -ne '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+    printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
 
 USER netalertx
 
@@ -211,11 +228,15 @@ 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.
 
+# hadolint ignore=DL3006
 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:/usr/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
@@ -225,17 +246,34 @@ 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 py3-yaml py3-docker-py docker-cli docker-cli-buildx \
+    pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
-    docker-cli-compose
+    docker-cli-compose shellcheck
+
+# Install hadolint (Dockerfile linter)
+RUN curl -L https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 -o /usr/local/bin/hadolint && \
+    chmod +x /usr/local/bin/hadolint
 
 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
-RUN mkdir /workspaces && \
+ENV SHELL=/bin/zsh
-    install -d -o netalertx -g netalertx -m 777 /services/run/logs && \
+
-    install -d -o netalertx -g netalertx -m 777 /app/run/tmp/client_body && \
+RUN mkdir -p /workspaces && \
-    sed -i -e 's|:/app:|:/workspaces:|' /etc/passwd && \
+    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

.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
@@ -44,7 +46,8 @@
   },
 
   "postCreateCommand": {
-      "Install Pip Requirements": "/opt/venv/bin/pip3 install pytest docker debugpy"
+      "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",
@@ -70,15 +73,27 @@
         "esbenp.prettier-vscode",
         "eamodio.gitlens",
         "alexcvzz.vscode-sqlite",
-        "yzhang.markdown-all-in-one",
+        "mkhl.shfmt",
-        "mkhl.shfmt"
+        "charliermarsh.ruff",
+        "ms-python.flake8",
+        "exiasr.hadolint",
+        "timonwong.shellcheck"
       ],
       "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,15 @@
 #   .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.
 
+# hadolint ignore=DL3006
 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:/usr/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
@@ -17,17 +21,34 @@ 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 py3-yaml py3-docker-py docker-cli docker-cli-buildx \
+    pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \
-    docker-cli-compose
+    docker-cli-compose shellcheck
+
+# Install hadolint (Dockerfile linter)
+RUN curl -L https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64 -o /usr/local/bin/hadolint && \
+    chmod +x /usr/local/bin/hadolint
 
 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
-RUN mkdir /workspaces && \
+ENV SHELL=/bin/zsh
-    install -d -o netalertx -g netalertx -m 777 /services/run/logs && \
+
-    install -d -o netalertx -g netalertx -m 777 /app/run/tmp/client_body && \
+RUN mkdir -p /workspaces && \
-    sed -i -e 's|:/app:|:/workspaces:|' /etc/passwd && \
+    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

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

@@ -1,118 +0,0 @@
-# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh
-# Generated from: install/production-filesystem/services/config/nginx/netalertx.conf.template
-
-# Set number of worker processes automatically based on number of CPU cores.
-worker_processes auto;
-
-# Enables the use of JIT for regular expressions to speed-up their processing.
-pcre_jit on;
-
-# Configures default error logger.
-error_log /app/log/nginx-error.log warn;
-
-events {
-	# The maximum number of simultaneous connections that can be opened by
-	# a worker process.
-	worker_connections 1024;
-}
-
-http {
-
-	# Mapping of temp paths for various nginx modules.
-    client_body_temp_path /services/run/tmp/client_body;
-    proxy_temp_path /services/run/tmp/proxy;
-	fastcgi_temp_path /services/run/tmp/fastcgi;
-	uwsgi_temp_path /services/run/tmp/uwsgi;
-	scgi_temp_path /services/run/tmp/scgi;
-	
-	# Includes mapping of file name extensions to MIME types of responses
-	# and defines the default type.
-	include /services/config/nginx/mime.types;
-	default_type application/octet-stream;
-
-	# Name servers used to resolve names of upstream servers into addresses.
-	# It's also needed when using tcpsocket and udpsocket in Lua modules.
-	#resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001];
-
-	# Don't tell nginx version to the clients. Default is 'on'.
-	server_tokens off;
-
-	# Specifies the maximum accepted body size of a client request, as
-	# indicated by the request header Content-Length. If the stated content
-	# length is greater than this size, then the client receives the HTTP
-	# error code 413. Set to 0 to disable. Default is '1m'.
-	client_max_body_size 1m;
-
-	# Sendfile copies data between one FD and other from within the kernel,
-	# which is more efficient than read() + write(). Default is off.
-	sendfile on;
-
-	# Causes nginx to attempt to send its HTTP response head in one packet,
-	# instead of using partial frames. Default is 'off'.
-	tcp_nopush on;
-
-
-	# Enables the specified protocols. Default is TLSv1 TLSv1.1 TLSv1.2.
-	# TIP: If you're not obligated to support ancient clients, remove TLSv1.1.
-	ssl_protocols TLSv1.2 TLSv1.3;
-
-	# Path of the file with Diffie-Hellman parameters for EDH ciphers.
-	# TIP: Generate with: `openssl dhparam -out /etc/ssl/nginx/dh2048.pem 2048`
-	#ssl_dhparam /etc/ssl/nginx/dh2048.pem;
-
-	# Specifies that our cipher suits should be preferred over client ciphers.
-	# Default is 'off'.
-	ssl_prefer_server_ciphers on;
-
-	# Enables a shared SSL cache with size that can hold around 8000 sessions.
-	# Default is 'none'.
-	ssl_session_cache shared:SSL:2m;
-
-	# Specifies a time during which a client may reuse the session parameters.
-	# Default is '5m'.
-	ssl_session_timeout 1h;
-
-	# Disable TLS session tickets (they are insecure). Default is 'on'.
-	ssl_session_tickets off;
-
-
-	# Enable gzipping of responses.
-	gzip on;
-
-	# Set the Vary HTTP header as defined in the RFC 2616. Default is 'off'.
-	gzip_vary on;
-
-
-    # Specifies the main log format.
-    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
-	    '$status $body_bytes_sent "$http_referer" '
-	    '"$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;
-
-
-	# Virtual host config
-    server {
-        listen 0.0.0.0:20211 default_server;
-		large_client_header_buffers 4 16k;
-        root /app/front;
-        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;
-            include /services/config/nginx/fastcgi_params;
-			fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-			fastcgi_param SCRIPT_NAME $fastcgi_script_name;
-
-            fastcgi_param PHP_VALUE "xdebug.remote_enable=1";
-            fastcgi_connect_timeout 75;
-            fastcgi_send_timeout 600;
-            fastcgi_read_timeout 600;
-        }
-    }
-}

.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/generate-configs.sh

@@ -7,56 +7,28 @@
 # the final .devcontainer/Dockerfile used by the devcontainer.
 
 echo "Generating .devcontainer/Dockerfile"
-SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+SCRIPT_PATH=$(set -- "$0"; dirname -- "$1")
+SCRIPT_DIR=$(cd "$SCRIPT_PATH" && pwd -P)
 DEVCONTAINER_DIR="${SCRIPT_DIR%/scripts}"
 ROOT_DIR="${DEVCONTAINER_DIR%/.devcontainer}"
 
 OUT_FILE="${DEVCONTAINER_DIR}/Dockerfile"
 
-echo "Adding base Dockerfile from $ROOT_DIR..." 
+echo "Adding base Dockerfile from $ROOT_DIR and merging to devcontainer-Dockerfile" 
+{
 
-echo "# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh" > "$OUT_FILE"
+echo "# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh"
-echo "" >> "$OUT_FILE"
+echo ""
-echo "# ---/Dockerfile---" >> "$OUT_FILE"
+echo "# ---/Dockerfile---" 
 
-cat "${ROOT_DIR}/Dockerfile" >> "$OUT_FILE"
+cat "${ROOT_DIR}/Dockerfile" 
 
-echo "" >> "$OUT_FILE"
+echo ""
-echo "# ---/resources/devcontainer-Dockerfile---" >> "$OUT_FILE"
+echo "# ---/resources/devcontainer-Dockerfile---"
-echo "" >> "$OUT_FILE"
+echo ""
+cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile"
+} > "$OUT_FILE"
 
-echo "Adding devcontainer-Dockerfile from $DEVCONTAINER_DIR/resources..."
+echo "Generated $OUT_FILE using root dir $ROOT_DIR"
-cat "${DEVCONTAINER_DIR}/resources/devcontainer-Dockerfile" >> "$OUT_FILE"
-
-echo "Generated $OUT_FILE using root dir $ROOT_DIR" >&2
-
-# Generate devcontainer nginx config from production template
-echo "Generating devcontainer nginx config"
-NGINX_TEMPLATE="${ROOT_DIR}/install/production-filesystem/services/config/nginx/netalertx.conf.template"
-NGINX_OUT="${DEVCONTAINER_DIR}/resources/devcontainer-overlay/services/config/nginx/netalertx.conf.template"
-
-# Create output directory if it doesn't exist
-mkdir -p "$(dirname "$NGINX_OUT")"
-
-# Start with header comment
-cat > "$NGINX_OUT" << 'EOF'
-# DO NOT MODIFY THIS FILE DIRECTLY. IT IS AUTO-GENERATED BY .devcontainer/scripts/generate-configs.sh
-# Generated from: install/production-filesystem/services/config/nginx/netalertx.conf.template
-
-EOF
-
-# Process the template: replace listen directive and inject Xdebug params
-sed 's/${LISTEN_ADDR}:${PORT}/0.0.0.0:20211/g' "$NGINX_TEMPLATE" | \
-awk '
-/fastcgi_param SCRIPT_NAME \$fastcgi_script_name;/ {
-    print $0
-	print ""
-    print "            fastcgi_param PHP_VALUE \"xdebug.remote_enable=1\";"
-    next
-}
-{ print }
-' >> "$NGINX_OUT"
-
-echo "Generated $NGINX_OUT from $NGINX_TEMPLATE" >&2
 
 echo "Done."

.devcontainer/scripts/setup.sh

@@ -1,184 +1,104 @@
 #!/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
-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_CRON
+  LOG_REPORT_OUTPUT_TXT
+  LOG_REPORT_OUTPUT_HTML
+  LOG_REPORT_OUTPUT_JSON
+  LOG_DB_IS_LOCKED
+  LOG_NGINX_ERROR
+)
 
-ensure_docker_socket_access() {
+sudo chmod 666 /var/run/docker.sock 2>/dev/null || true
-  local socket="/var/run/docker.sock"
+sudo chown "$(id -u)":"$(id -g)" /workspaces
-  if [ ! -S "${socket}" ]; then
+sudo chmod 755 /workspaces
-    echo "docker socket not present; skipping docker group configuration"
-    return
-  fi
 
-  local sock_gid
+killall php-fpm83 nginx crond python3 2>/dev/null || true
-  sock_gid=$(stat -c '%g' "${socket}" 2>/dev/null || true)
-  if [ -z "${sock_gid}" ]; then
-    echo "unable to determine docker socket gid; skipping docker group configuration"
-    return
-  fi
 
-  local group_entry=""
+# Mount ramdisks for volatile data
-  if command -v getent >/dev/null 2>&1; then
+sudo mount -t tmpfs -o size=100m,mode=0777 tmpfs /tmp/log 2>/dev/null || true
-    group_entry=$(getent group "${sock_gid}" 2>/dev/null || true)
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/api 2>/dev/null || true
-  else
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/run 2>/dev/null || true
-    group_entry=$(grep -E ":${sock_gid}:" /etc/group 2>/dev/null || true)
+sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/nginx 2>/dev/null || true
-  fi
 
-  local group_name=""
+sudo chmod 777 /tmp/log /tmp/api /tmp/run /tmp/nginx
-  if [ -n "${group_entry}" ]; then
-    group_name=$(echo "${group_entry}" | cut -d: -f1)
-  else
-    group_name="docker-host"
-    sudo addgroup -g "${sock_gid}" "${group_name}" 2>/dev/null || group_name=$(grep -E ":${sock_gid}:" /etc/group | head -n1 | cut -d: -f1)
-  fi
-
-  if [ -z "${group_name}" ]; then
-    echo "failed to resolve group for docker socket gid ${sock_gid}; skipping docker group configuration"
-    return
-  fi
-
-  if ! id -nG netalertx | tr ' ' '\n' | grep -qx "${group_name}"; then
-    sudo addgroup netalertx "${group_name}" 2>/dev/null || true
-  fi
-}
-
-
-main() {
-    echo "=== NetAlertX Development Container Setup ==="
-    killall php-fpm83 nginx crond python3 2>/dev/null
-    sleep 1
-    echo "Setting up ${SOURCE_DIR}..."
-    ensure_docker_socket_access
-    sudo chown $(id -u):$(id -g) /workspaces
-    sudo chmod 755 /workspaces
-    configure_source
-    
-    echo "--- Starting Development Services ---"
-    configure_php
-
-
-    start_services
-}
-
-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
-	sudo chmod 777 /opt/venv/lib/python3.12/site-packages/ && \
-  sudo chmod 005 /opt/venv/lib/python3.12/site-packages/
-	sudo chmod 666 /var/run/docker.sock
-
-	echo "      -> Updating build timestamp"
-	date +%s > ${NETALERTX_FRONT}/buildtimestamp.txt
-    
-}
-
-# 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 /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}" \
+  "${SYSTEM_SERVICES_RUN_TMP}" \
+  "/tmp/nginx/client_body" \
+  "/tmp/nginx/proxy" \
+  "/tmp/nginx/fastcgi" \
+  "/tmp/nginx/uwsgi" \
+  "/tmp/nginx/scgi"; do
+  sudo install -d -m 777 "${dir}"
+done
+
+
+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

@@ -44,9 +44,9 @@ body:
     required: false
 - type: textarea
   attributes:
-    label: app.conf
+    label: Relevant `app.conf` settings 
     description: |
-      Paste your `app.conf` (remove personal info)    
+      Paste relevant `app.conf`settings (remove sensitive info)    
     render: python
   validations:
     required: false
@@ -55,7 +55,7 @@ body:
     label: docker-compose.yml
     description: |
       Paste your `docker-compose.yml`    
-    render: python
+    render: yaml
   validations:
     required: false
 - type: dropdown
@@ -70,21 +70,37 @@ 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
+    label: Relevant `app.log` section
+    value: |
+        ```
+          PASTE LOG HERE. Using the triple backticks preserves format. 
+        ```
     description: |
       Logs with debug enabled (https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) ⚠
       ***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.
+    value: |
-      required: true
+        ```
+          PASTE DOCKER LOG HERE. Using the triple backticks preserves format. 
+        ```
+  validations:
+    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.
@@ -72,3 +83,9 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, `
 - Be sure to offer choices when appropriate.
 - Always understand the intent of the user's request and undo/redo as needed.
 - Above all, use the simplest possible code that meets the need so it can be easily audited and maintained.
+- Always leave logging enabled. If there is a possiblity it will be difficult to debug with current logging, add more logging.
+- Always run the testFailure tool before executing any tests to gather current failure information and avoid redundant runs.
+- Always prioritize using the appropriate tools in the environment first. As an example if a test is failing use `testFailure` then `runTests`. Never `runTests` first. 
+- Docker tests take an extremely long time to run.  Avoid changes to docker or tests until you've examined the exisiting testFailures and runTests results.
+- Environment tools are designed specifically for your use in this project and running them in this order will give you the best results. 
+

.github/workflows/code_checks.yml

@@ -21,7 +21,8 @@ jobs:
         run: |
           echo "🔍 Checking for incorrect absolute '/php/' URLs (should be 'php/' or './php/')..."
 
-          MATCHES=$(grep -rE "['\"]\/php\/" --include=\*.{js,php,html} ./front | grep -E "\.get|\.post|\.ajax|fetch|url\s*:") || true
+          MATCHES=$(grep -rE "['\"]/php/" --include=\*.{js,php,html} ./front \
+            | grep -E "\.get|\.post|\.ajax|fetch|url\s*:") || true
 
           if [ -n "$MATCHES" ]; then
             echo "$MATCHES"
@@ -39,3 +40,60 @@ jobs:
           echo "🔍 Checking Python syntax..."
           find . -name "*.py" -print0 | xargs -0 -n1 python3 -m py_compile
 
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install linting tools
+        run: |
+          # Python linting
+          pip install flake8
+          # Docker linting
+          wget -O /tmp/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
+          chmod +x /tmp/hadolint
+          # PHP and shellcheck for syntax checking
+          sudo apt-get update && sudo apt-get install -y php-cli shellcheck
+
+      - name: Shell check
+        continue-on-error: true
+        run: |
+          echo "🔍 Checking shell scripts..."
+          find . -name "*.sh" -exec shellcheck {} \;
+
+      - name: Python lint
+        continue-on-error: true
+        run: |
+          echo "🔍 Linting Python code..."
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: PHP check
+        continue-on-error: true
+        run: |
+          echo "🔍 Checking PHP syntax..."
+          find . -name "*.php" -exec php -l {} \;
+
+      - name: Docker lint
+        continue-on-error: true
+        run: |
+          echo "🔍 Linting Dockerfiles..."
+          /tmp/hadolint --config .hadolint.yaml Dockerfile* || true
+
+  docker-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run Docker-based tests
+        run: |
+          echo "🐳 Running Docker-based tests..."
+          chmod +x ./test/docker_tests/run_docker_tests.sh
+          ./test/docker_tests/run_docker_tests.sh

.github/workflows/docker_dev.yml

@@ -3,12 +3,12 @@ name: docker
 on:
   push:
     branches:
-      - next_release
+      - main
     tags:
       - '*.*.*'
   pull_request:
     branches:
-      - next_release
+      - main
 
 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}}
@@ -72,7 +83,7 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6

.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,51 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # --- Previous approach Get release version from tag
       - name: Set up dynamic build ARGs
         id: getargs
         run: echo "version=$(cat ./stable/VERSION)" >> $GITHUB_OUTPUT
 
       - name: Get release version
-        id: get_version
+        id: get_version_prev
         run: echo "::set-output name=version::${GITHUB_REF#refs/tags/}"
 
       - name: Create .VERSION file
-        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
+        run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION_PREV
 
+      # --- Get release version from tag
+      - name: Get release version
+        id: get_version
+        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
+
+      # --- 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:
@@ -74,13 +84,12 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3
+        uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6
           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

@@ -11,6 +11,7 @@ nohup.out
 config/*
 .ash_history
 .VERSION
+.VERSION_PREV
 config/pialert.conf
 config/app.conf
 db/*

.hadolint.yaml

@@ -0,0 +1,2 @@
+ignored:
+  - DL3018

.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,29 +169,55 @@
       }
     },
     {
-      "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'",
-      "options": {
+      "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.",
-        "cwd": "/workspaces/NetAlertX/.devcontainer/scripts"
-      },
       "presentation": {
         "echo": true,
         "reveal": "always",
         "panel": "shared",
-        "showReuseMessage": false
+        "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": "output",
+        "id": "database",
-        "color": "terminal.ansiBlue"
+        "color": "terminal.ansiRed"
       }
-    }
+    },
-    ,
     {
-      "label": "[Any] Build Unit Test Docker image",
+      "label": "Build & Launch Prodcution Docker Container",
       "type": "shell",
-      "command": "docker buildx build -t netalertx-test . && echo '🧪 Unit Test Docker image built: netalertx-test'",
+      "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"
+      },
       "presentation": {
         "echo": true,
         "reveal": "always",
@@ -177,7 +230,7 @@
         "isDefault": false
       },
       "icon": {
-        "id": "beaker",
+        "id": "package",
         "color": "terminal.ansiBlue"
       }
     }

Dockerfile

@@ -32,7 +32,7 @@ RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev o
 # Create virtual environment owned by root, but readable by everyone else. This makes it easy to copy
 # into hardened stage without worrying about permissions and keeps image size small. Keeping the commands
 # together makes for a slightly smaller image size.
-RUN pip install -r /tmp/requirements.txt && \
+RUN pip install --no-cache-dir -r /tmp/requirements.txt && \
     chmod -R u-rwx,g-rwx /opt
 
 # second stage is the main runtime stage with just the minimum required to run the application
@@ -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
 
@@ -66,7 +68,8 @@ ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
 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_CRON=${NETALERTX_LOG}/cron.log
+ENV LOG_NGINX_ERROR=${NETALERTX_LOG}/nginx-error.log
 
 # System Services configuration files
 ENV ENTRYPOINT_CHECKS=/entrypoint.d
@@ -74,26 +77,28 @@ 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_NGINX_CONFIG_TEMPLATE=${SYSTEM_NGINX_CONFIG}/netalertx.conf.template
-ENV SYSTEM_SERVICES_ACTIVE_CONFIG=${SYSTEM_NGINX_CONFIG}/conf.active
+ENV SYSTEM_SERVICES_CONFIG_CRON=${SYSTEM_SERVICES_CONFIG}/cron
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG=/tmp/nginx/active-config
+ENV SYSTEM_SERVICES_ACTIVE_CONFIG_FILE=${SYSTEM_SERVICES_ACTIVE_CONFIG}/nginx.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=/tmp/run
-ENV SYSTEM_SERVICES_RUN=${SYSTEM_SERVICES}/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} ${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_NGINX_CONFIG}"
+                       ${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
@@ -101,7 +106,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
@@ -111,7 +116,7 @@ ENV LANG=C.UTF-8
 RUN apk add --no-cache bash mtr libbsd zip lsblk tzdata curl arp-scan iproute2 iproute2-ss nmap \
     nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates \
     sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session python3 envsubst \
-    nginx shadow && \
+    nginx supercronic shadow && \
     rm -Rf /var/cache/apk/*  && \
     rm -Rf /etc/nginx && \
     addgroup -g 20211 ${NETALERTX_GROUP} && \
@@ -125,11 +130,16 @@ 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} .[V]ERSION ${NETALERTX_APP}/.VERSION
+COPY --chown=${NETALERTX_USER}:${NETALERTX_GROUP} .[V]ERSION ${NETALERTX_APP}/.VERSION_PREV
+
 # Copy the virtualenv from the builder stage
 COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
@@ -138,20 +148,26 @@ COPY --from=builder --chown=20212:20212 ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 # This is done after the copy of the venv to ensure the venv is in place
 # although it may be quicker to do it before the copy, it keeps the image
 # layers smaller to do it after.
-RUN apk add libcap && \
+RUN for vfile in .VERSION .VERSION_PREV; do \
+        if [ ! -f "${NETALERTX_APP}/${vfile}" ]; then \
+            echo "DEVELOPMENT 00000000" > "${NETALERTX_APP}/${vfile}"; \
+        fi; \
+        chown 20212:20212 "${NETALERTX_APP}/${vfile}"; \
+    done && \
+    apk add --no-cache libcap && \
     setcap cap_net_raw+ep /bin/busybox && \
     setcap cap_net_raw,cap_net_admin+eip /usr/bin/nmap && \
     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 $(readlink -f ${VIRTUAL_ENV_BIN}/python) && \
+    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-cron.sh && \
     /bin/sh /build/init-backend.sh && \
     rm -rf /build && \
     apk del libcap && \
-    date +%s > ${NETALERTX_FRONT}/buildtimestamp.txt
+    date +%s > "${NETALERTX_FRONT}/buildtimestamp.txt"
 
 
 ENTRYPOINT ["/bin/sh","/entrypoint.sh"]
@@ -168,13 +184,15 @@ ENV UMASK=0077
 # AI may claim this is stupid, but it's actually least possible permissions as
 # read-only user cannot login, cannot sudo, has no write permission, and cannot even
 # read the files it owns. The read-only user is ownership-as-a-lock hardening pattern.
-RUN addgroup -g 20212 ${READ_ONLY_GROUP} && \
+RUN addgroup -g 20212 "${READ_ONLY_GROUP}" && \
-    adduser -u 20212 -G ${READ_ONLY_GROUP} -D -h /app ${READ_ONLY_USER}
+    adduser -u 20212 -G "${READ_ONLY_GROUP}" -D -h /app "${READ_ONLY_USER}"
 
 
 # reduce permissions to minimum necessary for all NetAlertX files and folders
 # Permissions 005 and 004 are not typos, they enable read-only. Everyone can
 # read the read-only files, and nobody can write to them, even the readonly user.
+
+# hadolint ignore=SC2114
 RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     chmod -R 004 ${READ_ONLY_FOLDERS} && \
     find ${READ_ONLY_FOLDERS} -type d -exec chmod 005 {} + && \
@@ -193,7 +211,7 @@ RUN chown -R ${READ_ONLY_USER}:${READ_ONLY_GROUP} ${READ_ONLY_FOLDERS} && \
     /srv /media && \
     sed -i "/^\(${READ_ONLY_USER}\|${NETALERTX_USER}\):/!d" /etc/passwd && \
     sed -i "/^\(${READ_ONLY_GROUP}\|${NETALERTX_GROUP}\):/!d" /etc/group && \
-    echo -ne '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
+    printf '#!/bin/sh\n"$@"\n' > /usr/bin/sudo && chmod +x /usr/bin/sudo
 
 USER netalertx
 

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
@@ -71,18 +72,20 @@ ENV LOG_APP_PHP_ERRORS=${NETALERTX_LOG}/app.php_errors.log
 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_CRON=${NETALERTX_LOG}/cron.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
@@ -129,25 +132,29 @@ COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
 
 
 # ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.debian.sh file as well ❗ 
-RUN apt update && apt-get install -y \
+# hadolint ignore=DL3008,DL3027
+RUN apt-get update && apt-get install -y --no-install-recommends \
     tini snmp ca-certificates curl libwww-perl arp-scan sudo gettext-base \
     nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools  \
     python3 python3-dev iproute2 nmap python3-pip zip git systemctl usbutils traceroute nbtscan openrc \
-    busybox nginx nginx-core mtr python3-venv
+    busybox nginx nginx-core mtr python3-venv && \
+    rm -rf /var/lib/apt/lists/*
 
 # While php8.3 is in debian bookworm repos, php-fpm is not included so we need to add sury.org repo
 # (Ondřej Surý maintains php packages for debian. This is temp until debian includes php-fpm in their
 # repos. Likely it will be in Debian Trixie.).  This keeps the image up-to-date with the alpine version.
+# hadolint ignore=DL3008
 RUN apt-get install -y --no-install-recommends \
     apt-transport-https \
     ca-certificates \
     lsb-release \
     wget && \
-    wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg && \
+    wget -q -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg && \
     echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list && \
     apt-get update && \
-    apt-get install -y php8.3-fpm php8.3-cli php8.3-sqlite3 php8.3-common php8.3-curl php8.3-cgi && \
+    apt-get install -y --no-install-recommends php8.3-fpm php8.3-cli php8.3-sqlite3 php8.3-common php8.3-curl php8.3-cgi && \
-    ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 # make it compatible with alpine version
+    ln -s /usr/sbin/php-fpm8.3 /usr/sbin/php-fpm83 && \
+    rm -rf /var/lib/apt/lists/* # make it compatible with alpine version
 
 # Setup virtual python environment and use pip3 to install packages
 RUN python3 -m venv ${VIRTUAL_ENV} && \

README.md

@@ -6,7 +6,7 @@
 
 # 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
 
@@ -33,19 +33,25 @@ Get visibility of what's going on on your WIFI/LAN network and enable presence d
 
 ## 🚀 Quick Start
 
+> [!WARNING]
+> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
+
 Start NetAlertX in seconds with Docker:
 
 ```bash
-docker run -d --rm --network=host \
+docker run -d \
-  -v local_path/config:/app/config \
+  --network=host \
-  -v local_path/db:/app/db \
+  --restart unless-stopped \
-  --mount type=tmpfs,target=/app/api \
+  -v /local_data_dir:/data \
-  -e PUID=200 -e PGID=300 \
+  -v /etc/localtime:/etc/localtime:ro \
-  -e TZ=Europe/Berlin \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   -e PORT=20211 \
+  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
   ghcr.io/jokob-sk/netalertx:latest
 ```
 
+Note: Your `/local_data_dir` should contain a `config` and `db` folder.
+
 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
@@ -61,7 +67,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]
@@ -103,7 +109,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)
@@ -140,7 +146,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

back/cron_script.sh

@@ -1,14 +1,17 @@
 #!/bin/bash
 export INSTALL_DIR=/app
 
-LOG_FILE="${INSTALL_DIR}/log/execution_queue.log"
+if [ -f "${LOG_EXECUTION_QUEUE}" ] && grep -q "cron_restart_backend" "${LOG_EXECUTION_QUEUE}"; then
-
+  echo "$(date): Restarting backend triggered by cron_restart_backend"
-# Check if there are any entries with cron_restart_backend
+  killall python3 || echo "killall python3 failed or no process found"
-if grep -q "cron_restart_backend" "$LOG_FILE"; then
+  sleep 2
-  # Restart python application using s6
+  /services/start-backend.sh &
-  s6-svc -r /var/run/s6-rc/servicedirs/netalertx
-  echo 'done'
 
   # Remove all lines containing cron_restart_backend from the log file
-  sed -i '/cron_restart_backend/d' "$LOG_FILE"
+  # Atomic replacement with temp file. grep returns 1 if no lines selected (file becomes empty), which is valid here.
+  grep -v "cron_restart_backend" "${LOG_EXECUTION_QUEUE}" > "${LOG_EXECUTION_QUEUE}.tmp"
+  RC=$?
+  if [ $RC -eq 0 ] || [ $RC -eq 1 ]; then
+    mv "${LOG_EXECUTION_QUEUE}.tmp" "${LOG_EXECUTION_QUEUE}"
+  fi
 fi

db/.gitignore

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

docker-compose.yml

@@ -17,53 +17,38 @@ services:
 
     volumes:
 
-      - type: volume                                # Persistent Docker-managed Named Volume for storage of config files
+      - type: volume                                # Persistent Docker-managed Named Volume for storage
-        source: netalertx_config                    # the default name of the volume is netalertx_config
+        source: netalertx_data                      # the default name of the volume is netalertx_data
-        target: /app/config                         # inside the container mounted to /app/config
+        target: /data                               # consolidated configuration and database storage
         read_only: false                            # writable volume
 
-    # Example custom local folder called /home/user/netalertx_config
+    # Example custom local folder called /home/user/netalertx_data
     # - type: bind
-    #   source: /home/user/netalertx_config
+    #   source: /home/user/netalertx_data
-    #   target: /app/config
+    #   target: /data
     #   read_only: false
     # ... or use the alternative format
-    # - /home/user/netalertx_config:/app/config:rw
+    # - /home/user/netalertx_data:/data:rw
-
-      - type: volume
-        source: netalertx_db
-        target: /app/db
-        read_only: false
 
       - type: bind                           # Bind mount for timezone consistency
         source: /etc/localtime
         target: /etc/localtime
         read_only: true
 
-      # Use a custom Enterprise-configured nginx config for ldap or other settings
+  # Use a custom Enterprise-configured nginx config for ldap or other settings
-      # - /custom-enterprise.conf:/services/config/nginx/conf.active/netalertx.conf:ro
+  # - /custom-enterprise.conf:/tmp/nginx/active-config/netalertx.conf:ro
 
       # Test your plugin on the production container
       # - /path/on/host:/app/front/plugins/custom
 
-      # Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
+  # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
-      # - /path/on/host/log:/app/log
+  # - /path/on/host/log:/tmp/log
 
-    # Tempfs mounts for writable directories in a read-only container and improve system performance
+    # tmpfs mounts for writable directories in a read-only container and improve system performance
-    # All mounts have noexec,nosuid,nodev for security purposes no devices, no suid/sgid and no execution of binaries
+    # All writes now live under /tmp/* subdirectories which are created dynamically by entrypoint.d scripts
-    # async where possible for performance, sync where required for correctness
     # 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: ${LISTEN_ADDR:-0.0.0.0}                      # Listen for connections on all interfaces
@@ -86,6 +71,5 @@ services:
     # Always restart the container unless explicitly stopped
     restart: unless-stopped
 
-volumes:                        # Persistent volumes for configuration and database storage
+volumes:                        # Persistent volume for configuration and database storage
-  netalertx_config:             # Configuration files
+  netalertx_data:
-  netalertx_db:                 # Database files

docs/API.md

@@ -1,4 +1,4 @@
-# NetAlertX API Documentation
+# API Documentation
 
 This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted. For example, to authorize a GraphQL request, you need to use a `Authorization: Bearer API_TOKEN` header as per example below:
 
@@ -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

@@ -52,7 +52,7 @@ query GetDevices($options: PageQueryOptionsInput) {
 }
 ```
 
-See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
+See also: [Debugging GraphQL issues](./DEBUG_API_SERVER.md)
 
 ### `curl` Command
 
@@ -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,7 +1,7 @@
 # Backing Things Up
 
 > [!NOTE]
-> To back up 99% of your configuration, back up at least the `/app/config` folder.
+> To back up 99% of your configuration, back up at least the `/data/config` folder.
 > 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.
 
 ---
@@ -25,7 +25,7 @@ Understanding where your data is stored helps you plan your backup strategy.
 
 ### Core Configuration
 
-Stored in `/app/config/app.conf`.
+Stored in `/data/config/app.conf`.
 This includes settings for:
 
 * Notifications
@@ -37,7 +37,7 @@ This includes settings for:
 
 ### Device Data
 
-Stored in `/app/config/devices_<timestamp>.csv` or `/app/config/devices.csv`, created by the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup).
+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).
 Contains:
 
 * Device names, icons, and categories
@@ -46,7 +46,7 @@ Contains:
 
 ### Historical Data
 
-Stored in `/app/db/app.db` (see [Database Overview](./DATABASE.md)).
+Stored in `/data/db/app.db` (see [Database Overview](./DATABASE.md)).
 Contains:
 
 * Plugin data and historical entries
@@ -77,13 +77,13 @@ You can also download the `app.conf` and `devices.csv` files from the **Maintena
 
 ### 💾 What to Back Up
 
-* `/app/db/app.db` (uncorrupted)
+* `/data/db/app.db` (uncorrupted)
-* `/app/config/app.conf`
+* `/data/config/app.conf`
-* `/app/config/workflows.json`
+* `/data/config/workflows.json`
 
 ### 📥 How to Restore
 
-Map these files into your container as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
+Map these files into your container as described in the [Setup documentation](./DOCKER_INSTALLATION.md).
 
 ---
 
@@ -93,14 +93,14 @@ Map these files into your container as described in the [Setup documentation](ht
 
 ### 💾 What to Back Up
 
-* `/app/config/app.conf`
+* `/data/config/app.conf`
-* `/app/config/workflows.json`
+* `/data/config/workflows.json`
-* `/app/config/devices_<timestamp>.csv` (rename to `devices.csv` during restore)
+* `/data/config/devices_<timestamp>.csv` (rename to `devices.csv` during restore)
 
 ### 📥 How to Restore
 
-1. Copy `app.conf` and `workflows.json` into `/app/config/`
+1. Copy `app.conf` and `workflows.json` into `/data/config/`
-2. Rename and place `devices_<timestamp>.csv` → `/app/config/devices.csv`
+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.
@@ -157,6 +157,6 @@ For users running NetAlertX via Docker, you can back up or restore directly from
 
 ## Summary
 
-* Back up `/app/config` for configuration and devices; `/app/db` for history
+* 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/COMMON_ISSUES.md

@@ -1,57 +1,114 @@
-### Loading...
+# Troubleshooting Common Issues
 
-Often if the application is misconfigured the `Loading...` dialog is continuously displayed. This is most likely caused by the backed failing to start. The **Maintenance -> Logs** section should give you more details on what's happening. If there is no exception, check the Portainer log, or start the container in the foreground (without the `-d` parameter) to observe any exceptions. It's advisable to enable `trace` or `debug`. Check the [Debug tips](./DEBUG_TIPS.md) on detailed instructions. 
+> [!TIP]
+> Before troubleshooting, ensure you have set the correct [Debugging and LOG_LEVEL](./DEBUG_TIPS.md).
 
-### Incorrect SCAN_SUBNETS
+---
 
-One of the most common issues is not configuring `SCAN_SUBNETS` correctly. If this setting is misconfigured you will only see one or two devices in your devices list after a scan. Please read the [subnets docs](./SUBNETS.md) carefully to resolve this.
+## Docker Container Doesn't Start
 
-### Duplicate devices and notifications
+Initial setup issues are often caused by **missing permissions** or **incorrectly mapped volumes**. Always double-check your `docker run` or `docker-compose.yml` against the [official setup guide](./DOCKER_INSTALLATION.md) before proceeding.
-
-The app uses the MAC address as an unique identifier for devices. If a new MAC is detected a new device is added to the application and corresponding notifications are triggered. This means that if the MAC of an existing device changes, the device will be logged as a new device. You can usually prevent this from happening by changing the device configuration (in Android, iOS, or Windows) for your network. See the [Random Macs](./RANDOM_MAC.md) guide for details. 
 
 ### Permissions
 
-Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly.
+Make sure your [file permissions](./FILE_PERMISSIONS.md) are correctly set:
 
-* 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 you encounter AJAX errors, cannot write to the database, or see an empty screen, check that permissions are correct and review 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 fix permission issues with the database, update the owner and group of `app.db` as described in the [File Permissions guide](./FILE_PERMISSIONS.md).
-* 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)
 
-### Container restarts / crashes
+### Container Restarts / Crashes
 
-* Check the logs for details. Often a required setting for a notification method is missing. 
+* Check the logs for details. Often, required settings are missing.
+* For more detailed troubleshooting, see [Debug and Troubleshooting Tips](./DEBUG_TIPS.md).
+* To observe errors directly, run the container in the foreground instead of `-d`:
 
-### unable to resolve host
+```bash
+docker run --rm -it <your_image>
+```
 
-* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See the [subnets docs for details](./SUBNETS.md).  
+---
 
-### Invalid JSON
+## Docker Container Starts, But the Application Misbehaves
 
-Check the [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) docs on how to proceed.
+If the container starts but the app shows unexpected behavior, the cause is often **data corruption**, **incorrect configuration**, or **unexpected input data**.
 
-### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 
+### Continuous "Loading..." Screen
 
-> sudo: unexpected child termination condition: 0
+A misconfigured application may display a persistent `Loading...` dialog. This is usually caused by the backend failing to start.
 
-Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581)
+**Steps to troubleshoot:**
+
+1. Check **Maintenance → Logs** for exceptions.
+2. If no exception is visible, check the Portainer logs.
+3. Start the container in the foreground to observe exceptions.
+4. Enable `trace` or `debug` logging for detailed output (see [Debug Tips](./DEBUG_TIPS.md)).
+5. Verify that `GRAPHQL_PORT` is correctly configured.
+6. Check browser logs (press `F12`):
+
+   * **Console tab** → refresh the page
+   * **Network tab** → refresh the page
+
+If you are unsure how to resolve errors, provide screenshots or log excerpts in your issue report or Discord discussion.
+
+---
+
+### Common Configuration Issues
+
+#### Incorrect `SCAN_SUBNETS`
+
+If `SCAN_SUBNETS` is misconfigured, you may see only a few devices in your device list after a scan. See the [Subnets Documentation](./SUBNETS.md) for proper configuration.
+
+#### Duplicate Devices and Notifications
+
+* Devices are identified by their **MAC address**.
+* If a device's MAC changes, it will be treated as a new device, triggering notifications.
+* Prevent this by adjusting your device configuration for Android, iOS, or Windows. See the [Random MACs Guide](./RANDOM_MAC.md).
+
+#### Unable to Resolve Host
+
+* Ensure `SCAN_SUBNETS` uses the correct mask and `--interface`.
+* Refer to the [Subnets Documentation](./SUBNETS.md) for detailed guidance.
+
+#### Invalid JSON Errors
+
+* Follow the steps in [Invalid JSON Errors Debug Help](./DEBUG_INVALID_JSON.md).
+
+#### Sudo Execution Fails (e.g., on arpscan on Raspberry Pi 4)
+
+Error:
 
 ```
+sudo: unexpected child termination condition: 0
+```
+
+**Resolution**:
+
+```bash
 wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb
 sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb
 ```
 
-The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url.
+> ⚠️ The link may break over time. Check [Debian Packages](https://packages.debian.org/sid/armhf/libseccomp2/download) for the latest version.
 
-### Only Router and own device show up
+#### Only Router and Own Device Show Up
 
-Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your device/NAS has multiple ethernet ports, you probably need to change `eth0` to something else.
+* Verify the subnet and interface in `SCAN_SUBNETS`.
+* On devices with multiple Ethernet ports, you may need to change `eth0` to the correct interface.
 
-### Losing my settings and devices after an update
+#### Losing Settings or Devices After 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.
+* Ensure `/data/db` and `/data/config` are mapped to persistent storage.
+* Without persistent volumes, these folders are recreated on every update.
+* See [Docker Volumes Setup](./DOCKER_COMPOSE.md) for proper configuration.
 
+#### Application Performance Issues
 
-### The application is slow
+Slowness can be caused by:
+
+* Incorrect settings (causing app restarts) → check `app.log`.
+* Too many background processes → disable unnecessary scanners.
+* Long scans → limit the number of scanned devices.
+* Excessive disk operations or failing maintenance plugins.
+
+> See [Performance Tips](./PERFORMANCE.md) for detailed optimization steps.
 
-Slowness is usually caused by incorrect settings (the app might restart, so check the `app.log`), too many background processes (disable unnecessary scanners), too long scans (limit the number of scanned devices), too many disk operations, or some maintenance plugins might have failed. See the [Performance tips](./PERFORMANCE.md) docs for details.

docs/DEBUG_API_SERVER.md

@@ -12,7 +12,7 @@ As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting.
 
 Ideally use the Settings UI to update the setting under General -> Core -> GraphQL port:
 
-![GrapQL settings](./img/DEBUG_GRAPHQL/graphql_settings_port_token.png)
+![GrapQL settings](./img/DEBUG_API_SERVER/graphql_settings_port_token.png)
 
 You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests.
 
@@ -20,7 +20,7 @@ You might need to temporarily stop other applications or NetAlertX instances cau
 
 If the UI is not accessible, you can directly edit the `app.conf` file in your `/config` folder:
 
-![Editing app.conf](./img/DEBUG_GRAPHQL/app_conf_graphql_port.png)
+![Editing app.conf](./img/DEBUG_API_SERVER/app_conf_graphql_port.png)
 
 ### Using a docker variable
 
@@ -29,7 +29,6 @@ All application settings can also be initialized via the `APP_CONF_OVERRIDE` doc
 ```yaml
 ...
  environment:
-      - TZ=Europe/Berlin      
       - PORT=20213
       - APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"}
 ...
@@ -43,22 +42,22 @@ There are several ways to check if the GraphQL server is running.
 
 You can navigate to Maintenance -> Init Check to see if `isGraphQLServerRunning` is ticked:
 
-![Init Check](./img/DEBUG_GRAPHQL/Init_check.png)
+![Init Check](./img/DEBUG_API_SERVER/Init_check.png)
 
 ### Checking the Logs
 
 You can navigate to Maintenance -> Logs and search for `graphql` to see if it started correctly and serving requests:
 
-![GraphQL Logs](./img/DEBUG_GRAPHQL/graphql_running_logs.png)
+![GraphQL Logs](./img/DEBUG_API_SERVER/graphql_running_logs.png)
 
 ### Inspecting the Browser console
 
 In your browser open the dev console (usually F12) and navigate to the Network tab where you can filter GraphQL requests (e.g., reload the Devices page).
 
-![Browser Network Tab](./img/DEBUG_GRAPHQL/network_graphql.png)
+![Browser Network Tab](./img/DEBUG_API_SERVER/network_graphql.png)
 
 You can then inspect any of the POST requests by opening them in a new tab.
 
-![Browser GraphQL Json](./img/DEBUG_GRAPHQL/dev_console_graphql_json.png)
+![Browser GraphQL Json](./img/DEBUG_API_SERVER/dev_console_graphql_json.png)
 
 

docs/DEBUG_INVALID_JSON.md

@@ -8,8 +8,8 @@ Check the the HTTP response of the failing backend call by following these steps
 ![F12DeveloperConsole][F12DeveloperConsole]
 
 - Copy the URL causing the error and enter it in the address bar of your browser directly and hit enter. The copied URLs could look something like this (notice the query strings at the end):
-  - `http://<NetAlertX URL>:20211/api/table_devices.json?nocache=1704141103121`
+  - `http://<server>:20211/api/table_devices.json?nocache=1704141103121`
-  - `http://<NetAlertX URL>:20211/php/server/devices.php?action=getDevicesTotals`
+  - `http://<server>:20211/php/server/devices.php?action=getDevicesTotals`
 
 
 - Post the error response in the existing issue thread on GitHub or create a new issue and include the redacted response of the failing query.

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_PLUGINS.md

@@ -1,5 +1,8 @@
 # Troubleshooting plugins
 
+> [!TIP]
+> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md).
+
 ## High-level overview
 
 If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`).

docs/DEBUG_TIPS.md

@@ -13,16 +13,22 @@ When debugging an issue always set the highest log level:
 Start the container via the **terminal** with a command similar to this one:
 
 ```bash
-docker run --rm --network=host \
+docker run \
-  -v local/path/netalertx/config:/app/config \
+  --network=host \
-  -v local/path/netalertx/db:/app/db \
+  --restart unless-stopped \
-  -e TZ=Europe/Berlin \
+  -v /local_data_dir:/data \
+  -v /etc/localtime:/etc/localtime:ro \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   -e PORT=20211 \
+  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
   ghcr.io/jokob-sk/netalertx:latest
 
 ```
 
-> ⚠ Please note, don't use the `-d` parameter so you see the error when the container crashes. Use this error in your issue description.
+Note: Your `/local_data_dir` should contain a `config` and `db` folder.
+
+> [!NOTE]
+> ⚠ The most important part is NOT to use the `-d` parameter so you see the error when the container crashes. Use this error in your issue description.
 
 ## 3. Check the _dev image and open issues
 
@@ -48,7 +54,12 @@ services:
     # Other service configurations...
 ```
 
-## 5. Sharing application state
+## 5. TMP mount directories to rule host out permission issues
+
+Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. See teh [Permissions guide](./FILE_PERMISSIONS.md) for details.
+
+
+## 6. Sharing application state
 
 Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong.
 
@@ -61,4 +72,4 @@ Sometimes specific log sections are needed to debug issues. The Devices and Curr
 
 ## Common issues
 
-See [Common issues](./COMMON_ISSUES.md) for details. 
+See [Common issues](./COMMON_ISSUES.md) for additional troubleshooting tips.

docs/DEVICES_BULK_EDITING.md

@@ -26,7 +26,7 @@ The database and device structure may change with new releases. When using the C
 ![Maintenance > CSV Export](./img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png)
 
 > [!NOTE]
-> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this by acessing this URL: `<your netalertx url>/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this)
+> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this by acessing this URL: `<server>:20211/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this)
 
 ![Settings > CSV Backup](./img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png)
 

docs/DEVICE_MANAGEMENT.md

@@ -1,4 +1,4 @@
-# NetAlertX - Device Management
+# Device Management
 
 The Main Info section is where most of the device identifiable information is stored and edited. Some of the information is autodetected via various plugins. Initial values for most of the fields can be specified in the `NEWDEV` plugin.
 

docs/DEV_ENV_SETUP.md

@@ -55,7 +55,6 @@ The file content should be following, with your custom values.
 #--------------------------------
 #NETALERTX
 #--------------------------------
-TZ=Europe/Berlin
 PORT=22222    # make sure this port is unique on your whole network
 DEV_LOCATION=/development/NetAlertX
 APP_DATA_LOCATION=/volume/docker_appdata

docs/DOCKER_COMPOSE.md

@@ -1,9 +1,7 @@
 # NetAlertX and Docker Compose
 
 > [!WARNING]
-> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
+> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
-> 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.
 
@@ -31,28 +29,18 @@ services:
       - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
 
     volumes:
-      - type: volume                                # Persistent Docker-managed Named Volume for storage of config files
+      - type: volume                                # Persistent Docker-managed named volume for config + database
-        source: netalertx_config                    # the default name of the volume is netalertx_config
+        source: netalertx_data
-        target: /app/config                         # inside the container mounted to /app/config
+        target: /data                               # `/data/config` and `/data/db` live inside this mount
-        read_only: false                            # writable volume
-
-    # Example custom local folder called /home/user/netalertx_config
-    # - type: bind
-    #   source: /home/user/netalertx_config
-    #   target: /app/config
-    #   read_only: false
-    # ... or use the alternative format
-    # - /home/user/netalertx_config:/app/config:rw
-
-      - type: volume                                # NetAlertX Database partiton
-        source: netalertx_db
-        target: /app/db
         read_only: false
 
-      - type: volume                                # Future proof mount. During the migration to a
+    # Example custom local folder called /home/user/netalertx_data
-        source: netalertx_data                      # future version, app and db will be migrated to
+    # - type: bind
-        target: /data                               # the /data partition.  This will reduce the 
+    #   source: /home/user/netalertx_data
-        read_only: false                            # overhead and pain in the upcoming migration.
+    #   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
@@ -62,30 +50,25 @@ services:
       # Mount your DHCP server file into NetAlertX for a plugin to access
       # - path/on/host/to/dhcp.file:/resources/dhcp.file
 
-      # Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
+    # tmpfs mount consolidates writable state for a read-only container and improves performance
-      # - /path/on/host/log:/app/log
-
-    # Tempfs mounts for writable directories in a read-only container and improve system performance
-    # All mounts have noexec,nosuid,nodev for security purposes no devices, no suid/sgid and no execution of binaries
-    # async where possible for performance, sync where required for correctness
     # uid=20211 and gid=20211 is the netalertx user inside the container
-    # mode=1700 gives rwx------ permissions to the netalertx user only
+    # mode=1700 grants rwx------ permissions to the netalertx user only
     tmpfs:
-      # Speed up logging. This can be commented out to retain logs between container restarts
+      # Comment out to retain logs between container restarts - this has a server performance impact.
-      - "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      - "/tmp: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"  
+      # Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts
-      # Required for customization of the nginx listen addr/port without rebuilding the container
+      # Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.
-      - "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+      # - /path/on/host/log:/tmp/log
-      # /services/config/nginx/conf.d is required for nginx and php to start
+      # - "/tmp/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      - "/services/run: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 is required by php for session save this should be reworked to /services/run/tmp
+      # - "/tmp/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      - "/tmp:uid=2Key-Value Pairs: 20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+
     environment:
       LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                   # Listen for connections on all interfaces
       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.
+  #    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
@@ -101,10 +84,8 @@ services:
     # Always restart the container unless explicitly stopped
     restart: unless-stopped
 
-volumes:                        # Persistent volumes for configuration and database storage
+volumes:                        # Persistent volume for configuration and database storage
-  netalertx_config:             # Configuration files
+  netalertx_data:
-  netalertx_db:                 # Database files
-  netalertx_data:               # For future config/db upgrade
 ```
 
 Run or re-run it:
@@ -142,15 +123,17 @@ docker compose up
 
 ### 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.
+By default, the baseline compose file uses a single named volume (netalertx_data) mounted at `/data`. This single-volume layout is preferred because NetAlertX manages both configuration and the database under `/data` (for example, `/data/config` and `/data/db`) via its web UI. Using one named volume simplifies permissions and portability: Docker manages the storage and NetAlertX manages the files inside `/data`.
+
+A two-volume layout that mounts `/data/config` and `/data/db` separately (for example, `netalertx_config` and `netalertx_db`) is supported for backward compatibility and some advanced workflows, but it is an abnormal/legacy layout and not recommended for new deployments.
 
 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`.
+1. Choose a location on your computer. For example, `/local_data_dir`.
 
-2. Create the subfolders: `mkdir -p /home/adam/netalertx-files/config` and `mkdir -p /home/adam/netalertx-files/db`.
+2. Create the subfolders: `mkdir -p /local_data_dir/config` and `mkdir -p /local_data_dir/db`.
 
 3. Edit your `docker-compose.yml` and find the `volumes:` section (the one *inside* the `netalertx:` service).
 
@@ -163,25 +146,25 @@ However, if you prefer to have direct, file-level access to your configuration f
 ```yaml
 ...
     volumes:
-      - netalertx_config:/app/config:rw #short-form volume (no /path is a short volume)
+      - netalertx_config:/data/config:rw #short-form volume (no /path is a short volume)
-      - netalertx_db:/app/db:rw
+      - 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>`.
+Make sure to replace `/local_data_dir` with your actual path. The format is `<path_on_your_computer>:<path_inside_container>:<options>`.
 
 ```yaml
 ...
     volumes:
-#      - netalertx_config:/app/config:rw
+#      - netalertx_config:/data/config:rw
-#      - netalertx_db:/app/db:rw
+#      - netalertx_db:/data/db:rw
-      - /home/adam/netalertx-files/config:/app/config:rw
+      - /local_data_dir/config:/data/config:rw
-      - /home/adam/netalertx-files/db:/app/db:rw
+      - /local_data_dir/db:/data/db:rw
 ...
 ```
 
-Now, any files created by NetAlertX in `/app/config` will appear in your `/home/adam/netalertx-files/config` folder.
+Now, any files created by NetAlertX in `/data/config` will appear in your `/local_data_dir/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.
 
@@ -200,8 +183,8 @@ This method is useful for keeping your paths and other settings separate from yo
 services:
   netalertx:
     environment:
-      - TZ=${TZ}
       - PORT=${PORT}
+      - GRAPHQL_PORT=${GRAPHQL_PORT}
 
 ...
 ```
@@ -209,11 +192,9 @@ services:
 **`.env` file contents:**
 
 ```sh
-TZ=Europe/Paris
 PORT=20211
 NETALERTX_NETWORK_MODE=host
 LISTEN_ADDR=0.0.0.0
-PORT=20211
 GRAPHQL_PORT=20212
 ```
 

docs/DOCKER_INSTALLATION.md

@@ -23,28 +23,31 @@ Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and scree
 > [!WARNING]
 > You will have to run the container on the `host` network and specify `SCAN_SUBNETS` unless you use other [plugin scanners](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.
 
-```yaml
+```bash
 docker run -d --rm --network=host \
-  -v local_path/config:/app/config \
+  -v /local_data_dir:/data \
-  -v local_path/db:/app/db \
+  -v /etc/localtime:/etc/localtime \
-  --mount type=tmpfs,target=/app/api \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-  -e PUID=200 -e PGID=300 \
-  -e TZ=Europe/Berlin \
   -e PORT=20211 \
+  -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \
   ghcr.io/jokob-sk/netalertx:latest
 ```
 
 See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md).
 
+### Default ports
+
+| Default        | Description                    | How to override                                                                    |
+| :------------- |:-------------------------------| ----------------------------------------------------------------------------------:|
+| `20211`        |Port of the web interface       |  `-e PORT=20222`                                                                   |
+| `20212`        |Port of the backend API server  |  `-e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"}` or via the `GRAPHQL_PORT` Setting |
+
 ### Docker environment variables
 
 | Variable | Description | Example Value |
 | :------------- |:------------------------| -----:|
 | `PORT`      |Port of the web interface  |  `20211` |
-| `PUID`      |Application User UID  |  `102` |
-| `PGID`      |Application User GID  |  `82` |
 | `LISTEN_ADDR`      |Set the specific IP Address for the listener address for the nginx webserver (web interface). This could be useful when using multiple subnets to hide the web interface from all untrusted networks. |  `0.0.0.0` |
-|`TZ` |Time zone to display stats correctly. Find your time zone [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)  |  `Europe/Berlin` |
 |`LOADED_PLUGINS` | Default [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) to load. Plugins cannot be loaded with `APP_CONF_OVERRIDE`, you need to use this variable instead and then specify the plugins settings with `APP_CONF_OVERRIDE`. |  `["PIHOLE","ASUSWRT"]` |
 |`APP_CONF_OVERRIDE` | JSON override for settings (except `LOADED_PLUGINS`).   |  `{"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20212"}` |
 |`ALWAYS_FRESH_INSTALL` | ⚠ If `true` will delete the content of the `/db` & `/config` folders. For testing purposes. Can be coupled with [watchtower](https://github.com/containrrr/watchtower) to have an always freshly installed `netalertx`/`netalertx-dev` image.   |    `true` |
@@ -58,10 +61,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` | Folder which will contain the `/db/app.db`, `/config/app.conf` & `/config/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  | 
+| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is teh same as on teh server.  |
-| | `:/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` |  The [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 +73,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

@@ -1,9 +1,7 @@
 # The NetAlertX Container Operator's Guide
 
 > [!WARNING]
-> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
+> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
-> 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.
 
@@ -51,13 +49,13 @@ You want to edit your `app.conf` and other configuration files directly from you
        volumes:
          # - type: volume
          #   source: netalertx_config
-         #   target: /app/config
+         #   target: /data/config
          #   read_only: false
    ...
        # Example custom local folder called /data/netalertx_config
        - type: bind
          source: /data/netalertx_config
-         target: /app/config
+         target: /data/config
          read_only: false
    ...
    ```
@@ -70,7 +68,7 @@ You want to edit your `app.conf` and other configuration files directly from you
 
 ### 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 (`/app/config`), allowing you to edit the files directly.
+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.
 
 ---
 
@@ -97,13 +95,13 @@ You are currently using a local folder (bind mount) for your configuration (e.g.
        volumes:
          - type: volume
            source: netalertx_config
-           target: /app/config
+           target: /data/config
            read_only: false
    ...
        # Example custom local folder called /data/netalertx_config
        # - type: bind
        #   source: /data/netalertx_config
-       #   target: /app/config
+       #   target: /data/config
        #   read_only: false
    ...
    ```
@@ -149,7 +147,7 @@ You need to override the default Nginx configuration to add features like LDAP,
    ```yaml
    ...
        # Use a custom Enterprise-configured nginx config for ldap or other settings
-       - /data/my-netalertx.conf:/services/config/nginx/conf.active/netalertx.conf:ro
+       - /data/my-netalertx.conf:/tmp/nginx/active-config/netalertx.conf:ro
    ...
    ```
 4. Restart the container:

docs/DOCKER_PORTAINER.md

@@ -8,12 +8,12 @@ This guide shows you how to set up **NetAlertX** using Portainer’s **Stacks**
 
 ## 1. Prepare Your Host
 
-Before deploying, make sure you have a folder on your Docker host for NetAlertX data. Replace `APP_FOLDER` with your preferred location, for example `/opt` here:
+Before deploying, make sure you have a folder on your Docker host for NetAlertX data. Replace `APP_FOLDER` with your preferred location, for example `/local_data_dir` here:
 
 ```bash
-mkdir -p /opt/netalertx/config
+mkdir -p /local_data_dir/netalertx/config
-mkdir -p /opt/netalertx/db
+mkdir -p /local_data_dir/netalertx/db
-mkdir -p /opt/netalertx/log
+mkdir -p /local_data_dir/netalertx/log
 ```
 
 ---
@@ -34,32 +34,27 @@ Copy and paste the following YAML into the **Web editor**:
 services:
   netalertx:
     container_name: netalertx
-
     # Use this line for stable release
     image: "ghcr.io/jokob-sk/netalertx:latest"
-
     # Or, use this for the latest development build
     # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
-
     network_mode: "host"
     restart: unless-stopped
-
+    cap_drop:       # Drop all capabilities for enhanced security
+      - ALL
+    cap_add:        # Re-add necessary capabilities
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
     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)
+      # to sync with system time
-      - ${APP_FOLDER}/netalertx/log:/app/log
+      - /etc/localtime:/etc/localtime:ro
-
+    tmpfs:
-      # API storage options:
+      # All writable runtime state resides under /tmp; comment out to persist logs between restarts
-      # (Option 1) tmpfs (default, best performance)
+      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      - type: tmpfs
-        target: /app/api
-
-      # (Option 2) bind mount (useful for debugging)
-      # - ${APP_FOLDER}/netalertx/api:/app/api
-
     environment:
-      - TZ=${TZ}
       - PORT=${PORT}
       - APP_CONF_OVERRIDE=${APP_CONF_OVERRIDE}
 ```
@@ -70,14 +65,26 @@ services:
 
 In the **Environment variables** section of Portainer, add the following:
 
-* `APP_FOLDER=/opt` (or wherever you created the directories in step 1)
+* `APP_FOLDER=/local_data_dir` (or wherever you created the directories in step 1)
-* `TZ=Europe/Berlin` (replace with your timezone)
 * `PORT=22022` (or another port if needed)
-* `APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22023"}` (optional advanced settings)
+* `APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22023"}` (optional advanced settings, otherwise the backend API server PORT defaults to `20212`)
 
 ---
 
-## 5. Deploy the Stack
+## 5. Ensure permissions
+
+> [!TIP]
+> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located).
+>
+>  `sudo chown -R 20211:20211 /local_data_dir`
+>
+>  `sudo chmod -R a+rwx  /local_data_dir`
+>
+
+
+---
+
+## 6. Deploy the Stack
 
 1. Scroll down and click **Deploy the stack**.
 2. Portainer will pull the image and start NetAlertX.
@@ -89,7 +96,7 @@ http://<your-docker-host-ip>:22022
 
 ---
 
-## 6. Verify and Troubleshoot
+## 7. Verify and Troubleshoot
 
 * Check logs via Portainer → **Containers** → `netalertx` → **Logs**.
 * Logs are stored under `${APP_FOLDER}/netalertx/log` if you enabled that volume.

docs/DOCKER_SWARM.md

@@ -41,15 +41,7 @@ Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** a
 services:
   netalertx:
     image: ghcr.io/jokob-sk/netalertx:latest
-    ports:
+...
-      - 20211:20211
-    volumes:
-      - /mnt/YOUR_SERVER/netalertx/config:/app/config:rw
-      - /mnt/YOUR_SERVER/netalertx/db:/netalertx/app/db:rw
-      - /mnt/YOUR_SERVER/netalertx/logs:/netalertx/app/log:rw
-    environment:
-      - TZ=Europe/London
-      - PORT=20211
     networks:
       swarm-ipvlan:
         ipv4_address: 192.168.1.240     # ⚠️ Choose a free IP from your LAN

docs/FILE_PERMISSIONS.md

@@ -1,8 +1,23 @@
 # Managing File Permissions for NetAlertX on a Read-Only Container
 
+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.
+
 > [!TIP]
 > 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.
 
+Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server.
+
+```bash
+docker run --rm --network=host \
+  -v /etc/localtime:/etc/localtime:ro \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
+  -e PORT=20211 \
+  ghcr.io/jokob-sk/netalertx:latest
+```
+
+> [!WARNING]
+> The above should be only used as a test - once the container restarts, all data is lost.
+
 ---
 
 ## Writable Paths
@@ -11,30 +26,28 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b
 
 | Path                                 | Purpose                             | Notes                                                  |
 | ------------------------------------ | ----------------------------------- | ------------------------------------------------------ |
-| `/app/config`                        | Application configuration           | Persistent volume recommended                          |
+| `/data/config`                        | Application configuration           | Persistent volume recommended                          |
-| `/app/db`                            | Database files                      | Persistent volume recommended                          |
+| `/data/db`                            | Database files                      | Persistent volume recommended                          |
-| `/app/log`                           | Logs                                | Can be `tmpfs` for speed or host volume to retain logs |
+| `/tmp/log`                           | Logs                                | Lives under `/tmp`; optional host bind to retain logs  |
-| `/app/api`                           | API cache                           | Use `tmpfs` for faster access                          |
+| `/tmp/api`                           | API cache                           | Subdirectory of `/tmp`                                 |
-| `/services/config/nginx/conf.active` | Active nginx configuration override | `tmpfs` recommended or customized file mounted        |
+| `/tmp/nginx/active-config` | Active nginx configuration override | Mount `/tmp` (or override specific file)               |
-| `/services/run`                      | Runtime directories for nginx & PHP | `tmpfs` required                                       |
+| `/tmp/run`                      | Runtime directories for nginx & PHP | Subdirectory of `/tmp`                                 |
-| `/tmp`                               | PHP session save directory          | `tmpfs` required                                       |
+| `/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:/app/config \
+  -v /local_data_dir:/data \
-  -v local/path/db:/app/db \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   ghcr.io/jokob-sk/netalertx:latest
 ```
 
@@ -44,6 +57,14 @@ docker run -it --rm --name netalertx --user "0" \
 
 > The container startup script detects `root` and runs `chown -R 20211:20211` on all volumes, fixing ownership for the secure `netalertx` user.
 
+> [!TIP]
+> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located).
+>
+>  `sudo chown -R 20211:20211 /local_data_dir`
+>
+>  `sudo chmod -R a+rwx  /local_data_dir`
+>
+
 ---
 
 ## Example: docker-compose.yml with `tmpfs`
@@ -54,22 +75,19 @@ services:
     container_name: netalertx
     image: "ghcr.io/jokob-sk/netalertx"
     network_mode: "host"
-    cap_add:
+    cap_drop:                                       # Drop all capabilities for enhanced security
-      - NET_RAW
+      - ALL
-      - NET_ADMIN
+    cap_add:                                        # Add only the necessary capabilities
-      - NET_BIND_SERVICE
+      - NET_ADMIN                                   # Required for ARP scanning
+      - NET_RAW                                     # Required for raw socket operations
+      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         
+      - /local_data_dir:/data
-      - local/path/db:/app/db                 
+      - /etc/localtime:/etc/localtime
     environment:
-      - TZ=Europe/Berlin      
       - PORT=20211
     tmpfs:
-      - "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      - "/app/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,sync,noatime,nodiratime"  
-      - "/services/config/nginx/conf.active:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
-      - "/services/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
       - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
 ```
 

docs/HELPER_SCRIPTS.md

@@ -1,4 +1,4 @@
-# NetAlertX Community Helper Scripts Overview
+# Community Helper Scripts Overview
 
 This page provides an overview of community-contributed scripts for NetAlertX. These scripts are not actively maintained and are provided as-is.
 

docs/HW_INSTALL.md

@@ -13,8 +13,7 @@ To download and install NetAlertX on the hardware/server directly use the `curl`
 > Data loss is a possibility, **it is recommended to install NetAlertX using the supplied Docker image**.
 
 > [!WARNING]
-> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may
+> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may be dangerous, as you cannot see the code that's about to be executed on your system.
-be dangerous, as you cannot see the code that's about to be executed on your system.
 
 If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will fo its best to install NetAlertX on your system.
 

docs/INSTALLATION.md

@@ -4,7 +4,7 @@
 
 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)](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.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)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 

docs/LOGGING.md

@@ -9,7 +9,7 @@ NetAlertX comes with several logs that help to identify application issues. Thes
 
 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)
 
@@ -52,18 +52,18 @@ The default logs are erased every time the container restarts because they are s
 
 2. Edit your `docker-compose.yml` file:
 
-   * **Comment out** the `/app/log` line under the `tmpfs:` section.
+   * **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:
-         # - "/app/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
+         # - "/tmp/log:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
    ...
        volumes:
    ...
-         # Retain logs - comment out tmpfs /app/log if you want to retain logs between container restarts
+         # Retain logs - comment out tmpfs /tmp/log if you want to retain logs between container restarts
-         - /home/adam/netalertx_logs:/app/log
+         - /home/adam/netalertx_logs:/tmp/log
    ...
    ```
 3. Restart the container:
@@ -72,4 +72,4 @@ The default logs are erased every time the container restarts because they are s
    docker-compose up -d
    ```
 
-This change stops Docker from mounting a temporary in-memory volume at `/app/log`. Instead, it "bind mounts" a persistent folder from your host computer (e.g., `/data/netalertx_logs`) to that *same location* inside the container. 
+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,11 +1,5 @@
 # Migration
 
-> [!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.
-
-
 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]
@@ -43,7 +37,7 @@ A banner message will appear at the top of the web UI reminding you to update yo
 
 
 > [!TIP]
-> 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 /app/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. 
+> 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
 
@@ -51,8 +45,8 @@ The internal application path in the container has changed from `/home/pi/pialer
 
  | 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:
@@ -85,10 +79,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config:/home/pi/pialert/config  
+      - /local_data_dir/config:/home/pi/pialert/config
-      - local/path/db:/home/pi/pialert/db         
+      - /local_data_dir/db:/home/pi/pialert/db
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/home/pi/pialert/front/log
+      - /local_data_dir/logs:/home/pi/pialert/front/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -104,10 +98,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         # 🆕 This has changed  
+      - /local_data_dir/config:/data/config         # 🆕 This has changed
-      - local/path/db:/app/db                 # 🆕 This has changed  
+      - /local_data_dir/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  
+      - /local_data_dir/logs:/tmp/log        # 🆕 This has changed
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -131,10 +125,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config/pialert.conf:/home/pi/pialert/config/pialert.conf  
+      - /local_data_dir/config/pialert.conf:/home/pi/pialert/config/pialert.conf
-      - local/path/db/pialert.db:/home/pi/pialert/db/pialert.db         
+      - /local_data_dir/db/pialert.db:/home/pi/pialert/db/pialert.db
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/home/pi/pialert/front/log
+      - /local_data_dir/logs:/home/pi/pialert/front/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -150,10 +144,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config/app.conf:/app/config/app.conf # 🆕 This has changed  
+      - /local_data_dir/config/app.conf:/data/config/app.conf # 🆕 This has changed
-      - local/path/db/app.db:/app/db/app.db             # 🆕 This has changed  
+      - /local_data_dir/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  
+      - /local_data_dir/logs:/tmp/log                  # 🆕 This has changed
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -190,10 +184,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         
+      - /local_data_dir/config:/data/config
-      - local/path/db:/app/db                 
+      - /local_data_dir/db:/data/db
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log        
+      - /local_data_dir/logs:/tmp/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -207,10 +201,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         
+      - /local_data_dir/config:/data/config
-      - local/path/db:/app/db                 
+      - /local_data_dir/db:/data/db
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log        
+      - /local_data_dir/logs:/tmp/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -218,7 +212,7 @@ services:
 
 ### 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). 
+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). The data location has also hanged from `/app/db` and `/app/config` to `/data/db` and `/data/config`. See detailed steps below.
 
 #### STEPS:
 
@@ -234,10 +228,10 @@ services:
     network_mode: "host"
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         
+      - /local_data_dir/config:/app/config
-      - local/path/db:/app/db                 
+      - /local_data_dir/db:/app/db
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/log        
+      - /local_data_dir/logs:/tmp/log
     environment:
       - TZ=Europe/Berlin
       - PORT=20211
@@ -248,16 +242,24 @@ services:
 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`.  
+> The example below assumes your `/config` and `/db` folders are stored in `local_data_dir`.
 > 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:/app/config \
+  -v /local_data_dir/config:/data/config \
-  -v local/path/db:/app/db \
+  -v /local_data_dir/db:/data/db \
+  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   ghcr.io/jokob-sk/netalertx:latest
 ```
 
+...or alternatively execute:
+
+```bash
+sudo chown -R 20211:20211 /local_data_dir
+sudo chmod -R a+rwx /local_data_dir
+```
+
 7. Stop the container
 8. Update the `docker-compose.yml` as per example below.
 
@@ -265,32 +267,24 @@ docker run -it --rm --name netalertx --user "0" \
 services:
   netalertx:
     container_name: netalertx
-    image: "ghcr.io/jokob-sk/netalertx"         # 🆕 This is important  
+    image: "ghcr.io/jokob-sk/netalertx"  # 🆕 This has changed
     network_mode: "host"
-    cap_add:                          # 🆕 New line
+    cap_drop:                # 🆕 New line
-      - NET_RAW                       # 🆕 New line 
+      - ALL                  # 🆕 New line
-      - NET_ADMIN                     # 🆕 New line
+    cap_add:                 # 🆕 New line
-      - NET_BIND_SERVICE              # 🆕 New line 
+      - NET_RAW              # 🆕 New line
+      - NET_ADMIN            # 🆕 New line
+      - NET_BIND_SERVICE     # 🆕 New line
     restart: unless-stopped
     volumes:
-      - local/path/config:/app/config         
+      - /local_data_dir:/data  # 🆕 This folder contains your /db and /config directories and the parent changed from /app to /data
-      - local/path/db:/app/db                 
+      # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured
-      # (optional) useful for debugging if you have issues setting up the container
+      - /etc/localtime:/etc/localtime:ro    # 🆕 New line
-      #- local/path/logs:/app/log        
     environment:
-      - TZ=Europe/Berlin      
       - PORT=20211
     # 🆕 New "tmpfs" section START 🔽
     tmpfs:
-      # Speed up logging. This can be commented out to retain logs between container restarts
+      # All writable runtime state resides under /tmp; comment out to persist logs between 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"
     # 🆕 New "tmpfs" section END  🔼
 ```

docs/NETWORK_TREE.md

@@ -50,6 +50,8 @@ Let’s walk through setting up a device named `raspberrypi` to act as a network
 
 - Optionally assign a **Parent Node** (where this device connects to) and the **Relationship type** of the connection.
   The `nic` relationship type can affect parent notifications — see the setting description and [Notifications documentation](./NOTIFICATIONS.md) for more.
+- A device’s parent MAC will be overwritten by plugins if its current value is any of the following: "null", "(unknown)" "(Unknown)".
+- If you want plugins to be able to overwrite the parent value (for example, when mixing plugins that do not provide parent MACs like `ARPSCAN` with those that do, like `UNIFIAPI`), you must set the setting `NEWDEV_devParentMAC` to None.
 
 ![Device details](./img/NETWORK_TREE/Network_Device_Details_Parent.png)
 

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

@@ -1,47 +1,50 @@
 # Performance Optimization Guide
 
-There are several ways to improve the application's performance. The application has been tested on a range of devices, from a Raspberry Pi 4 to NAS and NUC systems. If you are running the application on a lower-end device, carefully fine-tune the performance settings to ensure an optimal user experience.
+There are several ways to improve the application's performance. The application has been tested on a range of devices, from Raspberry Pi 4 units to NAS and NUC systems. If you are running the application on a lower-end device, fine-tuning the performance settings can significantly improve the user experience.
 
 ## Common Causes of Slowness
 
 Performance issues are usually caused by:
 
-- **Incorrect settings** – The app may restart unexpectedly. Check `app.log` under **Maintenance → Logs** for details.
+* **Incorrect settings** – The app may restart unexpectedly. Check `app.log` under **Maintenance → Logs** for details.
-- **Too many background processes** – Disable unnecessary scanners.
+* **Too many background processes** – Disable unnecessary scanners.
-- **Long scan durations** – Limit the number of scanned devices.
+* **Long scan durations** – Limit the number of scanned devices.
-- **Excessive disk operations** – Optimize scanning and logging settings.
+* **Excessive disk operations** – Optimize scanning and logging settings.
-- **Failed maintenance plugins** – Ensure maintenance tasks are running properly.
+* **Maintenance plugin failures** – If cleanup tasks fail, performance can degrade over time.
 
-The application performs regular maintenance and database cleanup. If these tasks fail, performance may degrade.
+The application performs regular maintenance and database cleanup. If these tasks are failing, you will see slowdowns.
 
 ### Database and Log File Size
 
-A large database or oversized log files can slow down performance. You can check database and table sizes on the **Maintenance** page.
+A large database or oversized log files can impact performance. You can check database and table sizes on the **Maintenance** page.
 
 ![DB size check](./img/PERFORMANCE/db_size_check.png)
 
 > [!NOTE]
-> - For **~100 devices**, the database should be around **50MB**.
+>
-> - No table should exceed **10,000 rows** in a healthy system.
+> * For **~100 devices**, the database should be around **50 MB**.
-> - These numbers vary based on network activity and settings.
+> * No table should exceed **10,000 rows** in a healthy system.
+> * Actual values vary based on network activity and plugin settings.
 
 ---
 
 ## Maintenance Plugins
 
-Two plugins help maintain the application’s performance:
+Two plugins help maintain the system’s performance:
 
 ### **1. Database Cleanup (DBCLNP)**
-- Responsible for database maintenance.
+
-- Check settings in the [DB Cleanup Plugin Docs](/front/plugins/db_cleanup/README.md).
+* Handles database maintenance and cleanup.
-- Ensure it’s not failing by checking logs.
+* See the [DB Cleanup Plugin Docs](/front/plugins/db_cleanup/README.md).
-- Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if needed.
+* Ensure it’s not failing by checking logs.
+* Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if necessary.
 
 ### **2. Maintenance (MAINT)**
-- Handles log cleanup and other maintenance tasks.
+
-- Check settings in the [Maintenance Plugin Docs](/front/plugins/maintenance/README.md).
+* Cleans logs and performs general maintenance tasks.
-- Ensure it’s running correctly by checking logs.
+* See the [Maintenance Plugin Docs](/front/plugins/maintenance/README.md).
-- Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed.
+* Verify proper operation via logs.
+* Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed.
 
 ---
 
@@ -50,47 +53,56 @@ Two plugins help maintain the application’s performance:
 Frequent scans increase resource usage, network traffic, and database read/write cycles.
 
 ### **Optimizations**
-- **Increase scan intervals** (`<PLUGIN>_RUN_SCHD`) on busy networks or low-end hardware.
-- **Extend scan timeouts** (`<PLUGIN>_RUN_TIMEOUT`) to prevent failures.
-- **Reduce the subnet size** – e.g., from `/16` to `/24` to lower scan loads.
 
-Some plugins have additional options to limit the number of scanned devices. If certain plugins take too long to complete, check if you can optimize scan times by selecting a scan range. 
+* **Increase scan intervals** (`<PLUGIN>_RUN_SCHD`) on busy networks or low-end hardware.
+* **Increase timeouts** (`<PLUGIN>_RUN_TIMEOUT`) to avoid plugin failures.
+* **Reduce subnet size** – e.g., use `/24` instead of `/16` to reduce scan load.
 
-For example, the **ICMP plugin** allows you to specify a regular expression to scan only IPs that match a specific pattern.
+Some plugins also include options to limit which devices are scanned. If certain plugins consistently run long, consider narrowing their scope.
+
+For example, the **ICMP plugin** allows scanning only IPs that match a specific regular expression.
 
 ---
 
 ## 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 devices with slower I/O, you can improve performance by storing temporary files (and optionally the database) in memory using `tmpfs`.
 
-Using `tmpfs` reduces disk writes and improves performance. However, it should be **disabled** if persistent logs or API data storage are required.
+> [!WARNING]
+> Storing the **database** in `tmpfs` is generally discouraged. Use this only if device data and historical records are not required to persist. If needed, you can pair this setup with the `SYNC` plugin to store important persistent data on another node. See the [Plugins docs](./PLUGINS.md) for details.
 
-Below is an optimized `docker-compose.yml` snippet:
+Using `tmpfs` reduces disk writes and speeds up I/O, but **all data stored in memory will be lost on restart**.
 
+Below is an optimized `docker-compose.yml` snippet using non-persistent logs, API data, and DB:
 
 ```yaml
-version: "3"
 services:
   netalertx:
     container_name: netalertx
-    # Uncomment the line below to test the latest dev image
+    # Use this line for the stable release
-    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
     image: "ghcr.io/jokob-sk/netalertx:latest"
+    # Or use this line for the latest development build
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
     network_mode: "host"
     restart: unless-stopped
-    volumes:
-      - local/path/config:/app/config
-      - local/path/db:/app/db      
-      # (Optional) Useful for debugging setup issues
-      - local/path/logs:/app/log
-      # (API: OPTION 1) Store temporary files in memory (recommended for performance)
-      - type: tmpfs              # ◀ 🔺
-        target: /app/api         # ◀ 🔺
-      # (API: OPTION 2) Store API data on disk (useful for debugging)
-      # - local/path/api:/app/api
-    environment:
-      - TZ=Europe/Berlin      
-      - PORT=20211
 
+    cap_drop:       # Drop all capabilities for enhanced security
+      - ALL
+    cap_add:        # Re-add necessary capabilities
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
+
+    volumes:
+      - ${APP_FOLDER}/netalertx/config:/data/config
+      - /etc/localtime:/etc/localtime:ro
+
+    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"
+      - "/data/db:uid=20211,gid=20211,mode=1700"  # ⚠ You will lose historical data on restart
+
+    environment:
+      - PORT=${PORT}
+      - APP_CONF_OVERRIDE=${APP_CONF_OVERRIDE}
 ```

docs/PLUGINS.md

@@ -64,6 +64,7 @@ Device-detecting plugins insert values into the `CurrentScan` database table.  T
 | `LUCIRPC`       | [luci_import](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/luci_import/)                         | 🔍       | Import connected devices from OpenWRT     |          |          |
 | `MAINT`         | [maintenance](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/maintenance/)                          | ⚙        | Maintenance of logs, etc.                 |          |          |
 | `MQTT`          | [_publisher_mqtt](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_mqtt/)                | ▶️       | MQTT for synching to Home Assistant       |          |          |
+| `MTSCAN`        | [mikrotik_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/mikrotik_scan/)                    | 🔍       | Mikrotik device import & sync              |          |          |
 | `NBTSCAN`       | [nbtscan_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nbtscan_scan/)                       | 🆎       | Nbtscan (NetBIOS-based) name resolution   |          |          |
 | `NEWDEV`        | [newdev_template](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/newdev_template/)                 | ⚙        | New device template                       |          | Yes      |
 | `NMAP`          | [nmap_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nmap_scan/)                             | ♻        | Nmap port scanning & discovery            |          |          |
@@ -74,6 +75,7 @@ Device-detecting plugins insert values into the `CurrentScan` database table.  T
 | `OMDSDN`        | [omada_sdn_imp](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/omada_sdn_imp/)                    | 📥/🆎 ❌  | UNMAINTAINED use `OMDSDNOPENAPI`          | 🖧 🔄    |          |
 | `OMDSDNOPENAPI` | [omada_sdn_openapi](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/omada_sdn_openapi/)            | 📥/🆎    | OMADA TP-Link import via OpenAPI          | 🖧       |          |
 | `PIHOLE`        | [pihole_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_scan/)                         | 🔍/🆎/📥 | Pi-hole device import & sync              |          |          |
+| `PIHOLEAPI`     | [pihole_api_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_api_scan/)                 | 🔍/🆎/📥 | Pi-hole device import & sync via API v6+ |          |          |
 | `PUSHSAFER`     | [_publisher_pushsafer](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_pushsafer/)      | ▶️       | Pushsafer notifications                   |          |          |
 | `PUSHOVER`      | [_publisher_pushover](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_pushover/)        | ▶️       | Pushover notifications                    |          |          |
 | `SETPWD`        | [set_password](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/set_password/)                       | ⚙        | Set password                              |          | Yes      |

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 🧪)
 
@@ -63,7 +63,6 @@ There is also an in-app Help / FAQ section that should be answering frequently a
 
 #### ♻ Misc
 
-- [Version history (legacy)](./VERSIONS_HISTORY.md)
 - [Reverse proxy (Nginx, Apache, SWAG)](./REVERSE_PROXY.md)
 - [Installing Updates](./UPDATES.md)
 - [Setting up Authelia](./AUTHELIA.md) (DRAFT)

docs/REVERSE_DNS.md

@@ -3,7 +3,7 @@
 If you are running a DNS server, such as **AdGuard**, set up **Private reverse DNS servers** for a better name resolution on your network. Enabling this setting will enable NetAlertX to execute dig and nslookup commands to automatically resolve device names based on their IP addresses.
 
 > [!TIP]
-> Before proceeding, ensure that [name resolution plugins](./NAME_RESOLUTION.md) are enabled.  
+> Before proceeding, ensure that [name resolution plugins](/local_data_dir/NAME_RESOLUTION.md) are enabled.
 > You can customize how names are cleaned using the `NEWDEV_NAME_CLEANUP_REGEX` setting.
 > To auto-update Fully Qualified Domain Names (FQDN), enable the `REFRESH_FQDN` setting.
 
@@ -40,15 +40,7 @@ services:
   netalertx:
     container_name: netalertx
     image: "ghcr.io/jokob-sk/netalertx:latest"
-    restart: unless-stopped
+...
-    volumes:
-      -  /home/netalertx/config:/app/config
-      -  /home/netalertx/db:/app/db
-      -  /home/netalertx/log:/app/log
-    environment:
-      - TZ=Europe/Berlin
-      - PORT=20211
-    network_mode: host
     dns:           # specifying the DNS servers used for the container
       - 10.8.0.1
       - 10.8.0.17
@@ -65,22 +57,13 @@ version: "3"
 services:
   netalertx:
     container_name: netalertx
-    image: "ghcr.io/jokob-sk/netalertx:latest"
-    restart: unless-stopped
     volumes:
-      - ./config/app.conf:/app/config/app.conf
+...
-      - ./db:/app/db
+      - /local_data_dir/config/resolv.conf:/etc/resolv.conf                          # ⚠ Mapping the /resolv.conf file for better name resolution
-      - ./log:/app/log
+...
-      - ./config/resolv.conf:/etc/resolv.conf                          # Mapping the /resolv.conf file for better name resolution
-    environment:
-      - TZ=Europe/Berlin
-      - PORT=20211
-    ports:
-      - "20211:20211"
-    network_mode: host
 ```
 
-#### ./config/resolv.conf:
+#### /local_data_dir/config/resolv.conf:
 
 The most important below is the `nameserver` entry (you can add multiple):
 

docs/REVERSE_PROXY.md

@@ -496,14 +496,9 @@ server {
 Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/default`) into the docker container:
 
 
-```bash
+```yaml
-docker run -d --rm --network=host \
+...
-  --name=netalertx \
+  volumes:
-  -v /appl/docker/netalertx/config:/app/config \
+    - /appl/docker/netalertx/default:/etc/nginx/sites-available/default
-  -v /appl/docker/netalertx/db:/app/db \
+...
-  -v /appl/docker/netalertx/default:/etc/nginx/sites-available/default \
-  -e TZ=Europe/Amsterdam \
-  -e PORT=20211 \
-  ghcr.io/jokob-sk/netalertx:latest
-
 ```

docs/SECURITY_FEATURES.md

@@ -48,7 +48,7 @@ Here’s a breakdown of the defensive layers you get, right out of the box using
 
 **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., `/app/log`, `/app/api`, `/tmp`) to in-memory `tmpfs` filesystems. They do not exist on the host's disk.
+* **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.
 

docs/SESSION_INFO.md

@@ -1,62 +1,64 @@
-# Sessions Section in Device View
+# Sessions Section – Device View
 
-The **Sessions Section** provides details about a device's connection history. This data is automatically detected and cannot be edited by the user.
+The **Sessions Section** shows a device’s connection history. All data is automatically detected and **cannot be edited**.
 
- ![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png)
+![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png)
 
 ---
 
 ## Key Fields
 
-1. **Date and Time of First Connection**
+| Field                          | Description                                                                                      | Editable?       |
-   - **Description:** Displays the first detected connection time for the device.
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | --------------- |
-   - **Editability:** Uneditable (auto-detected).
+| **First Connection**           | The first time the device was detected on the network.                                           | ❌ Auto-detected |
-   - **Source:** Automatically captured when the device is first added to the system.
+| **Last Connection**            | The most recent time the device was online.                                                      | ❌ Auto-detected |
-
-2. **Date and Time of Last Connection**
-   - **Description:** Shows the most recent time the device was online.
-   - **Editability:** Uneditable (auto-detected).
-   - **Source:** Updated with every new connection event.
-
-3. **Offline Devices with Missing or Conflicting Data**
-   - **Description:** Handles cases where a device is offline but has incomplete or conflicting session data (e.g., missing start times).
-   - **Handling:** The system flags these cases for review and attempts to infer missing details.
 
 ---
 
-## How Sessions are Discovered and Calculated
+## How Session Information Works
 
 ### 1. Detecting New Devices
-When a device is first detected in the network, the system logs it in the events table:
 
-`INSERT INTO Events (eve_MAC, eve_IP, eve_DateTime, eve_EventType, eve_AdditionalInfo, eve_PendingAlertEmail) SELECT cur_MAC, cur_IP, '{startTime}', 'New Device', cur_Vendor, 1 FROM CurrentScan WHERE NOT EXISTS (SELECT 1 FROM Devices WHERE devMac = cur_MAC)`
+* New devices are automatically detected when they first appear on the network.
+* A **New Device** record is created, capturing the MAC, IP, vendor, and detection time.
 
-- Devices scanned in the current cycle (**CurrentScan**) are checked against the **Devices** table.
+### 2. Recording Connection Sessions
-- If a device is new:
-  - A **New Device** event is logged.
-  - The device’s MAC, IP, vendor, and detection time are recorded.
 
-### 2. Logging Connection Sessions
+* Every time a device connects, a session entry is created.
-When a new connection is detected, the system creates a session record:
+* Captured details include:
 
-`INSERT INTO Sessions (ses_MAC, ses_IP, ses_EventTypeConnection, ses_DateTimeConnection, ses_EventTypeDisconnection, ses_DateTimeDisconnection, ses_StillConnected, ses_AdditionalInfo) SELECT cur_MAC, cur_IP, 'Connected', '{startTime}', NULL, NULL, 1, cur_Vendor FROM CurrentScan WHERE NOT EXISTS (SELECT 1 FROM Sessions WHERE ses_MAC = cur_MAC)`
+  * Connection type (wired or wireless)
-
+  * Connection time
-- A new session is logged in the **Sessions** table if no prior session exists.
+  * Device details (MAC, IP, vendor)
-- Fields like `MAC`, `IP`, `Connection Type`, and `Connection Time` are populated.
-- The `Still Connected` flag is set to `1` (active connection).
 
 ### 3. Handling Missing or Conflicting Data
-- Devices with incomplete or conflicting session data (e.g., missing start times) are detected.
+
-- The system flags these records and attempts corrections by inferring details from available data.
+* **Triggers:**
+  Devices are flagged when session data is incomplete, inconsistent, or conflicting. Examples include:
+
+  * Missing first or last connection timestamps
+  * Overlapping session records
+  * Sessions showing a device as connected and disconnected at the same time
+
+* **System response:**
+
+  * Automatically highlights affected devices in the **Sessions Section**.
+  * Attempts to **infer missing information** from available data, such as:
+
+    * Estimating first or last connection times from nearby session events
+    * Correcting overlapping session periods
+    * Reconciling conflicting connection statuses
+
+* **User impact:**
+
+  * Users do **not** need to manually fix session data.
+  * The system ensures the device’s connection history remains as accurate as possible for monitoring and reporting.
 
 ### 4. Updating Sessions
-- When a device reconnects, its session is updated with a new connection timestamp.
-- When a device disconnects:
-  - The **Disconnection Time** is recorded.
-  - The `Still Connected` flag is set to `0`.
 
-The session information is then used to display the device presence under **Monitoring** -> **Presence**.
+* **Reconnect:** Updates session with the new connection timestamp.
+* **Disconnect:** Records disconnection time and marks the device as offline.
+
+This session information feeds directly into **Monitoring → Presence**, providing a live view of which devices are currently online.
 
 ![Monitoring Device Presence](./img/SESSION_INFO/Monitoring_Presence.png)
-
-

docs/SYNOLOGY_GUIDE.md

@@ -29,6 +29,7 @@ The folders you are creating below will contain the configuration and the databa
 - Path: `/app_storage/netalertx` (will differ from yours)
 - Paste in the following template:
 
+
 ```yaml
 version: "3"
 services:
@@ -39,13 +40,20 @@ services:
     image: "ghcr.io/jokob-sk/netalertx:latest"
     network_mode: "host"
     restart: unless-stopped
+    cap_drop:       # Drop all capabilities for enhanced security
+      - ALL
+    cap_add:        # Re-add necessary capabilities
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
     volumes:
-      - local/path/config:/app/config
+      - /app_storage/netalertx:/data
-      - local/path/db:/app/db      
+      # to sync with system time
-      # (optional) useful for debugging if you have issues setting up the container
+      - /etc/localtime:/etc/localtime:ro
-      - local/path/logs:/app/log
+    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"
     environment:
-      - TZ=Europe/Berlin      
       - PORT=20211
 ```
 
@@ -57,10 +65,7 @@ services:
 
 ```yaml
  volumes:
-      - /volume1/app_storage/netalertx/config:/app/config
+      - /volume1/app_storage/netalertx:/data
-      - /volume1/app_storage/netalertx/db:/app/db      
-      # (optional) useful for debugging if you have issues setting up the container
-      # - local/path/logs:/app/log <- commented out with # ⚠
 ```
 
 ![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png)
@@ -72,3 +77,12 @@ services:
 
 10. Navigate to `<Synology URL>:20211` (or your custom port).
 11. Read the [Subnets](./SUBNETS.md) and [Plugins](/docs/PLUGINS.md) docs to complete your setup.
+
+
+> [!TIP]
+> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located).
+>
+>  `sudo chown -R 20211:20211 /local_data_dir`
+>
+>  `sudo chmod -R a+rwx  /local_data_dir`
+>

docs/UPDATES.md

@@ -2,6 +2,7 @@
 
 > [!WARNING]
 > For versions prior to `v25.6.7` upgrade to version `v25.5.24` first (`docker pull ghcr.io/jokob-sk/netalertx:25.5.24`) as later versions don't support a full upgrade. Alternatively, devices and settings can be migrated manually, e.g. via [CSV import](./DEVICES_BULK_EDITING.md).
+> See the [Migration guide](./MIGRATION.md) for details.
 
 This guide outlines approaches for updating Docker containers, usually when upgrading to a newer version of NetAlertX. Each method offers different benefits depending on the situation. Here are the methods:
 

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
 
@@ -25,7 +25,7 @@ Follow all of the below in order to disqualify potential causes of issues and to
 
 When opening an issue or debugging:
 
-1. Include a screenshot of what you see when accessing `HTTP://<your rpi IP>/20211` (or your custom port)
+1. Include a screenshot of what you see when accessing `HTTP://<your_server>:20211` (or your custom port)
 1. [Follow steps 1, 2, 3, 4  on this page](./DEBUG_TIPS.md)
 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result:
    - `sudo apk add lsof`
@@ -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/WORKFLOWS_DEBUGGING.md

@@ -1,7 +1,7 @@
 # Workflows debugging and troubleshooting
 
 > [!TIP]
-> Before troubleshooting, please ensure you have [Debugging enabled](./DEBUG_TIPS.md).
+> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md).
 
 Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application.
 

docs/docker-troubleshooting/excessive-capabilities.md

@@ -23,7 +23,7 @@ Limit capabilities to only those required:
     - NET_ADMIN
     - NET_BIND_SERVICE
   ```
-- Remove any unnecessary `--cap-add` flags from docker run commands
+- Remove any unnecessary `--cap-add` or `--privileged` flags from docker run commands
 
 ## Additional Resources
 

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

@@ -24,9 +24,9 @@ Review and correct your volume mounts in docker-compose.yml:
 Example volume configuration:
 ```yaml
 volumes:
-  - ./data/db:/app/db
+  - ./data/db:/data/db
-  - ./data/config:/app/config
+  - ./data/config:/data/config
-  - ./data/log:/app/log
+  - ./data/log:/tmp/log
 ```
 
 ## Additional Resources

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

@@ -20,7 +20,7 @@ If you want to use a custom port, create a bind mount for the nginx configuratio
 - Add to your docker-compose.yml:
   ```yaml
   volumes:
-    - /path/to/nginx-config:/app/system/services/active/config
+    - /path/to/nginx-config:/tmp/nginx/active-config
   environment:
     - PORT=your_custom_port
   ```

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/css/app.css

@@ -70,6 +70,11 @@ a[target="_blank"] {
     opacity: 1;
 }
 
+[data-is-valid="0"] {
+    /* border: 1px solid red;  */
+    background-color: #ff4b4b !important;
+}
+
 /* -----------------------------------------------------------------------------
    Helper Classes
 ----------------------------------------------------------------------------- */

front/devices.php

@@ -1,6 +1,6 @@
 <!--
 #---------------------------------------------------------------------------------#
-#  NetAlertX                                                                       #
+#  NetAlertX                                                                      #
 #  Open Source Network Guard / WIFI & LAN intrusion detector                      #
 #                                                                                 #
 #  devices.php - Front module. Devices list page                                  #
@@ -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]);
 ?>
@@ -123,7 +136,7 @@
 <!-- page script ----------------------------------------------------------- -->
 <script>
   var deviceStatus    = 'all';
-  var tableRows       = getCache ("nax_parTableRows") == "" ? parseInt(getSetting("UI_DEFAULT_PAGE_SIZE")) : getCache ("nax_parTableRows") ;
+
   var tableOrder      = getCache ("nax_parTableOrder") == "" ? [[3,'desc'], [0,'asc']] : JSON.parse(getCache ("nax_parTableOrder")) ;
 
   var tableColumnHide = [];
@@ -550,6 +563,9 @@ function initializeDatatable (status) {
     status = 'my_devices'
   }
 
+  // retrieve page size
+  var tableRows       = getCache ("nax_parTableRows") == "" ? parseInt(getSetting("UI_DEFAULT_PAGE_SIZE")) : getCache ("nax_parTableRows") ;
+
   // Save status selected
   deviceStatus = status;
 

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","sv_sv","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","ja_jp","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  = {}
 
 
@@ -343,6 +343,9 @@ function getLangCode() {
       case 'Italian (it_it)':
         lang_code = 'it_it';
         break;
+      case 'Japanese (ja_jp)':
+        lang_code = 'ja_jp';
+        break;
       case 'Russian (ru_ru)':
         lang_code = 'ru_ru';
         break;
@@ -375,7 +378,7 @@ function localizeTimestamp(input) {
   let tz = getSetting("TIMEZONE") || 'Europe/Berlin';
   input = String(input || '').trim();
 
-  // ✅ 1. Unix timestamps (10 or 13 digits)
+  // 1. Unix timestamps (10 or 13 digits)
   if (/^\d+$/.test(input)) {
     const ms = input.length === 10 ? parseInt(input, 10) * 1000 : parseInt(input, 10);
     return new Intl.DateTimeFormat('default', {
@@ -386,39 +389,53 @@ function localizeTimestamp(input) {
     }).format(new Date(ms));
   }
 
-  // ✅ 2. European DD/MM/YYYY
+  // 2. European DD/MM/YYYY
   let match = input.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})(?:[ ,]+(\d{1,2}:\d{2}(?::\d{2})?))?(.*)$/);
   if (match) {
-    let [ , d, m, y, t = "00:00:00", tzPart = "" ] = match;
+    let [, d, m, y, t = "00:00:00", tzPart = ""] = match;
     const iso = `${y}-${m.padStart(2,'0')}-${d.padStart(2,'0')}T${t.length===5?t+":00":t}${tzPart}`;
     return formatSafe(iso, tz);
   }
 
-  // ✅ 3. US MM/DD/YYYY
+  // 3. US MM/DD/YYYY
   match = input.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})(?:[ ,]+(\d{1,2}:\d{2}(?::\d{2})?))?(.*)$/);
   if (match) {
-    let [ , m, d, y, t = "00:00:00", tzPart = "" ] = match;
+    let [, m, d, y, t = "00:00:00", tzPart = ""] = match;
     const iso = `${y}-${m.padStart(2,'0')}-${d.padStart(2,'0')}T${t.length===5?t+":00":t}${tzPart}`;
     return formatSafe(iso, tz);
   }
 
-  // ✅ 4. ISO-style (with T, Z, offsets)
+  // 4. ISO YYYY-MM-DD with optional Z/+offset
-  match = input.match(/^(\d{4}-\d{1,2}-\d{1,2})[ T](\d{1,2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:?\d{2})?$/);
+  match = input.match(/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])[ T](\d{1,2}:\d{2}(?::\d{2})?)(Z|[+-]\d{2}:?\d{2})?$/);
   if (match) {
-    let [ , ymd, time, offset = "" ] = match;
+    let [, y, m, d, time, offset = ""] = match;
-    // normalize to YYYY-MM-DD
-    let [y, m, d] = ymd.split('-').map(x => x.padStart(2,'0'));
     const iso = `${y}-${m}-${d}T${time.length===5?time+":00":time}${offset}`;
     return formatSafe(iso, tz);
   }
 
-  // ✅ 5. RFC2822 / "25 Aug 2025 13:45:22 +0200"
+  // 5. RFC2822 / "25 Aug 2025 13:45:22 +0200"
   match = input.match(/^\d{1,2} [A-Za-z]{3,} \d{4}/);
   if (match) {
     return formatSafe(input, tz);
   }
 
-  // ✅ 6. Fallback (whatever Date() can parse)
+  // 6. DD-MM-YYYY with optional time
+  match = input.match(/^(\d{1,2})-(\d{1,2})-(\d{4})(?:[ T](\d{1,2}:\d{2}(?::\d{2})?))?$/);
+  if (match) {
+    let [, d, m, y, time = "00:00:00"] = match;
+    const iso = `${y}-${m.padStart(2,'0')}-${d.padStart(2,'0')}T${time.length===5?time+":00":time}`;
+    return formatSafe(iso, tz);
+  }
+
+  // 7. Strict YYYY-DD-MM with optional time
+  match = input.match(/^(\d{4})-(0[1-9]|[12]\d|3[01])-(0[1-9]|1[0-2])(?:[ T](\d{1,2}:\d{2}(?::\d{2})?))?$/);
+  if (match) {
+    let [, y, d, m, time = "00:00:00"] = match;
+    const iso = `${y}-${m}-${d}T${time.length === 5 ? time + ":00" : time}`;
+    return formatSafe(iso, tz);
+  }
+
+  // 8. Fallback
   return formatSafe(input, tz);
 
   function formatSafe(str, tz) {
@@ -437,6 +454,7 @@ function localizeTimestamp(input) {
 }
 
 
+
 // ----------------------------------------------------
 /**
  * Replaces double quotes within single-quoted strings, then converts all single quotes to double quotes,
@@ -497,11 +515,39 @@ function isValidBase64(str) {
 // -------------------------------------------------------------------
 // Utility function to check if the value is already Base64
 function isBase64(value) {
-  const base64Regex =
+  if (typeof value !== "string" || value.trim() === "") return false;
-    /^(?:[A-Za-z0-9+\/]{4})*?(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$/;
+
-  return base64Regex.test(value);
+  // Must have valid length
+  if (value.length % 4 !== 0) return false;
+
+  // Valid Base64 characters
+  const base64Regex = /^[A-Za-z0-9+/]+={0,2}$/;
+  if (!base64Regex.test(value)) return false;
+
+
+  try {
+    const decoded = atob(value);
+
+    // Re-encode
+    const reencoded = btoa(decoded);
+
+    if (reencoded !== value) return false;
+
+    // Extra verification:
+    // Ensure decoding didn't silently drop bytes (atob bug)
+    // Encode raw bytes: check if large char codes exist (invalid UTF-16)
+    for (let i = 0; i < decoded.length; i++) {
+      const code = decoded.charCodeAt(i);
+      if (code > 255) return false; // invalid binary byte
+    }
+
+    return true;
+  } catch (e) {
+    return false;
+  }
 }
 
+
 // ----------------------------------------------------
 function isValidJSON(jsonString) {
   try {
@@ -1591,7 +1637,6 @@ async function executeOnce() {
 
   if (!isAppInitialized()) {
     try {
-      console.log("HERE");
 
       await waitForGraphQLServer(); // Wait for the server to start
 
@@ -1599,7 +1644,7 @@ async function executeOnce() {
       await cacheSettings();
       await cacheStrings();
 
-      console.log("✅ All AJAX callbacks have completed");
+      console.log("All AJAX callbacks have completed");
       onAllCallsComplete();
     } catch (error) {
       console.error("Error:", error);

front/js/modal.js

@@ -247,12 +247,19 @@ function showModalPopupForm(
     let settingsArray = [];
     if (Array.isArray(popupFormJson)) {
         popupFormJson.forEach(field => {
-            collectSetting(
+            const result = collectSetting(
                 `${parentSettingKey}_popupform`, // prefix
                 field.function,                  // setCodeName
                 field.type,                      // setType (object)
                 settingsArray
             );
+            settingsArray = result.settingsArray;
+
+            if (!result.dataIsValid) {
+                msg = getString("Gen_Invalid_Value") + ":" + result.failedSettingKey;
+                console.error(msg);
+                showModalOk("ERROR", msg);
+            }
         });
     }
 

front/js/settings_utils.js

@@ -779,6 +779,7 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => {
   let getStringKey = "";
   let onClick = "console.log('onClick - Not implemented');";
   let onChange = "console.log('onChange - Not implemented');";
+  let focusout = "console.log('focusout - Not implemented');";
   let customParams = "";
   let customId = "";
   let columns = [];
@@ -830,6 +831,9 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => {
     if (option.onChange) {
       onChange = option.onChange;
     }
+    if (option.focusout) {
+      focusout = option.focusout;
+    }
     if (option.customParams) {
       customParams = option.customParams;
     }
@@ -867,7 +871,8 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => {
     customId,
     columns,
     base64Regex,
-    elementOptionsBase64
+    elementOptionsBase64,
+    focusout
   };
 };
 
@@ -1015,6 +1020,20 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) {
 
   const { elementType, elementOptions = [], transformers = [] } = elementWithInputValue;
 
+  // Check if validation failed
+  if (
+    $(`#${setCodeName}`)
+    && $(`#${setCodeName}`).attr("data-is-valid")
+    && $(`#${setCodeName}`).attr("data-is-valid") == 0
+  )
+  {
+     return {
+      "settingsArray": settingsArray,
+      "dataIsValid": false,
+      "failedSettingKey": setCodeName
+    };
+  }
+
   const opts = handleElementOptions('none', elementOptions, transformers, val = "");
 
   // Map of handlers
@@ -1084,7 +1103,11 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) {
   const value = handlers[handlerKey]();
   settingsArray.push([prefix, setCodeName, dataType, value]);
 
-  return settingsArray;
+  return {
+    "settingsArray": settingsArray,
+    "dataIsValid": true,
+    "failedSettingKey": ""
+  };
 }
 
 
@@ -1137,7 +1160,8 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori
       customId,
       columns,
       base64Regex,
-      elementOptionsBase64
+      elementOptionsBase64,
+      focusout
     } = handleElementOptions(setKey, elementOptions, transformers, inVal);
 
     // Override value
@@ -1160,6 +1184,7 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori
         const addCss = isOrdeable ? "select2 select2-hidden-accessible" : "";
 
         inputHtml += `<select onChange="settingsChanged();${onChange}"
+                              onfocusout="${focusout}"
                               my-data-type="${dataType}"
                               my-editable="${editable}"
                               class="form-control ${addCss} ${cssClasses}"
@@ -1185,6 +1210,7 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori
         inputHtml += `<input
                         class="${inputClass} ${cssClasses}"
                         onChange="settingsChanged();${onChange}"
+                        onfocusout="${focusout}"
                         my-data-type="${dataType}"
                         my-customparams="${customParams}"
                         my-customid="${customId}"
@@ -1216,6 +1242,8 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori
       case 'textarea':
         inputHtml += `<textarea
                         class="form-control input"
+                        onChange="settingsChanged();${onChange}"
+                        onfocusout="${focusout}"
                         my-customparams="${customParams}"
                         my-customid="${customId}"
                         my-originalSetKey="${originalSetKey}"

front/js/ui_components.js

@@ -140,8 +140,11 @@ function validateRegex(elem) {
       // Validate against regex
       if (regex.test(value)) {
           iconSpan.html("<i class='fa fa-check'></i>");
+          inputElem.attr("data-is-valid", "1");
       } else {
           iconSpan.html("<i class='fa fa-xmark'></i>");
+          showModalOk('WARNING', getString("Gen_Invalid_Value"));
+          inputElem.attr("data-is-valid", "0"); 
       }
   }
 

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/multiEditCore.php

@@ -137,7 +137,8 @@
                     customId,
                     columns,
                     base64Regex,
-                    elementOptionsBase64
+                    elementOptionsBase64,
+                    focusout
                   } = handleElementOptions('none', elementOptions, transformers, val = "");
 
                   //  render based on element type

front/network.php

@@ -462,10 +462,17 @@
 
       switch (orderTopologyBy[0]) {
         case "Name":
-          const nameCompare = a.devName.localeCompare(b.devName);
+          // ensuring string
-          return nameCompare !== 0 ? nameCompare : parsePort(a.devParentPort) - parsePort(b.devParentPort);
+          const nameA = (a.devName ?? "").toString();
+          const nameB = (b.devName ?? "").toString();
+          const nameCompare = nameA.localeCompare(nameB);
+          return nameCompare !== 0
+            ? nameCompare
+            : parsePort(a.devParentPort) - parsePort(b.devParentPort);
+
         case "Port":
           return parsePort(a.devParentPort) - parsePort(b.devParentPort);
+
         default:
           return a.rowid - b.rowid;
       }
@@ -514,13 +521,17 @@ function getChildren(node, list, path, visited = [])
 
     // Loop through all items to find children of the current node
     for (var i in list) {
-        if (list[i].devParentMAC.toLowerCase() == node.devMac.toLowerCase() && !hiddenMacs.includes(list[i].devParentMAC)) {   
+      const item = list[i];
+      const parentMac = item.devParentMAC || "";       // null-safe
+      const nodeMac = node.devMac || "";               // null-safe
 
-            visibleNodesCount++;
+      if (parentMac != "" && parentMac.toLowerCase() == nodeMac.toLowerCase() && !hiddenMacs.includes(parentMac)) {
 
-            // Process children recursively, passing a copy of the visited list
+        visibleNodesCount++;
-            children.push(getChildren(list[i], list, path + ((path == "") ? "" : '|') + list[i].devParentMAC, visited));
+
-        }
+        // Process children recursively, passing a copy of the visited list
+        children.push(getChildren(list[i], list, path + ((path == "") ? "" : '|') + parentMac, visited));
+      }
     }
 
     // Track leaf and parent node counts
@@ -558,14 +569,27 @@ function getChildren(node, list, path, visited = [])
 // ---------------------------------------------------------------------------
 function getHierarchy()
 {
+  let internetNode = null;
+
   for(i in deviceListGlobal)
   {
     if(deviceListGlobal[i].devMac == 'Internet')
     {
-      return (getChildren(deviceListGlobal[i], deviceListGlobal, ''))
+      internetNode = deviceListGlobal[i];
+
+      return (getChildren(internetNode, deviceListGlobal, ''))
       break;
     }
   }
+
+  if (!internetNode) {
+    showModalOk(
+      getString('Network_Configuration_Error'),
+      getString('Network_Root_Not_Configured')
+    );
+    console.error("getHierarchy(): Internet node not found");
+    return null;
+  }
 }
 
 //---------------------------------------------------------------------------
@@ -664,8 +688,6 @@ function handleNodeClick(el)
 
 // ---------------------------------------------------------------------------
 var myTree;
-
-
 var emSize;
 var nodeHeight;
 // var sizeCoefficient = 1.4
@@ -682,140 +704,139 @@ function emToPx(em, element) {
 
 function initTree(myHierarchy)
 {
-  // calculate the drawing area based on teh tree width and available screen size
+  if(myHierarchy && myHierarchy.type !== "")
-  
-  let baseFontSize = parseFloat($('html').css('font-size')); 
-  let treeAreaHeight = ($(window).height() - 155); ;
-  // calculate the font size of the leaf nodes to fit everything into the tree area
-  leafNodesCount == 0 ? 1 : leafNodesCount;
-
-  emSize = pxToEm((treeAreaHeight/(leafNodesCount)).toFixed(2));
-  
-  let screenWidthEm = pxToEm($('.networkTable').width()-15);
-
-  // init the drawing area size
-  $("#networkTree").attr('style', `height:${treeAreaHeight}px; width:${emToPx(screenWidthEm)}px`)
-
-  if(myHierarchy.type == "")
   {
-    showModalOk(getString('Network_Configuration_Error'), getString('Network_Root_Not_Configured'))      
+    // calculate the drawing area based on the tree width and available screen size
+    let baseFontSize = parseFloat($('html').css('font-size'));
+    let treeAreaHeight = ($(window).height() - 155); ;
 
-    return;
+    // calculate the font size of the leaf nodes to fit everything into the tree area
-  }
+    leafNodesCount == 0 ? 1 : leafNodesCount;
 
-  // handle canvas and node size if only a few nodes
+    emSize = pxToEm((treeAreaHeight/(leafNodesCount)).toFixed(2));
-  emSize > 1 ? emSize = 1 : emSize = emSize;
 
-  let nodeHeightPx = emToPx(emSize*1);
+    let screenWidthEm = pxToEm($('.networkTable').width()-15);
-  let nodeWidthPx = emToPx(screenWidthEm / (parentNodesCount));
 
-  // handle if only a few nodes
+    // init the drawing area size
-  nodeWidthPx > 160 ? nodeWidthPx = 160 : nodeWidthPx = nodeWidthPx;
+    $("#networkTree").attr('style', `height:${treeAreaHeight}px; width:${emToPx(screenWidthEm)}px`)
 
-  console.log(Treeviz);
+    // handle canvas and node size if only a few nodes
+    emSize > 1 ? emSize = 1 : emSize = emSize;
 
-  myTree = Treeviz.create({
+    let nodeHeightPx = emToPx(emSize*1);
-    htmlId: "networkTree",
+    let nodeWidthPx = emToPx(screenWidthEm / (parentNodesCount));
-    renderNode:  nodeData =>  {
 
-      (!emptyArr.includes(nodeData.data.port )) ? port =  nodeData.data.port : port = "";
+    // handle if only a few nodes
+    nodeWidthPx > 160 ? nodeWidthPx = 160 : nodeWidthPx = nodeWidthPx;
 
-      (port == "" || port == 0 || port == 'None' ) ? portBckgIcon = `<i class="fa fa-wifi"></i>` : portBckgIcon = `<i class="fa fa-ethernet"></i>`;
+    console.log(Treeviz);
 
-      portHtml = (port == "" || port == 0 || port == 'None' ) ? " &nbsp " : port;
+    myTree = Treeviz.create({
+      htmlId: "networkTree",
+      renderNode:  nodeData =>  {
 
-      // Build HTML for individual nodes in the network diagram        
+        (!emptyArr.includes(nodeData.data.port )) ? port =  nodeData.data.port : port = "";
-      deviceIcon = (!emptyArr.includes(nodeData.data.icon )) ?  
-                `<div class="netIcon">
-                      ${atob(nodeData.data.icon)}
-                </div>` : "";
-      devicePort = `<div  class="netPort" 
-                          style="width:${emSize}em;height:${emSize}em">
-                      ${portHtml}</div> 
-                    <div  class="portBckgIcon" 
-                          style="margin-left:-${emSize*0.7}em;">
-                          ${portBckgIcon}
-                    </div>`;
-      collapseExpandIcon = nodeData.data.hiddenChildren ? 
-                          "square-plus" : "square-minus";
 
-      // generate +/- icon if node has children nodes
+        (port == "" || port == 0 || port == 'None' ) ? portBckgIcon = `<i class="fa fa-wifi"></i>` : portBckgIcon = `<i class="fa fa-ethernet"></i>`;
-      collapseExpandHtml = nodeData.data.hasChildren ? 
-                    `<div class="netCollapse" 
-                          style="font-size:${nodeHeightPx/2}px;top:${Math.floor(nodeHeightPx / 4)}px" 
-                          data-mytreepath="${nodeData.data.path}" 
-                          data-mytreemac="${nodeData.data.mac}">
-                      <i class="fa fa-${collapseExpandIcon} pointer"></i>
-                    </div>` : "";
 
-      selectedNodeMac = $(".nav-tabs-custom .active a").attr('data-mytabmac')
+        portHtml = (port == "" || port == 0 || port == 'None' ) ? " &nbsp " : port;
 
-      highlightedCss = nodeData.data.mac == selectedNodeMac ? 
+        // Build HTML for individual nodes in the network diagram
-                    " highlightedNode " : "";
+        deviceIcon = (!emptyArr.includes(nodeData.data.icon )) ?
-      cssNodeType = nodeData.data.devIsNetworkNodeDynamic  ? 
+                  `<div class="netIcon">
-                    " node-network-device " : " node-standard-device ";
+                        ${atob(nodeData.data.icon)}
+                  </div>` : "";
+        devicePort = `<div  class="netPort"
+                            style="width:${emSize}em;height:${emSize}em">
+                        ${portHtml}</div>
+                      <div  class="portBckgIcon"
+                            style="margin-left:-${emSize*0.7}em;">
+                            ${portBckgIcon}
+                      </div>`;
+        collapseExpandIcon = nodeData.data.hiddenChildren ?
+                            "square-plus" : "square-minus";
 
-      networkHardwareIcon = nodeData.data.devIsNetworkNodeDynamic ? `<span class="network-hw-icon">
+        // generate +/- icon if node has children nodes
-                                <i class="fa-solid fa-hard-drive"></i>
+        collapseExpandHtml = nodeData.data.hasChildren ?
-                            </span>` : "";
+                      `<div class="netCollapse"
+                            style="font-size:${nodeHeightPx/2}px;top:${Math.floor(nodeHeightPx / 4)}px"
+                            data-mytreepath="${nodeData.data.path}"
+                            data-mytreemac="${nodeData.data.mac}">
+                        <i class="fa fa-${collapseExpandIcon} pointer"></i>
+                      </div>` : "";
 
-      const badgeConf = getStatusBadgeParts(nodeData.data.presentLastScan, nodeData.data.alertDown, nodeData.data.mac, statusText = '')
+        selectedNodeMac = $(".nav-tabs-custom .active a").attr('data-mytabmac')
 
-      return result = `<div 
+        highlightedCss = nodeData.data.mac == selectedNodeMac ?
-                            class="node-inner hover-node-info box pointer ${highlightedCss} ${cssNodeType}"
+                      " highlightedNode " : "";
-                            style="height:${nodeHeightPx}px;font-size:${nodeHeightPx-5}px;"
+        cssNodeType = nodeData.data.devIsNetworkNodeDynamic  ?
-                            onclick="handleNodeClick(this)"
+                      " node-network-device " : " node-standard-device ";
-                            data-mac="${nodeData.data.mac}"                            
+
-                            data-parentMac="${nodeData.data.parentMac}"                            
+        networkHardwareIcon = nodeData.data.devIsNetworkNodeDynamic ? `<span class="network-hw-icon">
-                            data-name="${nodeData.data.name}"
+                                  <i class="fa-solid fa-hard-drive"></i>
-                            data-ip="${nodeData.data.ip}"
+                              </span>` : "";
-                            data-mac="${nodeData.data.mac}"
+
-                            data-vendor="${nodeData.data.vendor}"
+        const badgeConf = getStatusBadgeParts(nodeData.data.presentLastScan, nodeData.data.alertDown, nodeData.data.mac, statusText = '')
-                            data-type="${nodeData.data.type}"
+
-                            data-devIsNetworkNodeDynamic="${nodeData.data.devIsNetworkNodeDynamic}"
+        return result = `<div
-                            data-lastseen="${nodeData.data.lastseen}"
+                              class="node-inner hover-node-info box pointer ${highlightedCss} ${cssNodeType}"
-                            data-firstseen="${nodeData.data.firstseen}"
+                              style="height:${nodeHeightPx}px;font-size:${nodeHeightPx-5}px;"
-                            data-relationship="${nodeData.data.relType}"
+                              onclick="handleNodeClick(this)"
-                            data-status="${nodeData.data.status}"
+                              data-mac="${nodeData.data.mac}"
-                            data-present="${nodeData.data.presentLastScan}"
+                              data-parentMac="${nodeData.data.parentMac}"
-                            data-alert="${nodeData.data.alertDown}"
+                              data-name="${nodeData.data.name}"
-                            data-icon="${nodeData.data.icon}"
+                              data-ip="${nodeData.data.ip}"
-                        >
+                              data-mac="${nodeData.data.mac}"
-                          <div class="netNodeText">
+                              data-vendor="${nodeData.data.vendor}"
-                            <strong><span>${devicePort}  <span class="${badgeConf.cssText}">${deviceIcon}</span></span>
+                              data-type="${nodeData.data.type}"
-                              <span class="spanNetworkTree anonymizeDev" style="width:${nodeWidthPx-50}px">${nodeData.data.name}</span>
+                              data-devIsNetworkNodeDynamic="${nodeData.data.devIsNetworkNodeDynamic}"
-                              ${networkHardwareIcon}
+                              data-lastseen="${nodeData.data.lastseen}"
-                            </strong>                            
+                              data-firstseen="${nodeData.data.firstseen}"
+                              data-relationship="${nodeData.data.relType}"
+                              data-status="${nodeData.data.status}"
+                              data-present="${nodeData.data.presentLastScan}"
+                              data-alert="${nodeData.data.alertDown}"
+                              data-icon="${nodeData.data.icon}"
+                          >
+                            <div class="netNodeText">
+                              <strong><span>${devicePort}  <span class="${badgeConf.cssText}">${deviceIcon}</span></span>
+                                <span class="spanNetworkTree anonymizeDev" style="width:${nodeWidthPx-50}px">${nodeData.data.name}</span>
+                                ${networkHardwareIcon}
+                              </strong>
+                            </div>
                           </div>
-                        </div>
+                          ${collapseExpandHtml}`;
-                        ${collapseExpandHtml}`;
+      },
-    },
+      mainAxisNodeSpacing: 'auto',
-    mainAxisNodeSpacing: 'auto',
+      // secondaryAxisNodeSpacing: 0.3,
-    // secondaryAxisNodeSpacing: 0.3,
+      nodeHeight: nodeHeightPx,
-    nodeHeight: nodeHeightPx,
+      nodeWidth: nodeWidthPx,
-    nodeWidth: nodeWidthPx,
+      marginTop: '5',
-    marginTop: '5',
+      isHorizontal : true,
-    isHorizontal : true,
+      hasZoom: true,
-    hasZoom: true,
+      hasPan: true,
-    hasPan: true,
+      marginLeft: '10',
-    marginLeft: '10',
+      marginRight: '10',
-    marginRight: '10',
+      idKey: "mac",
-    idKey: "mac",
+      hasFlatData: false,
-    hasFlatData: false,
+      relationnalField: "children",
-    relationnalField: "children",
+      linkWidth: (nodeData) => 2,
-    linkWidth: (nodeData) => 2,
+      linkColor: (nodeData) => {
-    linkColor: (nodeData) => {  
+        relConf = getRelationshipConf(nodeData.data.relType)
-      relConf = getRelationshipConf(nodeData.data.relType)  
+        return relConf.color;
-      return relConf.color;
+      }
-    }
+      // onNodeClick: (nodeData) => handleNodeClick(nodeData),
-    // onNodeClick: (nodeData) => handleNodeClick(nodeData),
+    });
-  });      
 
-  console.log(deviceListGlobal);
+    console.log(deviceListGlobal);
-  myTree.refresh(myHierarchy);
+    myTree.refresh(myHierarchy);
 
-  // hide spinning icon
+    // hide spinning icon
-  hideSpinner()
+    hideSpinner()
+  } else
+  {
+    console.error("getHierarchy() not returning expected result");
+  }
 }
 
 

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('cron.log', 'cleanLog')"
+            }
+        ],
+    "fileName": "cron.log",
+    "filePath": "__NETALERTX_LOG__/cron.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', 'cron.log'];
 
   if(in_array($logFile, $allowedFiles))
   {
@@ -292,7 +303,7 @@ function saveSettings()
 
   // save to the file
   $new_name = $config_file.'_'.$timestamp.'.backup';
-  $new_location = $configFolderPath.$new_name;
+  $new_location = $configFolderPath.'/'.$new_name;
 
   if(file_exists( $fullConfPath) != 1)
   {
@@ -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]);