From 0035834c54aac53953037acd09f011509702b2c0 Mon Sep 17 00:00:00 2001
From: jokob-sk <jokob.sk@gmail.com>
Date: Sun, 18 Jan 2026 08:01:09 +1100
Subject: [PATCH] GIT+DOCS: workflows - ensure old images + v25.11.29 migration

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
---
 .github/workflows/docker_prod.yml             |  1 +
 docs/MIGRATION.md                             | 48 ++++++++++++++++++-
 .../aufs-capabilities.md                      |  2 +-
 .../docker-troubleshooting/running-as-root.md |  3 ++
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docker_prod.yml b/.github/workflows/docker_prod.yml
index 99884613..978c1dc4 100755
--- a/.github/workflows/docker_prod.yml
+++ b/.github/workflows/docker_prod.yml
@@ -67,6 +67,7 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: |
+            ghcr.io/netalertx/netalertx
             ghcr.io/jokob-sk/netalertx
             jokobsk/netalertx
           tags: |
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 9e39e5ba..9c47bc58 100755
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -16,6 +16,9 @@ When upgrading from older versions of NetAlertX (or PiAlert by jokob-sk), follow
 - You are running NetAlertX (by jokob-sk) (`v25.6.7` to `v25.10.1`)
   → [Read the 1.3 Migration from NetAlertX `v25.10.1`](#13-migration-from-netalertx-v25101)
 
+- You are running NetAlertX (by jokob-sk) (`v25.11.29`)
+  → [Read the 1.4 Migration from NetAlertX `v25.11.29`](#14-migration-from-netalertx-v251129)
+
 
 ### 1.0 Manual Migration
 
@@ -296,6 +299,49 @@ sudo chown -R 20211:20211 /local_data_dir
 sudo chmod -R a+rwx /local_data_dir
 ```
 
-8. Start the container and verify everything works as expeexpected.
+8. Start the container and verify everything works as expected.
 9. Check the [Permissions -> Writable-paths](https://docs.netalertx.com/FILE_PERMISSIONS/#writable-paths) what directories to mount if you'd like to access the API or log files.
 
+
+### 1.4 Migration from NetAlertX `v25.11.29`
+
+As per user feedback, we’ve re-introduced the ability to control which user the application runs as via the `PUID` and `PGID` environment variables. This required additional changes to the container to safely handle permission adjustments at runtime.
+
+#### STEPS:
+
+1. Stop the container
+2. [Back up your setup](./BACKUPS.md)
+3. Stop the container
+4. Update the `docker-compose.yml` as per example below.
+
+```yaml
+services:
+  netalertx:
+    container_name: netalertx
+    image: "ghcr.io/jokob-sk/netalertx"
+    network_mode: "host"
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_RAW
+      - NET_ADMIN
+      - NET_BIND_SERVICE
+      - CHOWN                # 🆕 New line
+      - SETUID               # 🆕 New line
+      - SETGID               # 🆕 New line
+    restart: unless-stopped
+    volumes:
+      - /local_data_dir:/data
+      # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - PORT=20211
+      # - PUID=0    # New optional variable to run as root
+      # - GUID=100  # New optional variable to run as root
+    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"
+```
+
+5. If you use a custom `PUID` (e.g. `0`) and `GUID` (e.g. `100`) make sure you also update the `tmpfs` ownership, e.g. `/tmp:uid=0,gid=100...`
+6. Start the container and verify everything works as expected.
diff --git a/docs/docker-troubleshooting/aufs-capabilities.md b/docs/docker-troubleshooting/aufs-capabilities.md
index 438c195d..cfa81951 100644
--- a/docs/docker-troubleshooting/aufs-capabilities.md
+++ b/docs/docker-troubleshooting/aufs-capabilities.md
@@ -30,7 +30,7 @@ When AUFS is detected without root privileges, the system emits the following wa
 >
 > AUFS strips Linux file capabilities, so tools like arp-scan, nmap, and nbtscan fail when NetAlertX runs as a non-root PUID.
 >
-> **Action:** Set PUID=0 on AUFS hosts for full functionality.
+> **Action:** Set `PUID=0` on AUFS hosts for full functionality.
 
 
 ## Security Ramifications
diff --git a/docs/docker-troubleshooting/running-as-root.md b/docs/docker-troubleshooting/running-as-root.md
index 390febe2..16faa489 100644
--- a/docs/docker-troubleshooting/running-as-root.md
+++ b/docs/docker-troubleshooting/running-as-root.md
@@ -1,5 +1,8 @@
 # Running as Root User
 
+> [!TIP]
+> Looking for how to run the container as root? See the [File permissions documentation](../FILE_PERMISSIONS.md) for details.
+
 ## Issue Description
 
 NetAlertX has detected that the container is running with root privileges (UID 0). This configuration bypasses all built-in security hardening measures designed to protect your system.