docs

nax_pyunifi.controller not found

.dockerignore

@@ -6,14 +6,10 @@
 docker-compose.yml
 Dockerfile
 Dockerfile.debian
-dockerfiles/LICENSE
-dockerfiles/README.md
-dockerfiles/README_ES.md
 docs
 LICENSE.txt
 README.md
 CONTRIBUTING
 FUNDING.yml
 config/.gitignore
-db/.gitignore
-
+db/.gitignore

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: jokob-sk
+patreon: 84385063
+buy_me_a_coffee: jokobsk

.github/ISSUE_TEMPLATE/documentation-feedback.yml

@@ -0,0 +1,56 @@
+name: Documentation Feedback 📝
+description: Suggest improvements, clarify inconsistencies, or report issues related to the documentation.
+labels: ['documentation 📚']
+body:
+- type: checkboxes
+  attributes:
+    label: Is there an existing issue for this?
+    description: Please search to see if an open or closed issue already exists for the documentation change you're suggesting.
+    options:
+      - label: I have searched the existing open and closed issues
+        required: true
+- type: textarea
+  attributes:
+    label: What document or section does this relate to?
+    description: |
+      Please include a link to the file and section, if applicable. Be specific about what part of the documentation you are referencing.
+    placeholder: e.g. https://github.com/jokob-sk/NetAlertX/blob/main/docs/FRONTEND_DEVELOPMENT.md
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Describe the issue
+    description: A clear and concise explanation of the issue or inconsistency you found in the documentation.
+    placeholder: e.g. The linked file is referred to as "Contributor Guidelines" but only covers frontend topics.
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Your suggestion or proposed solution
+    description: Suggest how the documentation could be improved, clarified, or reorganized.
+    placeholder: e.g. Combine frontend and backend development into a single CONTRIBUTING.md file with common sections to reduce fragmentation.
+  validations:
+    required: true
+- type: checkboxes
+  attributes:
+    label: What type of issue is this?
+    options:
+      - label: Missing information
+      - label: Inaccurate or outdated information
+      - label: Unclear or confusing content
+      - label: Structure or organization improvements
+      - label: Other (explain in issue)
+- type: textarea
+  attributes:
+    label: Anything else?
+    description: |
+      Additional context, references, screenshots, or related issues. You can also mention if you’re willing to help implement the suggestion.
+  validations:
+    required: false
+- type: checkboxes
+  attributes:
+    label: Can I help implement this? 👩‍💻👨‍💻 
+    description: The maintainer can provide guidance and review your changes.
+    options:
+      - label: "Yes, I’d like to help implement the improvement"
+      - label: "No, I’m just suggesting the idea"

.github/ISSUE_TEMPLATE/enhancement-request.yml

@@ -0,0 +1,33 @@
+name: Enhancement Request
+description: Propose an improvement to an existing feature or UX behavior.
+labels: ['enhancement ♻️']
+body:
+- type: checkboxes
+  attributes:
+    label: Is there an existing issue for this?
+    options:
+      - label: I have searched existing open and closed issues
+        required: true
+- type: textarea
+  attributes:
+    label: What is the enhancement?
+    description: Describe the change or optimization you’d like to see to an existing feature.
+    placeholder: e.g. Make scan intervals configurable from UI instead of just `app.conf`
+    required: true
+- type: textarea
+  attributes:
+    label: What problem does this solve or improve?
+    description: Describe why this change would improve user experience or project maintainability.
+    required: true
+- type: textarea
+  attributes:
+    label: Additional context or examples
+    description: |
+      Screenshots? Comparisons? Reference repos?
+    required: false
+- type: checkboxes
+  attributes:
+    label: Are you willing to help implement this?
+    options:
+      - label: "Yes"
+      - label: "No"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,6 +1,6 @@
 name: Feature Request
 description: 'Suggest an idea for NetAlertX'
-labels: ['Feature request➕']
+labels: ['Feature request ➕']
 body:
 - type: checkboxes
   attributes:
@@ -46,7 +46,7 @@ body:
 - type: checkboxes
   attributes:
     label: Can I help implement this? 👩‍💻👨‍💻 
-    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs
+    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://jokob-sk.github.io/NetAlertX/DEV_ENV_SETUP/
     options:
     - label: "Yes"
     - label: "No"

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

@@ -7,8 +7,18 @@ body:
     label: Is there an existing issue for this?
     description: Please search to see if an open or closed issue already exists for the bug you encountered.
     options:
-    - label: I have searched the existing open and closed issues and I checked the docs https://github.com/jokob-sk/NetAlertX/tree/main/docs
+    - label: I have searched the existing open and closed issues and I checked the docs https://jokob-sk.github.io/NetAlertX/
       required: true
+- type: checkboxes
+  attributes:
+    label: The issue occurs in the following browsers. Select at least 2.
+    description: This step helps me understand if this is a cache or browser-specific issue. 
+    options:
+    - label: "Firefox"
+    - label: "Chrome"
+    - label: "Edge"
+    - label: "Safari (unsupported) - PRs welcome"
+    - label: "N/A - This is an issue with the backend"
 - type: textarea
   attributes:
     label: Current Behavior
@@ -49,11 +59,15 @@ body:
   validations:
     required: false
 - type: dropdown
+  id: installation_type
   attributes:
-    label: What branch are you running?
+    label: What installation are you running?
     options:
-      - Production
-      - Dev
+      - Production (netalertx)
+      - Dev (netalertx-dev)
+      - Home Assistant (addon)
+      - Home Assistant fa (full-access addon)
+      - Bare-metal (community only support - Check Discord)
   validations:
     required: true
 - type: textarea
@@ -64,7 +78,7 @@ body:
       ***Generally speaking, all bug reports should have logs provided.***
       Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
       Additionally, any additional info? Screenshots? References? Anything that will give us more context about the issue you are encountering!
-      You can use `tail -100 /app/front/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. 
   validations:
     required: false
 - type: checkboxes

.github/ISSUE_TEMPLATE/refactor-codequality-request.yml

@@ -0,0 +1,37 @@
+name: Refactor / Code Quality Request ♻️
+description: Suggest improvements to code structure, style, or maintainability.
+labels: ['enhancement ♻️']
+body:
+- type: checkboxes
+  attributes:
+    label: Is there an existing issue for this?
+    description: Please check if a similar request already exists.
+    options:
+      - label: I have searched the existing open and closed issues
+        required: true
+- type: textarea
+  attributes:
+    label: What part of the code needs refactoring or improvement?
+    description: Specify files, modules, or components.
+    required: true
+- type: textarea
+  attributes:
+    label: Describe the proposed changes
+    description: Explain the refactoring or quality improvements you suggest.
+    required: true
+- type: textarea
+  attributes:
+    label: Why is this improvement needed?
+    description: Benefits such as maintainability, readability, performance, or scalability.
+    required: true
+- type: textarea
+  attributes:
+    label: Additional context or examples
+    description: Any relevant links, references, or related issues.
+    required: false
+- type: checkboxes
+  attributes:
+    label: Can you help implement this change?
+    options:
+      - label: Yes
+      - label: No

.github/ISSUE_TEMPLATE/security-report.yml

@@ -0,0 +1,28 @@
+name: Security Report 🔐
+description: Report a security vulnerability or concern privately.
+labels: ['security 🔐']
+body:
+- type: markdown
+  attributes:
+    value: |
+      **Important:** For security reasons, please do **not** post sensitive security issues publicly in the issue tracker.
+      Instead, send details to our security contact email: [jokob@duck.com](mailto:jokob@duck.com).
+      
+      We appreciate your responsible disclosure.
+- type: textarea
+  attributes:
+    label: Brief summary (non-sensitive)
+    description: Provide a non-sensitive overview of the security issue.
+    required: true
+- type: textarea
+  attributes:
+    label: Additional context or references
+    description: Any other information or related reports.
+    required: false
+- type: checkboxes
+  attributes:
+    label: Have you sent this report via email to the security contact?
+    options:
+      - label: Yes, I have sent the details to jokob@duck.com
+        required: true
+      - label: Not yet, I will send it after opening this issue

.github/ISSUE_TEMPLATE/setup-help.yml

@@ -0,0 +1,75 @@
+name: Setup help
+description: 'When submitting an issue enable LOG_LEVEL="trace" and re-search first.'
+labels: ['Setup 📥']
+body:
+- type: checkboxes
+  attributes:
+    label: Did I research?
+    description: Please confirm you checked the usual places before opening a setup support request.
+    options:
+    - label: I have searched the docs https://jokob-sk.github.io/NetAlertX/
+      required: true
+    - label: I have searched the existing open and closed issues
+      required: true
+    - label: I confirm my SCAN_SUBNETS is configured and tested as per https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md
+      required: true
+- type: checkboxes
+  attributes:
+    label: The issue occurs in the following browsers. Select at least 2.
+    description: This step helps me understand if this is a cache or browser-specific issue. 
+    options:
+    - label: "Firefox"
+    - label: "Chrome"
+    - label: "Other (unsupported) - PRs welcome"
+    - label: "N/A - This is an issue with the backend"
+- type: textarea
+  attributes:
+    label: What I want to do
+    description: Describe what you want to achieve.
+  validations:
+    required: false
+- type: textarea
+  attributes:
+    label: Relevant settings you changed
+    description: |
+      Paste a screenshot or setting values of the settings you changed. 
+  validations:
+    required: false
+- type: textarea
+  attributes:
+    label: docker-compose.yml
+    description: |
+      Paste your `docker-compose.yml`    
+    render: python
+  validations:
+    required: false
+- type: dropdown
+  id: installation_type
+  attributes:
+    label: What installation are you running?
+    options:
+      - Production (netalertx)
+      - Dev (netalertx-dev)
+      - Home Assistant (addon)
+      - Home Assistant fa (full-access addon)
+      - Bare-metal (community only support - Check Discord)
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: app.log
+    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. 
+  validations:
+    required: false
+- type: checkboxes
+  attributes:
+    label: Debug enabled
+    description: I confirm I enabled `debug`
+    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

.github/ISSUE_TEMPLATE/translation-request.yml

@@ -0,0 +1,36 @@
+name: Translation / Localization Request 🌐
+description: Suggest adding or improving translations or localization support.
+labels: ['enhancement 🌐']
+body:
+- type: checkboxes
+  attributes:
+    label: Have you checked for existing translation efforts or related issues?
+    options:
+      - label: I have searched existing open and closed issues
+        required: true
+- type: textarea
+  attributes:
+    label: Language(s) involved
+    description: Specify the language(s) this request pertains to.
+    required: true
+- type: textarea
+  attributes:
+    label: Describe the translation or localization improvement
+    description: Examples include adding new language support, fixing translation errors, or improving formatting.
+    required: true
+- type: textarea
+  attributes:
+    label: Why is this important for the project or users?
+    description: Describe the benefits or target audience.
+    required: false
+- type: textarea
+  attributes:
+    label: Additional context or references
+    description: Link to files, previous translation PRs, or external resources.
+    required: false
+- type: checkboxes
+  attributes:
+    label: Can you help with translation or review?
+    options:
+      - label: Yes
+      - label: No

.github/PULL_REQUEST_TEMPLATE/code-pr-template.md

@@ -0,0 +1,53 @@
+## 📌 Description
+
+<!-- Provide a brief description of the changes you're introducing. Be clear and concise. -->
+
+---
+
+## 🔍 Related Issues
+
+<!-- Reference any related issues (e.g., closes #123, fixes #456) -->
+
+---
+
+## 📋 Type of Change
+
+Please check the relevant option(s):
+
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] ♻️ Code refactor
+- [ ] 📚 Documentation update
+- [ ] 🧪 Test addition or change
+- [ ] 🔧 Build/config update
+- [ ] 🚀 Performance improvement
+- [ ] 🔨 CI/CD or automation
+- [ ] 🧹 Cleanup / chore
+
+---
+
+## 📷 Screenshots or Logs (if applicable)
+
+<!-- Add screenshots, terminal output, logs, or anything that helps understand your change -->
+
+---
+
+## 🧪 Testing Steps
+
+<!-- Describe how the change was tested. Manual steps, test cases, or automated test runs -->
+
+---
+
+## ✅ Checklist
+
+- [ ] I have read the [Contribution Guidelines](../../CONTRIBUTING)
+- [ ] I have tested my changes locally
+- [ ] I have updated relevant documentation (if applicable)
+- [ ] I have verified my changes do not break existing behavior
+- [ ] I am willing to respond to requested changes and feedback
+
+---
+
+## 🙋 Additional Notes
+
+<!-- Anything else you want reviewers to know? Future follow-ups? Questions? -->

.github/PULL_REQUEST_TEMPLATE/docs-pr-template.md

@@ -0,0 +1,37 @@
+## 📚 Documentation Update
+
+<!-- Describe the purpose of this PR in one or two sentences. Example: "This PR updates the contributor guidelines by merging frontend and backend sections." -->
+
+---
+
+## 📝 What’s Changed?
+
+<!-- Briefly outline what parts of the documentation were added, changed, removed, or reorganized -->
+
+- Combined frontend and backend development guidelines into a single file
+- Updated `mkdocs.yml` to reflect new structure
+- Added clarification on contribution process
+- Fixed outdated links in sidebar
+
+---
+
+## 🔍 Related Issue(s)
+
+<!-- Link to related issues, discussions, or context (e.g., closes #123) -->
+
+---
+
+## ✅ Checklist
+
+- [ ] I followed the formatting/style of existing documentation
+- [ ] I have read the [Contribution Guidelines](../../CONTRIBUTING)
+- [ ] I updated `mkdocs.yml` if necessary
+- [ ] I verified links and references still work
+- [ ] I checked that my changes improve clarity, structure, or accuracy
+- [ ] I'm open to feedback and suggestions
+
+---
+
+## 🙋 Additional Notes
+
+<!-- Optional: Include anything you want reviewers to be aware of -->

.github/tweet.md

@@ -0,0 +1,2 @@
+🎉 New release: **v25.7.3 - 🌍 Arabic translation and various fixes** is live! 🚀
+Check it out here: https://github.com/jokob-sk/NetAlertX/releases/tag/v25.7.3

.github/workflows/code_checks.yml

@@ -0,0 +1,41 @@
+name: Code checks
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*.*.*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-url-paths:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for incorrect absolute '/php/' URLs in frontend code
+        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
+
+          if [ -n "$MATCHES" ]; then
+            echo "$MATCHES"
+            echo "❌ Found incorrectly absolute '/php/' URLs. Use 'php/' or './php/' for relative paths."
+            exit 1
+          else
+            echo "✅ No bad '/php/' URLs found."
+          fi
+
+
+
+      - name: Check Python syntax
+        run: |
+          set -e
+          echo "🔍 Checking Python syntax..."
+          find . -name "*.py" -print0 | xargs -0 -n1 python3 -m py_compile
+

.github/workflows/docker_dev.yml

@@ -1,15 +1,14 @@
----
 name: docker
 
 on:
   push:
     branches:
-      - '**'
+      - main
     tags:
       - '*.*.*'
   pull_request:
     branches:
-      - master
+      - main
 
 jobs: 
   docker_dev:
@@ -37,7 +36,7 @@ jobs:
 
       - name: Get release version
         id: get_version
-        run: echo "::set-output name=version::${{ 'Dev' }}"
+        run: echo "version=Dev" >> $GITHUB_OUTPUT
 
       - name: Create .VERSION file
         run: echo "${{ steps.get_version.outputs.version }}" >> .VERSION
@@ -46,13 +45,11 @@ jobs:
         id: meta
         uses: docker/metadata-action@v4
         with:
-          # list of Docker images to use as base name for tags
           images: |
+            ghcr.io/jokob-sk/netalertx-dev
             jokobsk/netalertx-dev
-          # generate Docker tags based on the following events/attributes
           tags: |
             type=raw,value=latest
-            type=schedule
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}
@@ -60,24 +57,20 @@ jobs:
             type=semver,pattern={{major}}
             type=sha
 
-      - 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:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      # # Disable this after use
-      # - name: Prune Docker Builder
-      #   run: docker builder prune --force
-
       - name: Build and push
         uses: docker/build-push-action@v3
         with:
@@ -86,6 +79,3 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          # # ⚠ disable cache if build is failing to download debian packages
-          # cache-from: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache
-          # cache-to: type=registry,ref=ghcr.io/jokob-sk/netalertx:buildcache,mode=max

.github/workflows/docker_prod.yml

@@ -48,8 +48,8 @@ jobs:
         with:
           # list of Docker images to use as base name for tags
           images: |
-            jokobsk/pi.alert
-            jokobsk/netalertx
+            ghcr.io/jokob-sk/netalertx
+            jokobsk/netalertx  
           # generate Docker tags based on the following events/attributes
           tags: |
             type=semver,pattern={{version}},value=${{ inputs.version }}

.github/workflows/label-issues.yml

@@ -0,0 +1,43 @@
+name: Label Issues by Installation Type
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  add-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get issue content
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.issue.body;
+
+            const lowerBody = body.toLowerCase();
+
+            let labelsToAdd = [];
+
+            if (lowerBody.includes('bare-metal')) {
+              labelsToAdd.push('bare-metal ❗');
+            }
+
+            if (lowerBody.includes('home assistant')) {
+              labelsToAdd.push('Home Assistant 🏠');
+            }
+
+            if (lowerBody.includes('production (netalertx)') || lowerBody.includes('dev (netalertx-dev)')) {
+              labelsToAdd.push('Docker 🐋');
+            }
+
+            if (labelsToAdd.length > 0) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: labelsToAdd
+              });
+            }

.github/workflows/mkdocs.yml

@@ -0,0 +1,25 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main  # Change if your default branch is different
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+
+      - name: Install MkDocs
+        run: |
+          pip install mkdocs mkdocs-material && pip install mkdocs-github-admonitions-plugin 
+
+      - name: Deploy MkDocs
+        run: mkdocs gh-deploy --force

.github/workflows/social_post_on_release.yml

@@ -0,0 +1,53 @@
+name: 📧 Twitter and Discord Posts
+on:
+  release:
+    types: [published]
+
+jobs:
+  post-discord:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Wait for 15 minutes
+        run: sleep 900  # 15 minutes delay
+
+      - name: Post to Discord
+        run: |
+          curl -X POST -H "Content-Type: application/json" \
+          -d '{"content": "🎉 New release: **${{ github.event.release.name }}** is live! 🚀\nCheck it out here: ${{ github.event.release.html_url }}"}' \
+          ${{ secrets.DISCORD_WEBHOOK_URL }}
+
+  post-twitter:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Wait for 15 minutes
+        run: sleep 900  # 15 minutes delay     
+
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set Git config
+        run: |
+          git config --global user.email "github-actions@github.com"
+          git config --global user.name "GitHub Actions"
+
+      - name: Create tweet file
+        run: |
+          echo "🎉 New release: **${{ github.event.release.name }}** is live! 🚀" > .github/tweet.md
+          echo "Check it out here: ${{ github.event.release.html_url }}" >> .github/tweet.md
+          git add .github/tweet.md
+          git commit -m "Add release tweet for ${{ github.event.release.name }}"
+
+      - name: Push changes
+        run: |
+          git push https://github.com/${{ github.repository }}.git HEAD:main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tweet
+        uses: twitter-together/action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
+          TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
+          TWITTER_API_KEY: ${{ secrets.TWITTER_API_KEY }}
+          TWITTER_API_SECRET_KEY: ${{ secrets.TWITTER_API_SECRET_KEY }}

.github/workflows/update_sponsors_table.yml

@@ -1,29 +0,0 @@
-name: 🤖Automation - Update Sponsors Table
-
-on:
-  schedule:
-    - cron: '50 11 * * *' # Set your preferred schedule (UTC)
-
-jobs:
-  update-table:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.8
-
-      - name: Install Dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r update_sponsors_requirements.txt  # If you have any Python dependencies
-
-      - name: Update Sponsors Table
-        run: |
-          python update_sponsors.py
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -7,8 +7,11 @@ db/*
 db/pialert.db
 db/app.db
 front/log/*
+/log/*
 front/api/*
+/api/*
 **/plugins/**/*.log
+**/plugins/cloud_services/*
 **/%40eaDir/
 **/@eaDir/
 
@@ -22,10 +25,10 @@ __pycache__/
 **/pialert.db_bak
 .*.swp
 
-front/img/account/*
-**/account.php
-**/account.js
-front/css/account.css
+front/img/cloud_services/*
+**/cloud_services.php
+**/cloud_services.js
+front/css/cloud_services.css
 
 docker-compose.yml.ffsb42
 .env.omada.ffsb42

CODE_OF_CONDUCT.md

@@ -0,0 +1,137 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at <jokob@duck.com>.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Ethical Use Clause (Project-Specific)
+
+While NetAlertX is a tool designed to empower users with greater insight into their own networks, we expect and encourage all users to use this software **ethically and legally**.
+
+- Do not use this software to scan or monitor networks without **explicit authorization**.
+- Respect privacy, consent, and data protection laws applicable in your jurisdiction.
+- Any use of NetAlertX for malicious surveillance, stalking, or unauthorized access is explicitly discouraged and may be grounds for removal from the community and revocation of support.
+
+We reserve the right to take appropriate action to uphold the ethical integrity of this project.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1,
+available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/inclusion).
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq/>. Translations are available at
+<https://www.contributor-covenant.org/translations/>.

CONTRIBUTING

@@ -1,14 +1,53 @@
-# Contributing to this project
+# 🤝 Contributing to NetAlertX
 
-## Issues, bugs, feature requests
+First off, **thank you** for taking the time to contribute! NetAlertX is built and improved with the help of passionate people like you.
 
-The issue tracker is the preferred channel for bug reports, features requests and submitting pull requests.
+---
 
-Before submitting a new issue please spend a couple of minutes on research:
+## 📂 Issues, Bugs, and Feature Requests
 
-* Check [🛑 Common issues](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues) 
-* Check [💡 Closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) if a similar issue was solved in the past.
+Please use the [GitHub Issue Tracker](https://github.com/jokob-sk/NetAlertX/issues) for:
+- Bug reports 🐞
+- Feature requests 💡
+- Documentation feedback 📖
 
-## Pull-requests (PRs)
+Before opening a new issue:
+- 🛑 [Check Common Issues & Debug Tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues)
+- 🔍 [Search Closed Issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
 
-If you submit a PR please do check that your changes are backward compatible with existing installations. Existing features should be always preserved.
+---
+
+## 🚀 Submitting Pull Requests (PRs)
+
+We welcome PRs to improve the code, docs, or UI!
+
+Please:
+- Ensure **backward compatibility** with existing installations
+- Preserve existing features unless a breaking change is intentional and discussed
+- Follow existing **code style and structure**
+- Provide a clear title and description for your PR
+- If relevant, add or update tests and documentation
+- For plugins, refer to the [Plugin Dev Guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS_DEV.md)
+
+---
+
+## 🌟 First-Time Contributors
+
+New to open source? Check out these resources:
+- [How to Fork and Submit a PR](https://opensource.guide/how-to-contribute/)
+- Ask questions or get support in our [Discord](https://discord.gg/NczTUTWyRr)
+
+---
+
+## 🔐 Code of Conduct
+
+By participating, you agree to follow our [Code of Conduct](./CODE_OF_CONDUCT.md), which ensures a respectful and welcoming community.
+
+---
+
+## 📬 Contact
+
+If you have more in-depth questions or want to discuss contributing in other ways, feel free to reach out at:  
+📧 [jokob@duck.com](mailto:jokob@duck.com?subject=NetAlertX%20Contribution)
+
+We appreciate every contribution, big or small! 💙

Dockerfile

@@ -1,31 +1,33 @@
-FROM alpine:3.20 AS builder
+FROM alpine:3.22 AS builder
 
 ARG INSTALL_DIR=/app
 
 ENV PYTHONUNBUFFERED=1
 
 # Install build dependencies
-RUN apk add --no-cache bash python3 python3-dev gcc musl-dev libffi-dev openssl-dev \
+RUN apk add --no-cache bash shadow python3 python3-dev gcc musl-dev libffi-dev openssl-dev git \
     && python -m venv /opt/venv
-    
 
 # Enable venv
 ENV PATH="/opt/venv/bin:$PATH"
 
 COPY . ${INSTALL_DIR}/
 
-
-RUN pip install netifaces tplink-omada-client pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython librouteros  \
+RUN pip install openwrt-luci-rpc asusrouter asyncio aiohttp graphene flask tplink-omada-client wakeonlan pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython librouteros yattag git+https://github.com/foreign-sub/aiofreepybox.git \
     && bash -c "find ${INSTALL_DIR} -type d -exec chmod 750 {} \;" \
     && bash -c "find ${INSTALL_DIR} -type f -exec chmod 640 {} \;" \
     && bash -c "find ${INSTALL_DIR} -type f \( -name '*.sh' -o -name '*.py'  -o -name 'speedtest-cli' \) -exec chmod 750 {} \;"
 
+# Append Iliadbox certificate to aiofreepybox
+RUN cat ${INSTALL_DIR}/install/freebox_certificate.pem >> /opt/venv/lib/python3.12/site-packages/aiofreepybox/freebox_certificates.pem
+
 # second stage
-FROM alpine:3.20 AS runner
+FROM alpine:3.22 AS runner
 
 ARG INSTALL_DIR=/app
 
 COPY --from=builder /opt/venv /opt/venv
+COPY --from=builder /usr/sbin/usermod /usr/sbin/groupmod /usr/sbin/
 
 # Enable venv
 ENV PATH="/opt/venv/bin:$PATH" 
@@ -39,11 +41,10 @@ ENV S6_CMD_WAIT_FOR_SERVICES_MAXTIME=0
 # ❗ IMPORTANT - if you modify this file modify the /install/install_dependecies.sh file as well ❗ 
 
 RUN apk update --no-cache \
-    && apk add --no-cache bash zip lsblk gettext-envsubst sudo mtr tzdata s6-overlay \
-    && apk add --no-cache curl arp-scan iproute2 iproute2-ss nmap nmap-scripts traceroute nbtscan net-tools net-snmp-tools bind-tools awake ca-certificates  \
+    && apk add --no-cache bash libbsd zip lsblk gettext-envsubst sudo mtr tzdata s6-overlay \
+    && apk add --no-cache curl arp-scan iproute2 iproute2-ss nmap nmap-scripts traceroute nbtscan avahi avahi-tools openrc dbus net-tools net-snmp-tools bind-tools awake ca-certificates \
     && apk add --no-cache sqlite php83 php83-fpm php83-cgi php83-curl php83-sqlite3 php83-session \
     && apk add --no-cache python3 nginx \
-    && apk add --no-cache dcron \
     && ln -s /usr/bin/awake /usr/bin/wakeonlan \
     && bash -c "install -d -m 750 -o nginx -g www-data ${INSTALL_DIR} ${INSTALL_DIR}" \
     && rm -f /etc/nginx/http.d/default.conf
@@ -51,12 +52,12 @@ RUN apk update --no-cache \
 COPY --from=builder --chown=nginx:www-data ${INSTALL_DIR}/ ${INSTALL_DIR}/
 
 # Add crontab file
-COPY install/crontab /etc/crontabs/root
+COPY --chmod=600 --chown=root:root install/crontab /etc/crontabs/root
 
 # Start all required services
-RUN ${INSTALL_DIR}/dockerfiles/pre-setup.sh
+RUN ${INSTALL_DIR}/dockerfiles/start.sh
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=2 \
-  CMD curl -sf -o /dev/null ${LISTEN_ADDR}:${PORT}/api/app_state.json
+    CMD curl -sf -o /dev/null ${LISTEN_ADDR}:${PORT}/php/server/query_json.php?file=app_state.json
 
 ENTRYPOINT ["/init"]

Dockerfile.debian

@@ -33,7 +33,7 @@ COPY --chmod=775 --chown=${USER_ID}:${USER_GID} . ${INSTALL_DIR}/
 RUN apt-get install -y \
     tini snmp ca-certificates curl libwww-perl arp-scan perl apt-utils cron sudo \
     nginx-light php php-cgi php-fpm php-sqlite3 php-curl sqlite3 dnsutils net-tools php-openssl \
-    python3 python3-dev iproute2 nmap python3-pip zip systemctl usbutils traceroute nbtscan
+    python3 python3-dev iproute2 nmap python3-pip zip systemctl usbutils traceroute nbtscan avahi avahi-tools openrc dbus
 
 # Alternate dependencies
 RUN apt-get install nginx nginx-core mtr php-fpm php8.2-fpm php-cli php8.2 php8.2-sqlite3 -y
@@ -43,7 +43,7 @@ RUN phpenmod -v 8.2 sqlite3
 RUN apt-get install -y python3-venv
 RUN python3 -m venv myenv
 
-RUN /bin/bash -c "source myenv/bin/activate && update-alternatives --install /usr/bin/python python /usr/bin/python3 10 && pip3 install tplink-omada-client pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython cryptography librouteros "
+RUN /bin/bash -c "source myenv/bin/activate && update-alternatives --install /usr/bin/python python /usr/bin/python3 10 && pip3 install openwrt-luci-rpc asusrouter asyncio aiohttp graphene flask tplink-omada-client wakeonlan pycryptodome requests paho-mqtt scapy cron-converter pytz json2table dhcp-leases pyunifi speedtest-cli chardet python-nmap dnspython librouteros yattag "
 
 # Create a buildtimestamp.txt to later check if a new version was released
 RUN date +%s > ${INSTALL_DIR}/front/buildtimestamp.txt

FUNDING.yml

@@ -1,2 +0,0 @@
-github: jokob-sk
-patreon: 84385063

README.md

@@ -1,102 +1,160 @@
-[![GitHub Committed](https://img.shields.io/github/last-commit/jokob-sk/NetAlertX?color=40ba12&label=Committed&logo=GitHub&logoColor=fff&style=for-the-badge)](https://github.com/jokob-sk/NetAlertX)
 [![Docker Size](https://img.shields.io/docker/image-size/jokobsk/netalertx?label=Size&logo=Docker&color=0aa8d2&logoColor=fff&style=for-the-badge)](https://hub.docker.com/r/jokobsk/netalertx)
 [![Docker Pulls](https://img.shields.io/docker/pulls/jokobsk/netalertx?label=Pulls&logo=docker&color=0aa8d2&logoColor=fff&style=for-the-badge)](https://hub.docker.com/r/jokobsk/netalertx)
 [![GitHub Release](https://img.shields.io/github/v/release/jokob-sk/NetAlertX?color=0aa8d2&logoColor=fff&logo=GitHub&style=for-the-badge)](https://github.com/jokob-sk/NetAlertX/releases)
-[![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/UQnnHNYV)
+[![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/NczTUTWyRr)
+[![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
 
-# 🖧🔍 Network scanner & notification framework
+# NetAlertX - Network, presence scanner and alert framework
 
-Get visibility of what's going on on your WIFI/LAN network. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins#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).
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Documentation](#-documentation)
+- [Quick Start](#-quick-start)
+- [Alternative Apps](#-other-alternative-apps)
+- [Security & Privacy](#-security--privacy)
+- [FAQ](#-faq)
+- [Known Issues](#-known-issues)
+- [Donations](#-donations)
+- [Contributors](#-contributors)
+- [Translations](#-translations)
+- [License](#license)
 
 
-  | 🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/netalertx) |  📑 [Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) |🆕 [Release notes](https://github.com/jokob-sk/NetAlertX/releases) | 📚 [All Docs](https://github.com/jokob-sk/NetAlertX/tree/main/docs) | 
-  |----------------------|----------------------| ----------------------|  ----------------------| 
+## 🚀 Quick Start
+
+Start NetAlertX in seconds with Docker:
+
+```bash
+docker run -d --rm --network=host \
+  -v local_path/config:/app/config \
+  -v local_path/db:/app/db \
+  --mount type=tmpfs,target=/app/api \
+  -e PUID=200 -e PGID=300 \
+  -e TZ=Europe/Berlin \
+  -e PORT=20211 \
+  ghcr.io/jokob-sk/netalertx:latest
+```
+
+Need help configuring it? Check the [usage guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) or [full documentation](https://jokob-sk.github.io/NetAlertX/).
+
+For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
+
+For other install methods, check the [installation docs](#-documentation)
 
 
-  | ![Main screen][main] | ![device_details 1][device_details]  | ![Screen network][network] |
-  |----------------------|----------------------| ----------------------| 
+| [📑 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)
+|----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 
 
-  ![network_setup][network_setup] 
-
-
-Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and screenshots 📷.
+![showcase][showcase] 
 
 <details>
   <summary>📷 Click for more screenshots</summary>
 
-  | ![presence][presence] | ![maintenance][maintenance] | ![settings][settings]  |
+  | ![Main screen][main] | ![device_details 1][device_details]  | ![Screen network][network] |
   |----------------------|----------------------|----------------------|
+  | ![presence][presence] | ![maintenance][maintenance] | ![settings][settings]  |
   | ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap]  |
 
-</details>
-
-<details>
-  <summary>❓ Why use Net<b>Alert</b><sup>x</sup>?</summary>
-
-  <hr>
-
-  Most of us don't know what's going on on our home network, but we want our family and data to be safe.  _Command-line tools_ are great, but the output can be _hard to understand_ and action if you are not a network specialist.
-
-  Net<b>Alert</b><sup>x</sup> gives you peace of mind. _Visualize and immediately report 📬_ what is going on in your network - this is the first step to enhance your _network security 🔐_. 
-
-  Net<b>Alert</b><sup>x</sup> combines several network and other scanning tools 🔍 with notifications 📧 into one user-friendly package 📦. 
-
-  Set up a _kill switch ☠_ for your network via a smart plug with the available [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md) integration. Implement custom automations with the [CSV device Exports 📤](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup), [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md), or [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) features. 
-
-  Extend the app if you want to create your own scanner [Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins#readme) and handle the results and notifications in Net<b>Alert</b><sup>x</sup>. 
-
-  Looking forward to your contributions if you decide to share your work with the community ❤.
+  Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷.
 
 </details>
 
-## Scan Methods, Notifications, Integration, Extension system
+## 📦 Features
 
-| Features    | Details    | 
-|-------------|-------------|
-|      🔍     |   The app scans your network for, **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**,  **Pi-hole - DB import**,  **Pi-hole - DHCP leases import**, **Generic DHCP leases import**. **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins#readme) docs for more info on individual scans. |
-|📧           | Send notifications to more than 80+ services, including Telegram via [Apprise](https://hub.docker.com/r/caronc/apprise), or use [Pushsafer](https://www.pushsafer.com/), [Pushover](https://www.pushover.net/), or [NTFY](https://ntfy.sh/). |
-|🧩           | Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows.  |
-|➕           | Build your own scanners with the [Plugin system](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins#readme) |
+### Scanners
+
+The app scans your network for **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**,  **Pi-hole - DB import**,  **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) docs for a full list of avaliable plugins. 
+
+### Notification gateways
+
+Send notifications to more than 80+ services, including Telegram via [Apprise](https://hub.docker.com/r/caronc/apprise), or use native [Pushsafer](https://www.pushsafer.com/), [Pushover](https://www.pushover.net/), or [NTFY](https://ntfy.sh/) publishers. 
+
+### Integrations and Plugins
+
+Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows. You can also 
+build your own scanners with the [Plugin system](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8).
+
+### Workflows
+
+The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORKFLOWS.md) allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
 
 
-## Installation & Documentation
+## 📚 Documentation
 <!--- --------------------------------------------------------------------- --->
 
-| Docs        | Link    | 
-|-------------|-------------|
-| 📥🐳  | [Docker instructions](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) 
-| 📥🗄️  | [HW install (experimental 🧪)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) |
-| 📥🟧  | [Unraid App](https://unraid.net/community/apps) |
-| 📚     | [All Documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) (App Usage and Configuration) |
- 
-> Other Alternatives
->
-> - Check out [leiweibau's on HW installed fork](https://github.com/leiweibau/Pi.Alert/) (maintained)
-> - [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI (Open source)
-> - [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
-> - [NetBox](https://netboxlabs.com/) - Network management software (Commercial)
+Supported browsers: Chrome, Firefox
 
-## 🔔 Get notified what's new
+- [[Installation] Docker](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.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) 
+- [[Setup] Usage and Configuration](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md)
+- [[Development] API docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md)
+- [[Development] Custom Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS_DEV.md)
+
+...or explore all the [documentation here](https://jokob-sk.github.io/NetAlertX/).
+
+## 🔐 Security & Privacy
+
+NetAlertX scans your local network and can store metadata about connected devices. By default, all data is stored **locally**. No information is sent to external services unless you explicitly configure notifications or integrations.
+
+To further secure your installation:
+- Run it behind a reverse proxy with authentication
+- Use firewalls to restrict access to the web UI
+- Regularly update to the latest version for security patches
+
+See [Security Best Practices](https://github.com/jokob-sk/NetAlertX/security) for more details.
+
+
+## ❓ FAQ
+
+**Q: Why don’t I see any devices?**  
+A: Ensure the container has proper network access (e.g., use `--network host` on Linux). Also check that your scan method is properly configured in the UI.
+
+**Q: Does this work on Wi-Fi-only devices like Raspberry Pi?**  
+A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP, DHCP, or Pi-hole import.
+
+**Q: Will this send any data to the internet?**  
+A: No. All scans and data remain local, unless you set up cloud-based notifications.
+
+**Q: Can I use this without Docker?**  
+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.
+
+
+## 🐞 Known Issues
+
+- Some scanners (e.g. ARP) may not detect devices on different subnets. See the [Remote networks guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REMOTE_NETWORKS.md) for workarounds.
+- Wi-Fi-only networks may require alternate scanners for accurate detection.
+- Notification throttling may be needed for large networks to prevent spam.
+- On some systems, elevated permissions (like `CAP_NET_RAW`) may be needed for low-level scanning.
+
+Check the [GitHub Issues](https://github.com/jokob-sk/NetAlertX/issues) for the latest bug reports and solutions and consult [the official documentation](https://jokob-sk.github.io/NetAlertX/).
+
+## 📃 Everything else
+<!--- --------------------------------------------------------------------- --->
+
+### 📧 Get notified what's new
 
 Get notified about a new release, what new functionality you can use and about breaking changes. 
 
 ![Follow and star][follow_star] 
 
-### ⭐ Sponsors
+### 🔀 Other Alternative Apps
 
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/jokob-sk?style=social)](https://github.com/sponsors/jokob-sk)
-
-Thank you to all the wonderful people who are sponsoring this project. 
-
-> preventing my burnout😅 are:
-
-<!-- SPONSORS-LIST DO NOT MODIFY BELOW -->
-| All Sponsors |
-|---|
-
-<!-- SPONSORS-LIST DO NOT MODIFY ABOVE -->
+- [PiAlert by leiweibau](https://github.com/leiweibau/Pi.Alert/) (maintained, bare-metal install)
+- [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI (Open source)
+- [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
+- [NetBox](https://netboxlabs.com/) - Network management software (Commercial)
 
+### 💙 Donations
 
+Thank you to everyone who appreciates this tool and donates. 
 
 <details>
   <summary>Click for more ways to donate</summary>
@@ -113,29 +171,22 @@ Thank you to all the wonderful people who are sponsoring this project.
 
 </details>
 
-### 🙏Contributors
+### 🏗 Contributors
 
 This project would be nothing without the amazing work of the community, with special thanks to: 
 
-> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up) [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few...
-
-
-## Everything else
-<!--- --------------------------------------------------------------------- --->
+> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/jokob-sk/NetAlertX/graphs/contributors). 
 
 ### 🌍 Translations 
 
-Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/).
+Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/). Help out and suggest languages in the [online portal of Weblate](https://hosted.weblate.org/projects/pialert/core/).
 
 <a href="https://hosted.weblate.org/engage/pialert/">
   <img src="https://hosted.weblate.org/widget/pialert/core/multi-auto.svg" alt="Translation status" />
 </a>
 
-Help out and suggest languages in the [online portal of Weblate](https://hosted.weblate.org/projects/pialert/core/).
-
 ### License
 >  GPL 3.0 | [Read more here](LICENSE.txt) | Source of the [animated GIF (Loading Animation)](https://commons.wikimedia.org/wiki/File:Loading_Animation.gif) | Source of the [selfhosted Fonts](https://github.com/adobe-fonts/source-sans)
-  
 
 
 <!--- --------------------------------------------------------------------- --->
@@ -146,8 +197,7 @@ Help out and suggest languages in the [online portal of Weblate](https://hosted.
 [maintenance]:              ./docs/img/maintenance.png                    "Screen 4"
 [network]:                  ./docs/img/network.png                        "Screen 5"
 [settings]:                 ./docs/img/settings.png                       "Screen 6"
-[network_setup]:            ./docs/img/network_setup.gif                  "Screen 6"
-[help_faq]:                 ./docs/img/help_faq.png                       "Screen 7"
+[showcase]:                 ./docs/img/showcase.gif                       "Screen 6"
 [sync_hub]:                 ./docs/img/sync_hub.png                       "Screen 8"
 [notification_center]:      ./docs/img/notification_center.png            "Screen 8"
 [sent_reports_text]:        ./docs/img/sent_reports_text.png              "Screen 8"
@@ -156,4 +206,3 @@ Help out and suggest languages in the [online portal of Weblate](https://hosted.
 [main_dark]:                /docs/img/1_devices_dark.jpg                  "Main screen dark"
 [maintain_dark]:            /docs/img/5_maintain.jpg                      "Maintain screen dark"
 [follow_star]:              /docs/img/Follow_Releases_and_Star.gif        "Follow and Star"
-

back/app.conf

@@ -17,19 +17,21 @@
 # Scan multiple interfaces (eth1 and eth0):
 # SCAN_SUBNETS    = [ '192.168.1.0/24 --interface=eth1', '192.168.1.0/24 --interface=eth0' ]
 
-SCAN_SUBNETS=['192.168.1.0/24 --interface=eth0']
+DISCOVER_PLUGINS=True
+SCAN_SUBNETS=['--localnet']
 TIMEZONE='Europe/Berlin'
-LOADED_PLUGINS = ['ARPSCAN','CSVBCKP','DBCLNP', 'INTRNT','MAINT','NEWDEV','NSLOOKUP','NTFPRCS', 'PHOLUS','SETPWD','SMTP', 'SYNC', 'VNDRPDT', 'WORKFLOWS']
+LOADED_PLUGINS=['ARPSCAN', 'AVAHISCAN', 'CSVBCKP','DBCLNP', 'DIGSCAN', 'INTRNT', 'MAINT', 'NEWDEV', 'NBTSCAN', 'NSLOOKUP','NTFPRCS', 'SETPWD', 'SMTP', 'SYNC', 'VNDRPDT', 'WORKFLOWS', 'UI']
 
 DAYS_TO_KEEP_EVENTS=90
 # Used for generating links in emails. Make sure not to add a trailing slash!
-REPORT_DASHBOARD_URL='http://netalertx'
+REPORT_DASHBOARD_URL='http://127.0.0.1'
 
 # Make sure at least these scanners are enabled for new installs, other defaults are taken from the config.json
 INTRNT_RUN='schedule'
 ARPSCAN_RUN='schedule'
-PHOLUS_RUN='on_new_device'
 NSLOOKUP_RUN='before_name_updates'
+AVAHISCAN_RUN='before_name_updates'
+NBTSCAN_RUN='before_name_updates'
 
 # Email 
 #-------------------------------------

back/cron_script.sh

@@ -1,12 +1,13 @@
 #!/bin/bash
 export INSTALL_DIR=/app
 
-LOG_FILE="${INSTALL_DIR}/front/log/execution_queue.log"
+LOG_FILE="${INSTALL_DIR}/log/execution_queue.log"
 
 # Check if there are any entries with cron_restart_backend
 if grep -q "cron_restart_backend" "$LOG_FILE"; then
-  # Kill all python processes and restart the server
-  pkill -f "python " && (python ${INSTALL_DIR}/server > /dev/null 2>&1 &) && echo 'done'
+  # Restart python application using s6
+  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"

back/update_vendors.sh

@@ -30,13 +30,12 @@ IEEE_OUI_URL="http://standards-oui.ieee.org/oui/oui.txt"
 # Download the file using wget
 wget "$IEEE_OUI_URL" -O ieee-oui_dl.txt
 
-# Filter lines containing "(base 16)" and remove the "(base 16)" string
-grep "(base 16)" ieee-oui_dl.txt | sed 's/ *(base 16)//' > ieee-oui_new.txt
-
-# Combine ieee-oui_new.txt and ieee-oui.txt, and extract unique MAC start values along with vendor names
+# Filter lines containing "(base 16)" and format them with a tab between MAC and vendor
+grep "(base 16)" ieee-oui_dl.txt | sed -E 's/ *\(base 16\)//' | awk -F' ' '{printf "%s\t%s\n", $1, substr($0, index($0, $2))}' > ieee-oui_new.txt
 
+# Combine, sort, and remove duplicates, ensuring tab-separated output
 cat ieee-oui.txt ieee-oui_new.txt >> ieee-oui_all.txt
-sort ieee-oui_all.txt > ieee-oui_all_sort.txt
-awk '{$1=$1; print}' ieee-oui_all_sort.txt | sort -u > ieee-oui_all_filtered.txt
+sort ieee-oui_all.txt | awk '{$1=$1; print}' | sort -u | awk -F' ' '{printf "%s\t%s\n", $1, substr($0, index($0, $2))}' > ieee-oui_all_filtered.txt
+
 
 

docker-compose.yml

@@ -1,4 +1,3 @@
-version: "3"
 services:
   netalertx:
     privileged: true
@@ -16,7 +15,12 @@ services:
       # - ${APP_DATA_LOCATION}/netalertx_dev/db:/app/db      
       - ${APP_DATA_LOCATION}/netalertx/db:/app/db           
       # (optional) useful for debugging if you have issues setting up the container
-      # - ${LOGS_LOCATION}:/app/front/log      
+      - ${APP_DATA_LOCATION}/netalertx/log:/app/log      
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # - ${DEV_LOCATION}/api:/app/api
       # ---------------------------------------------------------------------------
       # DELETE START anyone trying to use this file: comment out / delete BELOW lines, they are only for development purposes
       - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/dhcp1.leases:/mnt/dhcp1.leases
@@ -24,7 +28,10 @@ services:
       - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_full.leases:/etc/pihole/dhcp.leases      
       - ${APP_DATA_LOCATION}/netalertx/dhcp_samples/pihole_dhcp_2.leases:/etc/pihole/dhcp2.leases      
       - ${APP_DATA_LOCATION}/pihole/etc-pihole/pihole-FTL.db:/etc/pihole/pihole-FTL.db    
+      - ${DEV_LOCATION}/mkdocs.yml:/app/mkdocs.yml
+      - ${DEV_LOCATION}/docs:/app/docs
       - ${DEV_LOCATION}/server:/app/server            
+      - ${DEV_LOCATION}/test:/app/test            
       - ${DEV_LOCATION}/dockerfiles:/app/dockerfiles
       # - ${APP_DATA_LOCATION}/netalertx/php.ini:/etc/php/8.2/fpm/php.ini      
       - ${DEV_LOCATION}/install:/app/install
@@ -33,40 +40,40 @@ services:
       - ${DEV_LOCATION}/back/update_vendors.sh:/app/back/update_vendors.sh
       - ${DEV_LOCATION}/front/lib:/app/front/lib
       - ${DEV_LOCATION}/front/js:/app/front/js
-      - ${DEV_LOCATION}/front/report_templates:/front/report_templates
-      - ${DEV_LOCATION}/install/start.debian.sh:/app/install/start.debian.sh
-      - ${DEV_LOCATION}/install/user-mapping.debian.sh:/app/install/user-mapping.debian.sh
-      - ${DEV_LOCATION}/install/install.debian.sh:/app/install/install.debian.sh      
-      - ${DEV_LOCATION}/install/install_dependencies.debian.sh:/app/install/install_dependencies.debian.sh      
-      - ${DEV_LOCATION}/front/api:/app/front/api
       - ${DEV_LOCATION}/front/php:/app/front/php      
       - ${DEV_LOCATION}/front/deviceDetails.php:/app/front/deviceDetails.php
+      - ${DEV_LOCATION}/front/deviceDetailsEdit.php:/app/front/deviceDetailsEdit.php
       - ${DEV_LOCATION}/front/userNotifications.php:/app/front/userNotifications.php
       - ${DEV_LOCATION}/front/deviceDetailsTools.php:/app/front/deviceDetailsTools.php
+      - ${DEV_LOCATION}/front/deviceDetailsPresence.php:/app/front/deviceDetailsPresence.php
+      - ${DEV_LOCATION}/front/deviceDetailsSessions.php:/app/front/deviceDetailsSessions.php
+      - ${DEV_LOCATION}/front/deviceDetailsEvents.php:/app/front/deviceDetailsEvents.php
       - ${DEV_LOCATION}/front/devices.php:/app/front/devices.php
       - ${DEV_LOCATION}/front/events.php:/app/front/events.php
       - ${DEV_LOCATION}/front/plugins.php:/app/front/plugins.php
       - ${DEV_LOCATION}/front/pluginsCore.php:/app/front/pluginsCore.php
-      - ${DEV_LOCATION}/front/help_faq.php:/app/front/help_faq.php
       - ${DEV_LOCATION}/front/index.php:/app/front/index.php
+      - ${DEV_LOCATION}/front/initCheck.php:/app/front/initCheck.php
       - ${DEV_LOCATION}/front/maintenance.php:/app/front/maintenance.php
       - ${DEV_LOCATION}/front/network.php:/app/front/network.php
       - ${DEV_LOCATION}/front/presence.php:/app/front/presence.php
       - ${DEV_LOCATION}/front/settings.php:/app/front/settings.php      
       - ${DEV_LOCATION}/front/systeminfo.php:/app/front/systeminfo.php      
-      - ${DEV_LOCATION}/front/account.php:/app/front/account.php      
+      - ${DEV_LOCATION}/front/cloud_services.php:/app/front/cloud_services.php      
       - ${DEV_LOCATION}/front/report.php:/app/front/report.php      
       - ${DEV_LOCATION}/front/workflows.php:/app/front/workflows.php      
+      - ${DEV_LOCATION}/front/workflowsCore.php:/app/front/workflowsCore.php      
+      - ${DEV_LOCATION}/front/appEvents.php:/app/front/appEvents.php      
       - ${DEV_LOCATION}/front/appEventsCore.php:/app/front/appEventsCore.php      
       - ${DEV_LOCATION}/front/multiEditCore.php:/app/front/multiEditCore.php      
-      - ${DEV_LOCATION}/front/donations.php:/app/front/donations.php      
-      - ${DEV_LOCATION}/front/plugins:/app/front/plugins      
+      - ${DEV_LOCATION}/front/plugins:/app/front/plugins    
       # DELETE END anyone trying to use this file: comment out / delete ABOVE lines, they are only for development purposes
       # ---------------------------------------------------------------------------
-    environment:
-      # - APP_CONF_OVERRIDE={"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","UI_dark_mode":"True"}
+    environment:      
+      # - APP_CONF_OVERRIDE={"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20223","UI_theme":"Light"}
       - TZ=${TZ}
       - PORT=${PORT}      
       # ❗ DANGER ZONE BELOW - Setting ALWAYS_FRESH_INSTALL=true will delete the content of the /db & /config folders
       - ALWAYS_FRESH_INSTALL=${ALWAYS_FRESH_INSTALL}
+      # - LOADED_PLUGINS=["DHCPLSS","PIHOLE","ASUSWRT","FREEBOX"]
       

dockerfiles/README.md

@@ -1,14 +1,13 @@
-[![GitHub Committed](https://img.shields.io/github/last-commit/jokob-sk/NetAlertX?color=40ba12&label=Committed&logo=GitHub&logoColor=fff&style=for-the-badge)](https://github.com/jokob-sk/NetAlertX)
 [![Docker Size](https://img.shields.io/docker/image-size/jokobsk/netalertx?label=Size&logo=Docker&color=0aa8d2&logoColor=fff&style=for-the-badge)](https://hub.docker.com/r/jokobsk/netalertx)
 [![Docker Pulls](https://img.shields.io/docker/pulls/jokobsk/netalertx?label=Pulls&logo=docker&color=0aa8d2&logoColor=fff&style=for-the-badge)](https://hub.docker.com/r/jokobsk/netalertx)
 [![GitHub Release](https://img.shields.io/github/v/release/jokob-sk/NetAlertX?color=0aa8d2&logoColor=fff&logo=GitHub&style=for-the-badge)](https://github.com/jokob-sk/NetAlertX/releases)
-[![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/UQnnHNYV)
+[![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/NczTUTWyRr)
+[![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
 
+# NetAlertX - Network scanner & notification framework
 
-# NetAlertX 🖧🔍 Network scanner & notification framework
-
-  | 🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/netalertx) |  📑 [Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) |🆕 [Release notes](https://github.com/jokob-sk/NetAlertX/releases) | 📚 [All Docs](https://github.com/jokob-sk/NetAlertX/tree/main/docs) |
-  |----------------------|----------------------| ----------------------|  ----------------------| 
+| [📑 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)
+|----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 
 
 <a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
   <img src="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" width="1000px" />
@@ -22,26 +21,35 @@ Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and scree
 ## 📕 Basic Usage 
 
 > [!WARNING]
-> You will have to run the container on the `host` network.
+> 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
 docker run -d --rm --network=host \
-  -v local/path/config:/app/config \
-  -v local/path/db:/app/db \
+  -v local_path/config:/app/config \
+  -v local_path/db:/app/db \
+  --mount type=tmpfs,target=/app/api \
+  -e PUID=200 -e PGID=300 \
   -e TZ=Europe/Berlin \
   -e PORT=20211 \
-  jokobsk/netalertx:latest
+  ghcr.io/jokob-sk/netalertx:latest
 ```
-- The initial scan can take up to 15min (with 50 devices and MQTT). Subsequent ones 3 and 5 minutes so wait that long for all of the scans to run.
+
+See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md).
 
 ### Docker environment variables
 
-| Variable | Description | Default |
-| :------------- |:-------------| -----:|
+| 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` |
-|`ALWAYS_FRESH_INSTALL` | Setting  to `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`/`-dev` image.   |    `N/A` |
+|`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` |
+
+> You can override the default GraphQL port setting `GRAPHQL_PORT` (set to `20212`) by using the `APP_CONF_OVERRIDE` env variable. `LOADED_PLUGINS` and settings in `APP_CONF_OVERRIDE` can be specified via the UI as well.
 
 ### Docker paths
 
@@ -50,185 +58,41 @@ docker run -d --rm --network=host \
 
 | 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 (see below for details).  | 
-| ✅ | `:/app/db` | Folder which will contain the `app.db` file  | 
-| | `:/app/front/log` |  Logs folder useful for debugging if you have issues setting up the container  | 
-| | `:/etc/pihole/pihole-FTL.db` |  PiHole's `pihole-FTL.db` database file. Required if you want to use PiHole DB mapping.  | 
-| | `:/etc/pihole/dhcp.leases` |  PiHole's `dhcp.leases` file. Required if you want to use PiHole `dhcp.leases` file. This has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (the path in the container must contain `pihole`)| 
-| | `:/app/front/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.   | 
-| | `:/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/front/plugins/README.md).  | 
+| ✅ | `:/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  | 
+| ✅ | `:/app/db` | Folder which will contain the `app.db` database file  | 
+| | `:/app/log` |  Logs folder useful for debugging if you have issues setting up the container  | 
+| | `:/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.   | 
+| | `:/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).  | 
 
-> Use separate `db` and `config` directories, don't nest them.
+> Use separate `db` and `config` directories, do not nest them.
 
-### (If UI is not available) Modify the config (`app.conf`) 
+### Initial setup
 
-- The preferred way is to manage the configuration via the Settings section in the UI.
-- You can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/config) directly, if needed.
 - 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 
 
-### ⚙ Important settings
+#### Setting up scanners
 
-These are the most important settings to get at least some output in your Devices screen. Usually, only one approach is used, but you can combine these approaches.
-
-| Scan method | Setting | Description |
-| :------------- | :------------- | :-------------| 
-| arp-scan, nmap-scan | `SCAN_SUBNETS` | See the documentation on how [to setup SUBNETS, VLANs & limitations](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) |
-| PiHole | `PIHOLE_RUN` | There are 2 approaches how to get PiHole devices imported. Via the PiHole import (`PIHOLE`) plugin or DHCP leases (`DHCPLSS`) plugin. The `PIHOLE` plugin requires you to map the PiHole database, as mentioned above. |
-| dhcp.leases | `DHCPLSS_RUN` | You need to map `:/etc/myfiles/dhcp.leases` in the `docker-compose.yml` file if you enable this setting. This path has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases#overview) for details). |
+You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default `ARPSCAN` plugin, you have to specify at least one valid subnet and interface in the `SCAN_SUBNETS` setting. See the documentation on [How to set up multiple SUBNETS, VLANs and what are limitations](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) for troubleshooting and more advanced scenarios. 
 
+If you are running PiHole you can synchronize devices directly. Check the [PiHole configuration guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PIHOLE_GUIDE.md) for details. 
 
 > [!NOTE]
-> It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.
+> You can bulk-import devices via the [CSV import method](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md).
 
+#### Community guides
 
-#### 🧭 Community guides
+You can read or watch several [community configuration guides](https://github.com/jokob-sk/NetAlertX/blob/main/docs/COMMUNITY_GUIDES.md) in Chinese, Korean, German, or French. 
 
-Use the official installation guides at first and use community content as supplementary material. Open an issue if you'd like to add your link to the list 🙏 
-
-- ▶ [Home Lab Network Monitoring - Scotti-BYTE Enterprise Consulting Services](https://www.youtube.com/watch?v=0DryhzrQSJA) (July 2024)
-- 📄 [How to Install NetAlertX on Your Synology NAS - Marius hosting](https://mariushosting.com/how-to-install-pi-alert-on-your-synology-nas/) (Updated frequently)
-- 📄 [Using the PiAlert Network Security Scanner on a Raspberry Pi - PiMyLifeUp](https://pimylifeup.com/raspberry-pi-pialert/)
-- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg) 
-- 📄 [防蹭网神器，网络安全助手 | 极空间部署网络扫描和通知系统『NetAlertX』](https://blog.csdn.net/qq_63499861/article/details/141105273)
-- 📄 [시놀/헤놀에서 네트워크 스캐너 Pi.Alert Docker로 설치 및 사용하기](https://blog.dalso.org/article/%EC%8B%9C%EB%86%80-%ED%97%A4%EB%86%80%EC%97%90%EC%84%9C-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-%EC%8A%A4%EC%BA%90%EB%84%88-pi-alert-docker%EB%A1%9C-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%82%AC%EC%9A%A9) (July 2023)
-- 📄 [网络入侵探测器Pi.Alert (Chinese)](https://codeantenna.com/a/VgUvIAjZ7J) (May 2023)
-- ▶ [Pi.Alert auf Synology & Docker by - Jürgen Barth](https://www.youtube.com/watch?v=-ouvA2UNu-A) (March 2023)
-- ▶ [Top Docker Container for Home Server Security - VirtualizationHowto](https://www.youtube.com/watch?v=tY-w-enLF6Q) (March 2023)
-- ▶ [Pi.Alert or WatchYourLAN can alert you to unknown devices appearing on your WiFi or LAN network - Danie van der Merwe](https://www.youtube.com/watch?v=v6an9QG2xF0) (November 2022)
-
-> Ordered by last update time. 
+> Please note these might be outdated. Rely on official documentation first. 
  
-### **Common issues** 
+#### Common issues
 
-💡 Before creating a new issue, please check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed). 
+- Before creating a new issue, please check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed). 
+- Check also common issues and [debugging tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md). 
 
-⚠ Check also common issues and [debugging tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md). 
-
-> [!NOTE]
-> You can bulk-update devices via the [CSV import method](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md).
-
-## 📄 docker-compose.yml Examples
-
-### Example 1
-
-```yaml
-version: "3"
-services:
-  netalertx:
-    container_name: netalertx
-    # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: "jokobsk/netalertx:latest"      
-    network_mode: "host"        
-    restart: unless-stopped
-    volumes:
-      - local/path/config:/app/config
-      - local/path/db:/app/db      
-      # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/front/log
-    environment:
-      - TZ=Europe/Berlin      
-      - PORT=20211
-```
-
-To run the container execute: `sudo docker-compose up -d`
-
-### Example 2
-
-Example by [SeimuS](https://github.com/SeimusS).
-
-```yaml
-  netalertx:
-    container_name: NetAlertX
-    hostname: NetAlertX
-    privileged: true
-    # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: jokobsk/netalertx:latest
-    environment:
-      - TZ=Europe/Bratislava
-    restart: always
-    volumes:
-      - ./netalertx/db:/app/db
-      - ./netalertx/config:/app/config
-    network_mode: host
-```
-
-To run the container execute: `sudo docker-compose up -d`
-
-### Example 3
-
-`docker-compose.yml` 
-
-```yaml
-version: "3"
-services:
-  netalertx:
-    container_name: netalertx
-    # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: "jokobsk/netalertx:latest"      
-    network_mode: "host"        
-    restart: unless-stopped
-    volumes:
-      - ${APP_DATA_LOCATION}/netalertx/config:/app/config
-      - ${APP_DATA_LOCATION}/netalertx/db/:/app/db/      
-      # (optional) useful for debugging if you have issues setting up the container
-      - ${LOGS_LOCATION}:/app/front/log
-    environment:
-      - TZ=${TZ}      
-      - PORT=${PORT}
-```
-
-`.env` file
-
-```yaml
-#GLOBAL PATH VARIABLES
-
-APP_DATA_LOCATION=/path/to/docker_appdata
-APP_CONFIG_LOCATION=/path/to/docker_config
-LOGS_LOCATION=/path/to/docker_logs
-
-#ENVIRONMENT VARIABLES
-
-TZ=Europe/Paris
-PORT=20211
-
-#DEVELOPMENT VARIABLES
-
-DEV_LOCATION=/path/to/local/source/code
-```
-
-To run the container execute: `sudo docker-compose --env-file /path/to/.env up`
-
-### Example 4
-
-Courtesy of [pbek](https://github.com/pbek). The volume `netalertx_db` is used by the db directory. The two config files are mounted directly from a local folder to their places in the config folder. You can backup the `docker-compose.yaml` folder and the docker volumes folder.
-
-```yaml
-  netalertx:
-    # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: jokobsk/netalertx
-    ports:
-      - "80:20211/tcp"
-    environment:
-      - TZ=Europe/Vienna
-    networks:
-      local:
-        ipv4_address: 192.168.1.2
-    restart: unless-stopped
-    volumes:
-      - netalertx_db:/app/db
-      - ./netalertx/:/app/config/      
-```
-
-## 🏅 Recognitions
-
-Big thanks to <a href="https://github.com/Macleykun">@Macleykun</a> & for help and tips & tricks for Dockerfile(s) and <a href="https://github.com/vladaurosh">@vladaurosh</a> for Alpine re-base help.
-
-## ❤ Support me 
+## 💙 Support me 
 
 | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) | 
 | --- | --- | --- | 
@@ -236,4 +100,4 @@ Big thanks to <a href="https://github.com/Macleykun">@Macleykun</a> & for help a
 - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM`
 - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7`
 
-> 📧 Email me at [jokob@duck.com](mailto:jokob@duck.com?subject=NetAlertX) if you want to get in touch or if I should add other sponsorship platforms.
+> 📧 Email me at [netalertx@gmail.com](mailto:netalertx@gmail.com?subject=NetAlertX Donations) if you want to get in touch or if I should add other sponsorship platforms.

dockerfiles/init.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/with-contenv bash
+
+echo "---------------------------------------------------------
+[INSTALL]                                    Run init.sh
+---------------------------------------------------------"
+
+DEFAULT_PUID=102
+DEFAULT_GID=82
+
+PUID=${PUID:-${DEFAULT_PUID}}
+PGID=${PGID:-${DEFAULT_GID}}
+
+echo "[INSTALL] Setting up user UID and GID"
+
+if ! groupmod -o -g "$PGID" www-data && [ "$PGID" != "$DEFAULT_GID" ] ; then
+   echo "Failed to set user GID to ${PGID}, trying with default GID ${DEFAULT_GID}"
+   groupmod -o -g "$DEFAULT_GID" www-data
+fi
+if ! usermod -o -u "$PUID" nginx && [ "$PUID" != "$DEFAULT_PUID" ] ; then
+   echo "Failed to set user UID to ${PUID}, trying with default PUID ${DEFAULT_PUID}"
+   usermod -o -u "$DEFAULT_PUID" nginx
+fi
+
+echo "
+---------------------------------------------------------
+GID/UID
+---------------------------------------------------------
+User UID:    $(id -u nginx)
+User GID:    $(getent group www-data | cut -d: -f3)
+---------------------------------------------------------"
+
+chown nginx:nginx /run/nginx/ /var/log/nginx/ /var/lib/nginx/ /var/lib/nginx/tmp/
+chgrp www-data /var/www/localhost/htdocs/
+
+export INSTALL_DIR=/app  # Specify the installation directory here
+
+# DO NOT CHANGE ANYTHING BELOW THIS LINE!
+
+CONF_FILE="app.conf"
+NGINX_CONF_FILE=netalertx.conf
+DB_FILE="app.db"
+FULL_FILEDB_PATH="${INSTALL_DIR}/db/${DB_FILE}"
+NGINX_CONFIG_FILE="/etc/nginx/http.d/${NGINX_CONF_FILE}"
+OUI_FILE="/usr/share/arp-scan/ieee-oui.txt" # Define the path to ieee-oui.txt and ieee-iab.txt
+
+INSTALL_DIR_OLD=/home/pi/pialert
+OLD_APP_NAME=pialert
+
+# DO NOT CHANGE ANYTHING ABOVE THIS LINE!
+
+# Check if script is run as root
+if [[ $EUID -ne 0 ]]; then
+    echo "This script must be run as root. Please use 'sudo'."
+    exit 1
+fi
+
+# DANGER ZONE: ALWAYS_FRESH_INSTALL
+if [ "$ALWAYS_FRESH_INSTALL" = true ]; then
+  echo "[INSTALL] ❗ ALERT /db and /config folders are cleared because the ALWAYS_FRESH_INSTALL is set to: $ALWAYS_FRESH_INSTALL❗"
+
+  # Delete content of "$INSTALL_DIR/config/"
+  rm -rf "$INSTALL_DIR/config/"*
+  rm -rf "$INSTALL_DIR_OLD/config/"*
+
+  # Delete content of "$INSTALL_DIR/db/"
+  rm -rf "$INSTALL_DIR/db/"*
+  rm -rf "$INSTALL_DIR_OLD/db/"*
+fi
+
+# OVERRIDE settings: Handling APP_CONF_OVERRIDE
+# Check if APP_CONF_OVERRIDE is set
+
+# remove old
+rm "${INSTALL_DIR}/config/app_conf_override.json"
+
+if [ -z "$APP_CONF_OVERRIDE" ]; then
+  echo "APP_CONF_OVERRIDE is not set. Skipping config file creation."
+else
+  # Save the APP_CONF_OVERRIDE env variable as a JSON file
+  echo "$APP_CONF_OVERRIDE" > "${INSTALL_DIR}/config/app_conf_override.json"
+  echo "Config file saved to ${INSTALL_DIR}/config/app_conf_override.json"
+fi
+
+# 🔻 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2025
+
+# Check if pialert.db exists, then create a symbolic link to app.db
+if [ -f "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" ]; then
+    ln -s "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" "${FULL_FILEDB_PATH}"
+fi
+
+# Check if ${OLD_APP_NAME}.conf exists, then create a symbolic link to app.conf
+if [ -f "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" ]; then
+    ln -s "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" "${INSTALL_DIR}/config/${CONF_FILE}"
+fi
+# 🔺 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2025
+
+echo "[INSTALL] Copy starter ${DB_FILE} and ${CONF_FILE} if they don't exist"
+
+# Copy starter app.db, app.conf if they don't exist
+cp -na "${INSTALL_DIR}/back/${CONF_FILE}" "${INSTALL_DIR}/config/${CONF_FILE}"
+cp -na "${INSTALL_DIR}/back/${DB_FILE}" "${FULL_FILEDB_PATH}"
+
+# if custom variables not set we do not need to do anything
+if [ -n "${TZ}" ]; then
+  FILECONF="${INSTALL_DIR}/config/${CONF_FILE}"
+  echo "[INSTALL] Setup timezone"
+  sed -i "\#^TIMEZONE=#c\TIMEZONE='${TZ}'" "${FILECONF}"
+
+  # set TimeZone in container
+  cp /usr/share/zoneinfo/$TZ /etc/localtime
+  echo $TZ > /etc/timezone
+fi
+
+# if custom variables not set we do not need to do anything
+if [ -n "${LOADED_PLUGINS}" ]; then
+  FILECONF="${INSTALL_DIR}/config/${CONF_FILE}"
+  echo "[INSTALL] Setup custom LOADED_PLUGINS variable"
+  sed -i "\#^LOADED_PLUGINS=#c\LOADED_PLUGINS=${LOADED_PLUGINS}" "${FILECONF}"
+fi
+
+echo "[INSTALL] Setup NGINX"
+echo "Setting webserver to address ($LISTEN_ADDR) and port ($PORT)"
+envsubst '$INSTALL_DIR $LISTEN_ADDR $PORT' < "${INSTALL_DIR}/install/netalertx.template.conf" > "${NGINX_CONFIG_FILE}"
+
+# Run the hardware vendors update at least once
+echo "[INSTALL] Run the hardware vendors update"
+
+# Check if ieee-oui.txt or ieee-iab.txt exist
+if [ -f "${OUI_FILE}" ]; then
+  echo "The file ieee-oui.txt exists. Skipping update_vendors.sh..."
+else
+  echo "The file ieee-oui.txt does not exist. Running update_vendors..."
+
+  # Run the update_vendors.sh script
+  if [ -f "${INSTALL_DIR}/back/update_vendors.sh" ]; then
+    "${INSTALL_DIR}/back/update_vendors.sh"
+  else
+    echo "update_vendors.sh script not found in ${INSTALL_DIR}."
+  fi
+fi
+
+# Create an empty log files
+# Create the execution_queue.log and app_front.log files if they don't exist
+touch "${INSTALL_DIR}"/log/{app.log,execution_queue.log,app_front.log,app.php_errors.log,stderr.log,stdout.log,db_is_locked.log}
+touch "${INSTALL_DIR}"/api/user_notifications.json
+
+# Create plugins sub-directory if it doesn't exist in case a custom log folder is used
+mkdir -p "${INSTALL_DIR}"/log/plugins
+
+echo "[INSTALL] Fixing permissions after copied starter config & DB"
+chown -R nginx:www-data "${INSTALL_DIR}"
+
+chmod 750 "${INSTALL_DIR}"/{config,log,db}
+find "${INSTALL_DIR}"/{config,log,db} -type f -exec chmod 640 {} \;
+
+# Check if buildtimestamp.txt doesn't exist
+if [ ! -f "${INSTALL_DIR}/front/buildtimestamp.txt" ]; then
+    # Create buildtimestamp.txt
+    date +%s > "${INSTALL_DIR}/front/buildtimestamp.txt"
+    chown nginx:www-data "${INSTALL_DIR}/front/buildtimestamp.txt"
+fi
+
+echo -e "
+            [ENV] PATH                      is ${PATH}
+            [ENV] PORT                      is ${PORT}
+            [ENV] TZ                        is ${TZ}
+            [ENV] LISTEN_ADDR               is ${LISTEN_ADDR}
+            [ENV] ALWAYS_FRESH_INSTALL      is ${ALWAYS_FRESH_INSTALL}
+        "

dockerfiles/pre-setup.sh

@@ -1,43 +0,0 @@
-#!/bin/bash
-
-export INSTALL_DIR=/app
-export APP_NAME=netalertx
-
-# php-fpm setup
-install -d -o nginx -g www-data /run/php/
-sed -i "/^;pid/c\pid = /run/php/php8.3-fpm.pid" /etc/php83/php-fpm.conf
-sed -i "/^listen/c\listen = /run/php/php8.3-fpm.sock" /etc/php83/php-fpm.d/www.conf
-sed -i "/^;listen.owner/c\listen.owner = nginx" /etc/php83/php-fpm.d/www.conf
-sed -i "/^;listen.group/c\listen.group = www-data" /etc/php83/php-fpm.d/www.conf
-sed -i "/^user/c\user = nginx" /etc/php83/php-fpm.d/www.conf
-sed -i "/^group/c\group = www-data" /etc/php83/php-fpm.d/www.conf
-
-# s6 overlay setup
-mkdir -p /etc/s6-overlay/s6-rc.d/{SetupOneshot,php-fpm/dependencies.d,nginx/dependencies.d}
-mkdir -p /etc/s6-overlay/s6-rc.d/{SetupOneshot,php-fpm/dependencies.d,nginx/dependencies.d,$APP_NAME/dependencies.d}
-echo "oneshot" > /etc/s6-overlay/s6-rc.d/SetupOneshot/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/php-fpm/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/nginx/type
-echo "longrun" > /etc/s6-overlay/s6-rc.d/$APP_NAME/type
-echo -e "${INSTALL_DIR}/dockerfiles/setup.sh" > /etc/s6-overlay/s6-rc.d/SetupOneshot/up
-echo -e "#!/bin/execlineb -P\n/usr/sbin/php-fpm83 -F" > /etc/s6-overlay/s6-rc.d/php-fpm/run
-echo -e '#!/bin/execlineb -P\nnginx -g "daemon off;"' > /etc/s6-overlay/s6-rc.d/nginx/run
-echo -e '#!/bin/execlineb -P
-        with-contenv
-
-        importas -u PORT PORT
-
-        if { echo
-        "
-            [INSTALL] 🚀 Starting app (:${PORT})
-
-        " }' > /etc/s6-overlay/s6-rc.d/$APP_NAME/run
-echo -e "python ${INSTALL_DIR}/server" >> /etc/s6-overlay/s6-rc.d/$APP_NAME/run
-touch /etc/s6-overlay/s6-rc.d/user/contents.d/{SetupOneshot,php-fpm,nginx} /etc/s6-overlay/s6-rc.d/{php-fpm,nginx}/dependencies.d/SetupOneshot
-touch /etc/s6-overlay/s6-rc.d/user/contents.d/{SetupOneshot,php-fpm,nginx,$APP_NAME} /etc/s6-overlay/s6-rc.d/{php-fpm,nginx,$APP_NAME}/dependencies.d/SetupOneshot
-touch /etc/s6-overlay/s6-rc.d/nginx/dependencies.d/php-fpm
-touch /etc/s6-overlay/s6-rc.d/$APP_NAME/dependencies.d/nginx
-
-
-
-rm -f $0

dockerfiles/setup.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/with-contenv bash
-
-echo "---------------------------------------------------------"
-echo "[INSTALL]                                    Run setup.sh"
-echo "---------------------------------------------------------"
-
-export INSTALL_DIR=/app  # Specify the installation directory here
-
-# DO NOT CHANGE ANYTHING BELOW THIS LINE!
-
-CONF_FILE="app.conf"
-NGINX_CONF_FILE=netalertx.conf
-DB_FILE="app.db"
-FULL_FILEDB_PATH="${INSTALL_DIR}/db/${DB_FILE}"
-NGINX_CONFIG_FILE="/etc/nginx/http.d/${NGINX_CONF_FILE}"
-OUI_FILE="/usr/share/arp-scan/ieee-oui.txt" # Define the path to ieee-oui.txt and ieee-iab.txt
-
-INSTALL_DIR_OLD=/home/pi/pialert
-OLD_APP_NAME=pialert
-
-# DO NOT CHANGE ANYTHING ABOVE THIS LINE!
-
-# Check if script is run as root
-if [[ $EUID -ne 0 ]]; then
-    echo "This script must be run as root. Please use 'sudo'."
-    exit 1
-fi
-
-echo "[INSTALL] Copy starter ${DB_FILE} and ${CONF_FILE} if they don't exist"
-
-# DANGER ZONE: ALWAYS_FRESH_INSTALL
-if [ "$ALWAYS_FRESH_INSTALL" = true ]; then
-  echo "[INSTALL] ❗ ALERT /db and /config folders are cleared because the ALWAYS_FRESH_INSTALL is set to: $ALWAYS_FRESH_INSTALL❗"
-
-  # Delete content of "$INSTALL_DIR/config/"
-  rm -rf "$INSTALL_DIR/config/"*
-  rm -rf "$INSTALL_DIR_OLD/config/"*
-
-  # Delete content of "$INSTALL_DIR/db/"
-  rm -rf "$INSTALL_DIR/db/"*
-  rm -rf "$INSTALL_DIR_OLD/db/"*
-fi
-
-# OVERRIDE settings: Handling APP_CONF_OVERRIDE
-# Check if APP_CONF_OVERRIDE is set
-if [ -z "$APP_CONF_OVERRIDE" ]; then
-  echo "APP_CONF_OVERRIDE is not set. Skipping config file creation."
-else
-  # Save the APP_CONF_OVERRIDE env variable as a JSON file
-  echo "$APP_CONF_OVERRIDE" > "${INSTALL_DIR}/config/app_conf_override.json"
-  echo "Config file saved to ${INSTALL_DIR}/config/app_conf_override.json"
-fi
-
-# 🔻 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2024
-
-# Check if pialert.db exists, then create a symbolic link to app.db
-if [ -f "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" ]; then
-    ln -s "${INSTALL_DIR_OLD}/db/${OLD_APP_NAME}.db" "${FULL_FILEDB_PATH}"
-fi
-
-# Check if ${OLD_APP_NAME}.conf exists, then create a symbolic link to app.conf
-if [ -f "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" ]; then
-    ln -s "${INSTALL_DIR_OLD}/config/${OLD_APP_NAME}.conf" "${INSTALL_DIR}/config/${CONF_FILE}"
-fi
-# 🔺 FOR BACKWARD COMPATIBILITY - REMOVE AFTER 12/12/2024
-
-# Copy starter .db and .conf if they don't exist
-cp -na "${INSTALL_DIR}/back/${CONF_FILE}" "${INSTALL_DIR}/config/${CONF_FILE}"
-cp -na "${INSTALL_DIR}/back/${DB_FILE}" "${FULL_FILEDB_PATH}"
-
-# if custom variables not set we do not need to do anything
-if [ -n "${TZ}" ]; then
-  FILECONF="${INSTALL_DIR}/config/${CONF_FILE}"
-  echo "[INSTALL] Setup timezone"
-  sed -i "\#^TIMEZONE=#c\TIMEZONE='${TZ}'" "${FILECONF}"
-
-  # set TimeZone in container
-  cp /usr/share/zoneinfo/$TZ /etc/localtime
-  echo $TZ > /etc/timezone
-fi
-
-echo "[INSTALL] Setup NGINX"
-echo "Setting webserver to address ($LISTEN_ADDR) and port ($PORT)"
-envsubst '$INSTALL_DIR $LISTEN_ADDR $PORT' < "${INSTALL_DIR}/install/netalertx.template.conf" > "${NGINX_CONFIG_FILE}"
-
-# Run the hardware vendors update at least once
-echo "[INSTALL] Run the hardware vendors update"
-
-# Check if ieee-oui.txt or ieee-iab.txt exist
-if [ -f "${OUI_FILE}" ]; then
-  echo "The file ieee-oui.txt exists. Skipping update_vendors.sh..."
-else
-  echo "The file ieee-oui.txt does not exist. Running update_vendors..."
-
-  # Run the update_vendors.sh script
-  if [ -f "${INSTALL_DIR}/back/update_vendors.sh" ]; then
-    "${INSTALL_DIR}/back/update_vendors.sh"
-  else
-    echo "update_vendors.sh script not found in ${INSTALL_DIR}."
-  fi
-fi
-
-# Create an empty log files
-# Create the execution_queue.log and app_front.log files if they don't exist
-touch "${INSTALL_DIR}"/front/log/{app.log,execution_queue.log,app_front.log,app.php_errors.log,stderr.log,stdout.log,db_is_locked.log}
-touch "${INSTALL_DIR}"/front/api/user_notifications.json
-
-echo "[INSTALL] Fixing permissions after copied starter config & DB"
-chown -R nginx:www-data "${INSTALL_DIR}"/{config,front/log,db,front/api}
-chown -R nginx:www-data "${INSTALL_DIR}"/front/api/user_notifications.json
-
-chmod 750 "${INSTALL_DIR}"/{config,front/log,db}
-find "${INSTALL_DIR}"/{config,front/log,db} -type f -exec chmod 640 {} \;
-
-# Check if buildtimestamp.txt doesn't exist
-if [ ! -f "${INSTALL_DIR}/front/buildtimestamp.txt" ]; then
-    # Create buildtimestamp.txt
-    date +%s > "${INSTALL_DIR}/front/buildtimestamp.txt"
-    chown nginx:www-data "${INSTALL_DIR}/front/buildtimestamp.txt"
-fi
-
-# Start crond service in the background
-echo "[INSTALL] Starting crond service..."
-crond -f -d 8 > /dev/null 2>&1 &
-
-echo -e "
-            [ENV] PATH                      is ${PATH}
-            [ENV] PORT                      is ${PORT}
-            [ENV] TZ                        is ${TZ}
-            [ENV] LISTEN_ADDR               is ${LISTEN_ADDR}
-            [ENV] ALWAYS_FRESH_INSTALL      is ${ALWAYS_FRESH_INSTALL}
-        "

dockerfiles/start.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+export INSTALL_DIR=/app
+export APP_NAME=netalertx
+
+# php-fpm setup
+install -d -o nginx -g www-data /run/php/
+sed -i "/^;pid/c\pid = /run/php/php8.3-fpm.pid" /etc/php83/php-fpm.conf
+sed -i "/^listen/c\listen = /run/php/php8.3-fpm.sock" /etc/php83/php-fpm.d/www.conf
+sed -i "/^;listen.owner/c\listen.owner = nginx" /etc/php83/php-fpm.d/www.conf
+sed -i "/^;listen.group/c\listen.group = www-data" /etc/php83/php-fpm.d/www.conf
+sed -i "/^user/c\user = nginx" /etc/php83/php-fpm.d/www.conf
+sed -i "/^group/c\group = www-data" /etc/php83/php-fpm.d/www.conf
+
+# s6 overlay setup
+mkdir -p /etc/s6-overlay/s6-rc.d/{SetupOneshot,crond/dependencies.d,php-fpm/dependencies.d,nginx/dependencies.d,$APP_NAME/dependencies.d}
+echo "oneshot" > /etc/s6-overlay/s6-rc.d/SetupOneshot/type
+echo "longrun" > /etc/s6-overlay/s6-rc.d/crond/type
+echo "longrun" > /etc/s6-overlay/s6-rc.d/php-fpm/type
+echo "longrun" > /etc/s6-overlay/s6-rc.d/nginx/type
+echo "longrun" > /etc/s6-overlay/s6-rc.d/$APP_NAME/type
+echo -e "${INSTALL_DIR}/dockerfiles/init.sh" > /etc/s6-overlay/s6-rc.d/SetupOneshot/up
+echo -e '#!/bin/execlineb -P
+
+        if { echo
+        "
+            [INSTALL] Starting crond service...
+
+        " }' > /etc/s6-overlay/s6-rc.d/crond/run
+echo -e "/usr/sbin/crond -f" >> /etc/s6-overlay/s6-rc.d/crond/run
+echo -e "#!/bin/execlineb -P\n/usr/sbin/php-fpm83 -F" > /etc/s6-overlay/s6-rc.d/php-fpm/run
+echo -e '#!/bin/execlineb -P\nnginx -g "daemon off;"' > /etc/s6-overlay/s6-rc.d/nginx/run
+echo -e '#!/bin/execlineb -P
+        with-contenv
+
+        importas -u PORT PORT
+
+        if { echo
+        "
+            [INSTALL] 🚀 Starting app (:${PORT})
+
+        " }' > /etc/s6-overlay/s6-rc.d/$APP_NAME/run
+echo -e "python ${INSTALL_DIR}/server" >> /etc/s6-overlay/s6-rc.d/$APP_NAME/run
+touch /etc/s6-overlay/s6-rc.d/user/contents.d/{SetupOneshot,crond,php-fpm,nginx,$APP_NAME} /etc/s6-overlay/s6-rc.d/{crond,php-fpm,nginx,$APP_NAME}/dependencies.d/SetupOneshot
+touch /etc/s6-overlay/s6-rc.d/nginx/dependencies.d/php-fpm
+touch /etc/s6-overlay/s6-rc.d/$APP_NAME/dependencies.d/nginx
+
+# this removes the current file
+rm -f $0

docs/API.md

@@ -1,7 +1,136 @@
-## API endpoints
+# API endpoints
 
-NetAlertX comes with a simple API. These API endpoints are static files, that are periodically updated based on your settings. 
+NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the `API_TOKEN` settings as authorization bearer, for example:
 
+```graphql
+curl 'http://host:GRAPHQL_PORT/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer API_TOKEN' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetDevices($options: PageQueryOptionsInput) { devices(options: $options) { devices { rowid devMac devName devOwner devType devVendor devLastConnection devStatus } count } }",
+    "variables": {
+      "options": {
+        "page": 1,
+        "limit": 10,
+        "sort": [{ "field": "devName", "order": "asc" }],
+        "search": "",
+        "status": "connected"
+      }
+    }
+  }'
+```
+
+## API Endpoint: GraphQL
+
+- Endpoint URL: `php/server/query_graphql.php`
+- Host: `same as front end (web ui)`
+- Port: `20212` or as defined by the `GRAPHQL_PORT` setting
+
+### Example Query to Fetch Devices
+
+First, let's define the GraphQL query to fetch devices with pagination and sorting options.
+
+```graphql
+query GetDevices($options: PageQueryOptionsInput) {
+  devices(options: $options) {
+    devices {
+      rowid
+      devMac
+      devName
+      devOwner
+      devType
+      devVendor
+      devLastConnection
+      devStatus
+    }
+    count
+  }
+}
+```
+
+See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
+
+### `curl` Command
+
+You can use the following `curl` command to execute the query. 
+
+```sh
+curl 'http://host:GRAPHQL_PORT/graphql'   -X POST   -H 'Authorization: Bearer API_TOKEN'  -H 'Content-Type: application/json'   --data '{
+    "query": "query GetDevices($options: PageQueryOptionsInput) { devices(options: $options) { devices { rowid devMac devName devOwner devType devVendor devLastConnection devStatus } count } }",
+    "variables": {
+      "options": {
+        "page": 1,
+        "limit": 10,
+        "sort": [{ "field": "devName", "order": "asc" }],
+        "search": "",
+        "status": "connected"
+      }
+    }
+  }'
+```
+
+### Explanation:
+
+1. **GraphQL Query**:
+   - The `query` parameter contains the GraphQL query as a string.
+   - The `variables` parameter contains the input variables for the query.
+
+2. **Query Variables**:
+   - `page`: Specifies the page number of results to fetch.
+   - `limit`: Specifies the number of results per page.
+   - `sort`: Specifies the sorting options, with `field` being the field to sort by and `order` being the sort order (`asc` for ascending or `desc` for descending).
+   - `search`: A search term to filter the devices.
+   - `status`: The status filter to apply (valid values are `my_devices` (determined by the `UI_MY_DEVICES` setting), `connected`, `favorites`, `new`, `down`, `archived`, `offline`).
+
+3. **`curl` Command**:
+   - The `-X POST` option specifies that we are making a POST request.
+   - The `-H "Content-Type: application/json"` option sets the content type of the request to JSON.
+   - The `-d` option provides the request payload, which includes the GraphQL query and variables.
+
+### Sample Response
+
+The response will be in JSON format, similar to the following:
+
+```json
+{
+  "data": {
+    "devices": {
+      "devices": [
+        {
+          "rowid": 1,
+          "devMac": "00:11:22:33:44:55",
+          "devName": "Device 1",
+          "devOwner": "Owner 1",
+          "devType": "Type 1",
+          "devVendor": "Vendor 1",
+          "devLastConnection": "2025-01-01T00:00:00Z",
+          "devStatus": "connected"
+        },
+        {
+          "rowid": 2,
+          "devMac": "66:77:88:99:AA:BB",
+          "devName": "Device 2",
+          "devOwner": "Owner 2",
+          "devType": "Type 2",
+          "devVendor": "Vendor 2",
+          "devLastConnection": "2025-01-02T00:00:00Z",
+          "devStatus": "connected"
+        }
+      ],
+      "count": 2
+    }
+  }
+}
+```
+
+## API Endpoint: JSON files 
+
+This API endpoint retrieves static files, that are periodically updated. 
+
+- Endpoint URL: `php/server/query_json.php?file=<file name>`
+- Host: `same as front end (web ui)`
+- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
 
 ### When are the endpoints updated
 
@@ -9,7 +138,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/front/api/` folder and thus on the `<netalertx_url>/api/<File name>` url.
+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.
 
 ### Available endpoints
 
@@ -17,20 +146,16 @@ You can access the following files:
 
   | File name | Description | 
   |----------------------|----------------------| 
-  | `notification_text.txt` | The plain text version of the last notification. |
-  | `notification_text.html` | The full HTML of the last email notification. |
   | `notification_json_final.json` | The json version of the last notification (e.g. used for webhooks - [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json)). |
-  | `table_devices.json` | The current (at the time of the last update as mentioned above on this page) state of all of the available Devices detected by the app. |  
-  | `table_pholus_scan.json` | The latest state of the [pholus](https://github.com/jokob-sk/NetAlertX/tree/main/pholus) (A multicast DNS and DNS Service Discovery Security Assessment Tool) scan results. |
+  | `table_devices.json` | All of the available Devices detected by the app. |  
   | `table_plugins_events.json` | The list of the unprocessed (pending) notification events (plugins_events DB table). |
   | `table_plugins_history.json` | The list of notification events history. |  
-  | `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins)|
+  | `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md)|
   | `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |  
   | `table_custom_endpoint.json` | A custom endpoint generated by the SQL query specified by the `API_CUSTOM_SQL` setting. |
   | `table_settings.json` | The content of the settings table. |
   | `app_state.json` | Contains the current application state. |
   
-  Current/latest state of the aforementioned files depends on your settings.
 
 ### JSON Data format
 
@@ -58,41 +183,79 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row
 {
   "data": [
         {
-          "dev_MAC": "Internet",
-          "dev_Name": "Net - Huawei",
-          "dev_DeviceType": "Router",
-          "dev_Vendor": null,
-          "dev_Group": "Always on",
-          "dev_FirstConnection": "2021-01-01 00:00:00",
-          "dev_LastConnection": "2021-01-28 22:22:11",
-          "dev_LastIP": "192.168.1.24",
-          "dev_StaticIP": 0,
-          "dev_PresentLastScan": 1,
-          "dev_LastNotification": "2023-01-28 22:22:28.998715",
-          "dev_NewDevice": 0,
-          "dev_Network_Node_MAC_ADDR": "",
-          "dev_Network_Node_port": "",
-          "dev_Icon": "globe"
+          "devMac": "Internet",
+          "devName": "Net - Huawei",
+          "devType": "Router",
+          "devVendor": null,
+          "devGroup": "Always on",
+          "devFirstConnection": "2021-01-01 00:00:00",
+          "devLastConnection": "2021-01-28 22:22:11",
+          "devLastIP": "192.168.1.24",
+          "devStaticIP": 0,
+          "devPresentLastScan": 1,
+          "devLastNotification": "2023-01-28 22:22:28.998715",
+          "devIsNew": 0,
+          "devParentMAC": "",
+          "devParentPort": "",
+          "devIcon": "globe"
         }, 
         {
-          "dev_MAC": "a4:8f:ff:aa:ba:1f",
-          "dev_Name": "Net - USG",
-          "dev_DeviceType": "Firewall",
-          "dev_Vendor": "Ubiquiti Inc",
-          "dev_Group": "",
-          "dev_FirstConnection": "2021-02-12 22:05:00",
-          "dev_LastConnection": "2021-07-17 15:40:00",
-          "dev_LastIP": "192.168.1.1",
-          "dev_StaticIP": 1,
-          "dev_PresentLastScan": 1,
-          "dev_LastNotification": "2021-07-17 15:40:10.667717",
-          "dev_NewDevice": 0,
-          "dev_Network_Node_MAC_ADDR": "Internet",
-          "dev_Network_Node_port": 1,
-          "dev_Icon": "shield-halved"
+          "devMac": "a4:8f:ff:aa:ba:1f",
+          "devName": "Net - USG",
+          "devType": "Firewall",
+          "devVendor": "Ubiquiti Inc",
+          "devGroup": "",
+          "devFirstConnection": "2021-02-12 22:05:00",
+          "devLastConnection": "2021-07-17 15:40:00",
+          "devLastIP": "192.168.1.1",
+          "devStaticIP": 1,
+          "devPresentLastScan": 1,
+          "devLastNotification": "2021-07-17 15:40:10.667717",
+          "devIsNew": 0,
+          "devParentMAC": "Internet",
+          "devParentPort": 1,
+          "devIcon": "shield-halved"
       }
     ]
 }
 
 ```
 
+## API Endpoint: /log files
+
+This API endpoint retrieves files from the `/app/log` folder. 
+
+- Endpoint URL: `php/server/query_logs.php?file=<file name>`
+- Host: `same as front end (web ui)`
+- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
+
+| File                     | Description                                                   |
+|--------------------------|---------------------------------------------------------------|
+| `IP_changes.log`         | Logs of IP address changes                                    |
+| `app.log`                | Main application log                                          |
+| `app.php_errors.log`     | PHP error log                                                 |
+| `app_front.log`          | Frontend application log                                      |
+| `app_nmap.log`           | Logs of Nmap scan results                                     |
+| `db_is_locked.log`       | Logs when the database is locked                              |
+| `execution_queue.log`    | Logs of execution queue activities                            |
+| `plugins/`               | Directory for temporary plugin-related files (not accessible) |
+| `report_output.html`     | HTML report output                                            |
+| `report_output.json`     | JSON format report output                                     |
+| `report_output.txt`      | Text format report output                                     |
+| `stderr.log`             | Logs of standard error output                                 |
+| `stdout.log`             | Logs of standard output                                       |
+
+
+## API Endpoint: /config files
+
+To retrieve files from the `/app/config` folder. 
+
+- Endpoint URL: `php/server/query_config.php?file=<file name>`
+- Host: `same as front end (web ui)`
+- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
+
+| File                     | Description                                      |
+|--------------------------|--------------------------------------------------|
+| `devices.csv`            | Devices csv file                                 |
+| `app.conf`               | Application config file                          |
+

docs/AUTHELIA.md

@@ -0,0 +1,277 @@
+## Authelia support
+
+> [!WARNING] 
+>
+> This is community contributed content and work in progress. Contributions are welcome. 
+
+```yaml
+theme: dark
+
+default_2fa_method: "totp"
+
+server:
+  address: 0.0.0.0:9091
+  endpoints:
+    enable_expvars: false
+    enable_pprof: false
+    authz:
+      forward-auth:
+        implementation: 'ForwardAuth'
+        authn_strategies:
+          - name: 'HeaderAuthorization'
+            schemes:
+              - 'Basic'
+          - name: 'CookieSession'
+      ext-authz:
+        implementation: 'ExtAuthz'
+        authn_strategies:
+          - name: 'HeaderAuthorization'
+            schemes:
+              - 'Basic'
+          - name: 'CookieSession'
+      auth-request:
+        implementation: 'AuthRequest'
+        authn_strategies:
+          - name: 'HeaderAuthRequestProxyAuthorization'
+            schemes:
+              - 'Basic'
+          - name: 'CookieSession'
+      legacy:
+        implementation: 'Legacy'
+        authn_strategies:
+          - name: 'HeaderLegacy'
+          - name: 'CookieSession'
+  disable_healthcheck: false
+  tls:
+    key: ""
+    certificate: ""
+    client_certificates: []
+  headers:
+    csp_template: ""
+
+log:
+  ## Level of verbosity for logs: info, debug, trace.
+  level: info
+
+###############################################################
+# The most important section
+###############################################################
+access_control:
+  ## Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'.
+  default_policy: deny
+  networks:
+    - name: internal
+      networks:
+        - '192.168.0.0/18'
+        - '10.10.10.0/8' # Zerotier
+    - name: private
+      networks:
+        - '172.16.0.0/12'
+  rules:
+    - networks:
+        - private
+      domain:
+        - '*'
+      policy: bypass
+    - networks:
+        - internal
+      domain:
+        - '*'
+      policy: bypass
+    - domain:
+        # exclude itself from auth, should not happen as we use Traefik middleware on a case-by-case screnario
+        - 'auth.MYDOMAIN1.TLD'
+        - 'authelia.MYDOMAIN1.TLD'
+        - 'auth.MYDOMAIN2.TLD'
+        - 'authelia.MYDOMAIN2.TLD'
+      policy: bypass
+    - domain:
+        #All subdomains match
+        - 'MYDOMAIN1.TLD'
+        - '*.MYDOMAIN1.TLD'
+      policy: two_factor
+    - domain:
+        # This will not work yet as Authelio does not support multi-domain authentication
+        - 'MYDOMAIN2.TLD'
+        - '*.MYDOMAIN2.TLD'
+      policy: two_factor
+
+
+############################################################
+identity_validation:
+  reset_password:
+    jwt_secret: "[REDACTED]"
+
+identity_providers:
+  oidc:
+    enable_client_debug_messages: true
+    enforce_pkce: public_clients_only
+    hmac_secret: [REDACTED]
+    lifespans:
+      authorize_code: 1m
+      id_token: 1h
+      refresh_token: 90m
+      access_token: 1h
+    cors:
+      endpoints:
+        - authorization
+        - token
+        - revocation
+        - introspection
+        - userinfo
+      allowed_origins:
+        - "*"
+      allowed_origins_from_client_redirect_uris: false
+    jwks:
+      - key: [REDACTED]
+        certificate_chain:
+    clients:
+      - client_id: portainer
+        client_name: Portainer
+        # generate secret with "authelia crypto hash generate pbkdf2 --random --random.length 32 --random.charset alphanumeric"
+        # Random Password: [REDACTED]
+        # Digest: [REDACTED]
+        client_secret: [REDACTED]
+        token_endpoint_auth_method: 'client_secret_post'
+        public: false
+        authorization_policy: two_factor
+        consent_mode: pre-configured #explicit
+        pre_configured_consent_duration: '6M' #Must be re-authorised every 6 Months
+        scopes:
+          - openid
+          #- groups #Currently not supported in Authelia V
+          - email
+          - profile
+        redirect_uris:
+          - https://portainer.MYDOMAIN1.LTD
+        userinfo_signed_response_alg: none
+
+      - client_id: openproject
+        client_name: OpenProject
+        # generate secret with "authelia crypto hash generate pbkdf2 --random --random.length 32 --random.charset alphanumeric"
+        # Random Password: [REDACTED]
+        # Digest: [REDACTED]
+        client_secret: [REDACTED]
+        token_endpoint_auth_method: 'client_secret_basic'
+        public: false
+        authorization_policy: two_factor
+        consent_mode: pre-configured #explicit
+        pre_configured_consent_duration: '6M' #Must be re-authorised every 6 Months
+        scopes:
+          - openid
+          #- groups #Currently not supported in Authelia V
+          - email
+          - profile
+        redirect_uris:
+          - https://op.MYDOMAIN.TLD
+        #grant_types:
+        #  - refresh_token
+        #  - authorization_code
+        #response_types:
+        #  - code
+        #response_modes:
+        #  - form_post
+        #  - query
+        #  - fragment
+        userinfo_signed_response_alg: none
+##################################################################
+
+
+telemetry:
+  metrics:
+    enabled: false
+    address: tcp://0.0.0.0:9959
+
+totp:
+  disable: false
+  issuer: authelia.com
+  algorithm: sha1
+  digits: 6
+  period: 30 ## The period in seconds a one-time password is valid for.
+  skew: 1
+  secret_size: 32
+
+webauthn:
+  disable: false
+  timeout: 60s ## Adjust the interaction timeout for Webauthn dialogues.
+  display_name: Authelia
+  attestation_conveyance_preference: indirect
+  user_verification: preferred
+
+ntp:
+  address: "pool.ntp.org"
+  version: 4
+  max_desync: 5s
+  disable_startup_check: false
+  disable_failure: false
+
+authentication_backend:
+  password_reset:
+    disable: false
+    custom_url: ""
+  refresh_interval: 5m
+  file:
+    path: /config/users_database.yml
+    watch: true
+    password:
+      algorithm: argon2
+      argon2:
+        variant: argon2id
+        iterations: 3
+        memory: 65536
+        parallelism: 4
+        key_length: 32
+        salt_length: 16
+
+password_policy:
+  standard:
+    enabled: false
+    min_length: 8
+    max_length: 0
+    require_uppercase: true
+    require_lowercase: true
+    require_number: true
+    require_special: true
+  ## zxcvbn is a well known and used password strength algorithm. It does not have tunable settings.
+  zxcvbn:
+    enabled: false
+    min_score: 3
+
+regulation:
+  max_retries: 3
+  find_time: 2m
+  ban_time: 5m
+
+session:
+  name: authelia_session
+  secret: [REDACTED]
+  expiration: 60m
+  inactivity: 15m
+  cookies:
+    - domain: 'MYDOMAIN1.LTD'
+      authelia_url: 'https://auth.MYDOMAIN1.LTD'
+      name: 'authelia_session'
+      default_redirection_url: 'https://MYDOMAIN1.LTD'
+    - domain: 'MYDOMAIN2.LTD'
+      authelia_url: 'https://auth.MYDOMAIN2.LTD'
+      name: 'authelia_session_other'
+      default_redirection_url: 'https://MYDOMAIN2.LTD'
+
+storage:
+  encryption_key: [REDACTED]
+  local:
+    path: /config/db.sqlite3
+
+notifier:
+  disable_startup_check: true
+  smtp:
+    address: MYOTHERDOMAIN.LTD:465
+    timeout: 5s
+    username: "USER@DOMAIN"
+    password: "[REDACTED]"
+    sender: "Authelia <postmaster@MYOTHERDOMAIN.LTD>"
+    identifier: NAME@MYOTHERDOMAIN.LTD
+    subject: "[Authelia] {title}"
+    startup_check_address: postmaster@MYOTHERDOMAIN.LTD
+
+```

docs/BACKUPS.md

@@ -1,15 +1,59 @@
-# 💾 Backing things up
+# Backing things up
 
 > [!NOTE]
-> To backup 99% of your configuration backup at least the `/config` folder. Please read the whole page (or at least "Scenario 2: Corrupted database") for details.
+> To backup 99% of your configuration backup at least the `/app/config` folder. Please read the whole page (or at least "Scenario 2: Corrupted database") for details.
+> Note that database definitions might change over time. The safest way is to restore your older backups into the **same version** of the app they were taken from and then gradually upgarde between releases to the latest version.
 
-There are 3 artifacts that can be used to backup the application:
+There are 4 artifacts that can be used to backup the application:
 
 | File                  | Description                   | Limitations                   |
 |-----------------------|-------------------------------|-------------------------------|
 | `/db/app.db`       | Database file(s)  | The database file might be in an uncommitted state or corrupted |
-| `/config/app.conf` | Configuration file |   Doesn't contain settings from the Maintenance section        |
+| `/config/app.conf` | Configuration file |  Can be overridden with the [`APP_CONF_OVERRIDE` env variable](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables).  |
 | `/config/devices.csv`  | CSV file containing device information |     Doesn't contain historical data        |
+| `/config/workflows.json`  | A JSON file containing your workflows |     N/A        |
+
+
+## Backup strategies
+
+The safest approach to backups is to backup everything, by taking regular file system backups of the `/db` and `/config` folders (I use [Kopia](https://github.com/kopia/kopia)). 
+
+Arguably, the most time is spent setting up the device list, so if only one file is kept I'd recommend to have a latest backup of the `devices_<timestamp>.csv` or `devices.csv` file, followed by the `app.conf` and `workflows.json` files. You can also download `app.conf` and `devices.csv` file in the Maintenance section:
+
+![Backup and Restore Section in Maintenance](./img/BACKUPS/Maintenance_Backup_Restore.png)
+
+### Scenario 1: Full backup
+
+End-result: Full restore
+
+#### 💾 Source artifacts:
+
+- `/app/db/app.db` (uncorrupted)
+- `/app/config/app.conf`
+- `/app/config/workflows.json`
+
+#### 📥 Recovery:
+
+To restore the application map the above files as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths). 
+
+
+### Scenario 2: Corrupted database
+
+End-result: Partial restore (historical data and some plugin data will be missing)
+
+#### 💾 Source artifacts:
+
+- `/app/config/app.conf`
+- `/app/config/devices_<timestamp>.csv` or `/app/config/devices.csv`
+- `/app/config/workflows.json`
+
+#### 📥 Recovery:
+
+Even with a corrupted database you can recover what I would argue is 99% of the configuration. 
+
+- upload the `app.conf` and `workflows.json` files into the mounted `/app/config/` folder as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
+- rename the `devices_<timestamp>.csv` to `devices.csv` and place it in the `/app/config` folder
+- Restore the `devices.csv` backup via the [Maintenance section](./DEVICES_BULK_EDITING.md)
 
 ## Data and backup storage
 
@@ -17,66 +61,30 @@ To decide on a backup strategy, check where the data is stored:
 
 ### Core Configuration
 
-The core application configuration is in the `app.conf` file (See [Settings System](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SETTINGS_SYSTEM.md) for details), such as:
+The core application configuration is in the `app.conf` file (See [Settings System](./SETTINGS_SYSTEM.md) for details), such as:
 
 - Notification settings
 - Scanner settings
 - Scheduled maintenance settings
-- UI configuration (80%)
+- UI configuration
 
 ### Core Device Data
 
-The core device data is backed up to the `devices_<timestamp>.csv` file via the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup). This file contains data, such as:
+The core device data is backed up to the `devices_<timestamp>.csv` or `devices.csv` file via the [CSV Backup `CSVBCKP` Plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup). This file contains data, such as:
 
 - Device names
-- Device Icons
-- Device Network configuration
+- Device icons
+- Device network configuration
 - Device categorization 
+- Device custom properties data
 
 ### Historical data
 
-Historical data is stored in the `app.db` database (See [Database overview](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DATABASE.md) for details). This data includes:
+Historical data is stored in the `app.db` database (See [Database overview](./DATABASE.md) for details). This data includes:
 
 - Plugin objects
 - Plugin historical entries
 - History of Events, Notifications, Workflow Events
-- Presence History
-
-## 🧭 Backup strategies
-
-The safest approach to backups is to backup all of the above, by taking regular file system backups (I use [Kopia](https://github.com/kopia/kopia)). 
-
-Arguably, the most time is spent setting up the device list, so if only one file is kept I'd recommend to have a latest backup of the `devices_<timestamp>.csv` file, followed by the `app.conf` file. 
-
-### Scenario 1: Full backup
-
-End-result: Full restore
-
-#### Source artifacts:
-
-- `/db/app.db` (uncorrupted)
-- `/config/app.conf`
-
-#### Recovery:
-
-To restore the application map the above files as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths). 
-
-
-### Scenario 2: Corrupted database
-
-End-result: Partial restore (historical data & configurations from the Maintenance section will be missing)
-
-#### Source artifacts:
-
-- `/config/app.conf`
-- `/config/devices_<timestamp>.csv` or `/config/devices.csv`
-
-#### Recovery:
-
-Even with a corrupted database you can recover what I would argue is 99% of the configuration (except of a couple of settings under Maintenance). 
-
-- map the `/config/app.conf` file as described in the [Setup documentation](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#docker-paths).
-- rename the `devices_<timestamp>.csv` to `devices.csv` and place it in the `/config` folder
-- Restore the `devices.csv` backup via the [Maintenance section](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)
+- Presence history
 
 

docs/COMMON_ISSUES.md

@@ -0,0 +1,57 @@
+### Loading...
+
+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. 
+
+### 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.
+
+### Duplicate devices and notifications
+
+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.
+
+* 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`. 
+* 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`. 
+* 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
+
+* Check the logs for details. Often a required setting for a notification method is missing. 
+
+### unable to resolve host
+
+* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See the [subnets docs for details](./SUBNETS.md).  
+
+### Invalid JSON
+
+Check the [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) docs on how to proceed.
+
+### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 
+
+> sudo: unexpected child termination condition: 0
+
+Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581)
+
+```
+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.
+
+### 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.
+
+### Losing my settings and devices after an update
+
+If you lose your devices and/or settings after an update that means you don't have the `/app/db` and `/app/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command.
+
+
+### The application is slow
+
+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/COMMUNITY_GUIDES.md

@@ -0,0 +1,15 @@
+# Community Guides
+
+Use the official installation guides at first and use community content as supplementary material. Open an issue or PR if you'd like to add your link to the list 🙏 (Ordered by last update time)
+
+- ▶ [Discover & Monitor Your Network with This Self-Hosted Open Source Tool - Lawrence Systems](https://www.youtube.com/watch?v=R3b5cxLZMpo) (June 2025)
+- ▶ [Home Lab Network Monitoring - Scotti-BYTE Enterprise Consulting Services](https://www.youtube.com/watch?v=0DryhzrQSJA) (July 2024)
+- 📄 [How to Install NetAlertX on Your Synology NAS - Marius hosting](https://mariushosting.com/how-to-install-pi-alert-on-your-synology-nas/) (Updated frequently)
+- 📄 [Using the PiAlert Network Security Scanner on a Raspberry Pi - PiMyLifeUp](https://pimylifeup.com/raspberry-pi-pialert/)
+- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg) 
+- 📄 [防蹭网神器，网络安全助手 | 极空间部署网络扫描和通知系统『NetAlertX』](https://blog.csdn.net/qq_63499861/article/details/141105273)
+- 📄 [시놀/헤놀에서 네트워크 스캐너 Pi.Alert Docker로 설치 및 사용하기](https://blog.dalso.org/article/%EC%8B%9C%EB%86%80-%ED%97%A4%EB%86%80%EC%97%90%EC%84%9C-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-%EC%8A%A4%EC%BA%90%EB%84%88-pi-alert-docker%EB%A1%9C-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%82%AC%EC%9A%A9) (July 2023)
+- 📄 [网络入侵探测器Pi.Alert (Chinese)](https://codeantenna.com/a/VgUvIAjZ7J) (May 2023)
+- ▶ [Pi.Alert auf Synology & Docker by - Jürgen Barth](https://www.youtube.com/watch?v=-ouvA2UNu-A) (March 2023)
+- ▶ [Top Docker Container for Home Server Security - VirtualizationHowto](https://www.youtube.com/watch?v=tY-w-enLF6Q) (March 2023)
+- ▶ [Pi.Alert or WatchYourLAN can alert you to unknown devices appearing on your WiFi or LAN network - Danie van der Merwe](https://www.youtube.com/watch?v=v6an9QG2xF0) (November 2022)

docs/CUSTOM_PROPERTIES.md

@@ -0,0 +1,85 @@
+# Custom Properties for Devices
+
+![Custom Properties](./img/CUSTOM_PROPERTIES/Device_Custom_Properties.png)
+
+## Overview
+
+This functionality allows you to define **custom properties** for devices, which can store and display additional information on the device listing page. By marking properties as "Show", you can enhance the user interface with quick actions, notes, or external links.
+
+### Key Features:
+- **Customizable Properties**: Define specific properties for each device.
+- **Visibility Control**: Choose which properties are displayed on the device listing page.
+- **Interactive Elements**: Include actions like links, modals, and device management directly in the interface.
+
+---
+
+## Defining Custom Properties
+
+Custom properties are structured as a list of objects, where each property includes the following fields:
+
+| Field             | Description                                                                 |
+|--------------------|-----------------------------------------------------------------------------|
+| `CUSTPROP_icon`    | The icon (Base64-encoded HTML) displayed for the property.                 |
+| `CUSTPROP_type`    | The action type (e.g., `show_notes`, `link`, `delete_dev`).                |
+| `CUSTPROP_name`    | A short name or title for the property.                                    |
+| `CUSTPROP_args`    | Arguments for the action (e.g., URL or modal text).                        |
+| `CUSTPROP_notes`   | Additional notes or details displayed when applicable.                    |
+| `CUSTPROP_show`    | A boolean to control visibility (`true` to show on the listing page).      |
+
+---
+
+## Available Action Types
+
+- **Show Notes**: Displays a modal with a title and additional notes.
+  - **Example**: Show firmware details or custom messages.
+- **Link**: Redirects to a specified URL in the current browser tab. (**Arguments** Needs to contain the full URL.)
+- **Link (New Tab)**: Opens a specified URL in a new browser tab. (**Arguments** Needs to contain the full URL.)
+- **Delete Device**: Deletes the device using its MAC address.
+- **Run Plugin**: Placeholder for executing custom plugins (not implemented yet).
+
+---
+
+## Usage on the Device Listing Page
+
+![Custom Properties](./img/CUSTOM_PROPERTIES/Device_Custom_Properties_vid.gif)
+
+Visible properties (`CUSTPROP_show: true`) are displayed as interactive icons in the device listing. Each icon can perform one of the following actions based on the `CUSTPROP_type`:
+
+1. **Modals (e.g., Show Notes)**:
+   - Displays detailed information in a popup modal.
+   - Example: Firmware version details.
+
+2. **Links**:
+   - Redirect to an external or internal URL.
+   - Example: Open a device's documentation or external site.
+
+3. **Device Actions**:
+   - Manage devices with actions like delete.
+   - Example: Quickly remove a device from the network.
+
+4. **Plugins**:
+   - Future placeholder for running custom plugin scripts.
+   - **Note**: Not implemented yet.
+
+---
+
+## Example Use Cases
+
+1. **Device Documentation Link**:
+   - Add a custom property with `CUSTPROP_type` set to `link` or `link_new_tab` to allow quick navigation to the external documentation of the device.
+
+2. **Firmware Details**:
+   - Use `CUSTPROP_type: show_notes` to display firmware versions or upgrade instructions in a modal.
+
+3. **Device Removal**:
+   - Enable device removal functionality using `CUSTPROP_type: delete_dev`.
+
+---
+
+## Notes
+
+- **Plugin Functionality**: The `run_plugin` action type is currently not implemented and will show an alert if used.
+- **Custom Icons (Experimental 🧪)**: Use Base64-encoded HTML to provide custom icons for each property. You can add your icons in Setttings via the `CUSTPROP_icon` settings 
+- **Visibility Control**: Only properties with `CUSTPROP_show: true` will appear on the listing page.
+
+This feature provides a flexible way to enhance device management and display with interactive elements tailored to your needs.

docs/DATABASE.md

@@ -1,11 +1,54 @@
   
-  # A high-level description of the database structure
+# A high-level description of the database structure
 
-  ⚠ Disclaimer: As I'm not the original author, some of the information might be inaccurate. Feel free to submit a PR to correct anything within this page or documentation in general. 
+ An overview of the most important database tables as well as an detailed overview of the Devices table. The MAC address is used as a foreign key in most cases. 
 
-  The MAC address is used as a foreign key in most cases. 
+## Devices database table
 
-  ## 🔍Tables overview
+| Field Name              | Description | Sample Value |
+|-------------------------|-------------|--------------|
+| `devMac`               | MAC address of the device. | `00:1A:2B:3C:4D:5E` |
+| `devName`              | Name of the device. | `iPhone 12` |
+| `devOwner`             | Owner of the device. | `John Doe` |
+| `devType`              | Type of the device (e.g., phone, laptop, etc.). If set to a network type (e.g., switch), it will become selectable as a Network Parent Node. | `Laptop` |
+| `devVendor`            | Vendor/manufacturer of the device. | `Apple` |
+| `devFavorite`          | Whether the device is marked as a favorite. | `1` |
+| `devGroup`             | Group the device belongs to. | `Home Devices` |
+| `devComments`          | User comments or notes about the device. | `Used for work purposes` |
+| `devFirstConnection`   | Timestamp of the device's first connection. | `2025-03-22 12:07:26+11:00` |
+| `devLastConnection`    | Timestamp of the device's last connection. | `2025-03-22 12:07:26+11:00` |
+| `devLastIP`            | Last known IP address of the device. | `192.168.1.5` |
+| `devStaticIP`          | Whether the device has a static IP address. | `0` |
+| `devScan`              | Whether the device should be scanned. | `1` |
+| `devLogEvents`         | Whether events related to the device should be logged. | `0` |
+| `devAlertEvents`       | Whether alerts should be generated for events. | `1` |
+| `devAlertDown`         | Whether an alert should be sent when the device goes down. | `0` |
+| `devSkipRepeated`      | Whether to skip repeated alerts for this device. | `1` |
+| `devLastNotification`  | Timestamp of the last notification sent for this device. | `2025-03-22 12:07:26+11:00` |
+| `devPresentLastScan`   | Whether the device was present during the last scan. | `1` |
+| `devIsNew`             | Whether the device is marked as new. | `0` |
+| `devLocation`          | Physical or logical location of the device. | `Living Room` |
+| `devIsArchived`        | Whether the device is archived. | `0` |
+| `devParentMAC`         | MAC address of the parent device (if applicable) to build the [Network Tree](./NETWORK_TREE.md). | `00:1A:2B:3C:4D:5F` |
+| `devParentPort`        | Port of the parent device to which this device is connected. | `Port 3` |
+| `devIcon`              | [Icon](./ICONS.md) representing the device. The value is a base64-encoded SVG or Font Awesome HTML tag. | `PHN2ZyB...` |
+| `devGUID`              | Unique identifier for the device. | `a2f4b5d6-7a8c-9d10-11e1-f12345678901` |
+| `devSite`              | Site or location where the device is registered. | `Office` |
+| `devSSID`              | SSID of the Wi-Fi network the device is connected to. | `HomeNetwork` |
+| `devSyncHubNode`       | The NetAlertX node ID used for synchronization between NetAlertX instances. | `node_1` |
+| `devSourcePlugin`      | Source plugin that discovered the device. | `ARPSCAN` |
+| `devCustomProps`       | [Custom properties](./CUSTOM_PROPERTIES.md) related to the device. The value is a base64-encoded JSON object. | `PHN2ZyB...` |
+| `devFQDN`              | Fully qualified domain name. | `raspberrypi.local` |
+
+
+To understand how values of these fields influuence application behavior, such as Notifications or Network topology, see also: 
+
+- [Device Management](./DEVICE_MANAGEMENT.md)
+- [Network Tree Topology Setup](./NETWORK_TREE.md)
+- [Notifications](./NOTIFICATIONS.md)
+
+
+## Other Tables overview
   
   | Table name | Description  | Sample data |
   |----------------------|----------------------| ----------------------| 
@@ -14,7 +57,6 @@
   | Events | Used to collect connection/disconnection events. | ![Screen4][screen4]  |   
   | Online_History   | Used to display the `Device presence` chart  | ![Screen6][screen6]  | 
   | Parameters       | Used to pass values between the frontend and backend. | ![Screen7][screen7]  | 
-  | Pholus_Scan      | Scan results of the Pholus python network penetration script. | ![Screen8][screen8]  |   
   | Plugins_Events   | For capturing events exposed by a plugin via the `last_result.log` file. If unique then saved into the `Plugins_Objects` table. Entries are deleted once processed and stored in the `Plugins_History` and/or `Plugins_Objects` tables.  | ![Screen10][screen10]  | 
   | Plugins_History  | History of all entries from the `Plugins_Events` table | ![Screen11][screen11]  | 
   | Plugins_Language_Strings  | Language strings collected from the plugin `config.json` files used for string resolution in the frontend. | ![Screen12][screen12]  | 
@@ -24,16 +66,15 @@
 
 
 
-  [screen1]: /docs/img/DATABASE/CurrentScan.png
-  [screen2]: /docs/img/DATABASE/Devices.png
-  [screen4]: /docs/img/DATABASE/Events.png  
-  [screen6]: /docs/img/DATABASE/Online_History.png
-  [screen7]: /docs/img/DATABASE/Parameters.png
-  [screen8]: /docs/img/DATABASE/Pholus_Scan.png  
-  [screen10]: /docs/img/DATABASE/Plugins_Events.png
-  [screen11]: /docs/img/DATABASE/Plugins_History.png
-  [screen12]: /docs/img/DATABASE/Plugins_Language_Strings.png
-  [screen13]: /docs/img/DATABASE/Plugins_Objects.png  
-  [screen15]: /docs/img/DATABASE/Sessions.png
-  [screen16]: /docs/img/DATABASE/Settings.png
+  [screen1]: ./img/DATABASE/CurrentScan.png
+  [screen2]: ./img/DATABASE/Devices.png
+  [screen4]: ./img/DATABASE/Events.png  
+  [screen6]: ./img/DATABASE/Online_History.png
+  [screen7]: ./img/DATABASE/Parameters.png
+  [screen10]: ./img/DATABASE/Plugins_Events.png
+  [screen11]: ./img/DATABASE/Plugins_History.png
+  [screen12]: ./img/DATABASE/Plugins_Language_Strings.png
+  [screen13]: ./img/DATABASE/Plugins_Objects.png  
+  [screen15]: ./img/DATABASE/Sessions.png
+  [screen16]: ./img/DATABASE/Settings.png
 

docs/DEBUG_GRAPHQL.md

@@ -0,0 +1,64 @@
+# Debugging GraphQL server issues
+
+The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. 
+
+The most common issue is that the GraphQL server doesn't start properly, usually due to a **port conflict**. If you are running multiple NetAlertX instances, make sure to use **unique ports** by changing the `GRAPHQL_PORT` setting. The default is `20212`.
+
+## How to update the `GRAPHQL_PORT` in case of issues
+
+As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues.  
+
+### Updating the setting via the Settings UI
+
+Ideally use the Settings UI to update the setting under General -> Core -> GraphQL port:
+
+![GrapQL settings](./img/DEBUG_GRAPHQL/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. 
+
+### Updating the `app.conf` file
+
+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)
+
+### Using a docker variable
+
+All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. 
+
+```yaml
+...
+ environment:
+      - TZ=Europe/Berlin      
+      - PORT=20213
+      - APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"}
+...
+```
+
+## How to check the GraphQL server is running?
+
+There are several ways to check if the GraphQL server is running.
+
+### Init Check
+
+You can navigate to Maintenance -> Init Check to see if `isGraphQLServerRunning` is ticked:
+
+![Init Check](./img/DEBUG_GRAPHQL/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)
+
+### 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)
+
+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)
+
+

docs/DEBUG_PLUGINS.md

@@ -2,14 +2,14 @@
 
 ## High-level overview
 
-If a Plugin supplies data to the main app it's doine either vie a SQL query or via a script that updates the `last_result.log` file in the plugin folder (`front/plugins/<plugin>`).
+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/`).
 
-For a more in-depth overview on how plugins work check the [Plugins development docs](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md).
+For a more in-depth overview on how plugins work check the [Plugins development docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).
 
 ### Prerequisites
 
 - Make sure you read and followed the specific plugin setup instructions.
-- Ensure you have [debug enabled (see More Logging)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#1-more-logging-) 
+- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md) 
 
 ### Potential issues
 
@@ -55,7 +55,7 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo
 17:31:05 [Plugins] SQL sqlParams for mapping: [('01:01:01:01:01:01', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'PIHOLE'), ('02:42:ac:1e:00:02', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'PIHOLE')]
 🔺
 17:31:05 [API] Update API starting
-17:31:06 [API] Updating table_plugins_history.json file in /front/api
+17:31:06 [API] Updating table_plugins_history.json file in /api
 ```
 
 > The debug output between the 🔻red arrows🔺 is important for debugging (arrows added only to highlight the section on this page, they are not available in the actual debug log)
@@ -75,4 +75,17 @@ In the above output notice the section logging how many events are produced by t
 
 These values, if formatted correctly, will also show up in the UI:
 
-![Plugins table](/docs/img/DEBUG_PLUGINS/plugin_objects_pihole.png)
+![Plugins table](./img/DEBUG_PLUGINS/plugin_objects_pihole.png)
+
+
+### 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. 
+
+1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files).
+2. Wait for the issue to occur.
+3. Search for `================ DEVICES table content  ================` in your logs.
+4. Search for `================ CurrentScan table content  ================` in your logs.
+5. Open a new issue and post (redacted) output into the issue description (or send to the netalertx@gmail.com email if sensitive data present).
+6. Please set `LOG_LEVEL` to `debug` or lower.
+

docs/DEBUG_TIPS.md

@@ -2,14 +2,13 @@
 
 Please follow tips 1 - 4 to get a more detailed error. 
 
-## 1. More Logging 📃
+## 1. More Logging 
 
 When debugging an issue always set the highest log level:
 
 `LOG_LEVEL='trace'`
 
-
-## 2. Surfacing errors when container restarts 🔁
+## 2. Surfacing errors when container restarts 
 
 Start the container via the **terminal** with a command similar to this one:
 
@@ -19,23 +18,23 @@ docker run --rm --network=host \
   -v local/path/netalertx/db:/app/db \
   -e TZ=Europe/Berlin \
   -e PORT=20211 \
-  jokobsk/netalertx:latest
+  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.
 
-## 3. Check the _dev image and open issues ❓
+## 3. Check the _dev image and open issues 
 
 If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is:
 
-`jokobsk/netalertx-dev:latest`
+`ghcr.io/jokob-sk/netalertx-dev:latest`
 
 > ⚠ Please backup your DB and config beforehand!
 
 Please also search [open issues](https://github.com/jokob-sk/NetAlertX/issues).
 
-## 4. Disable restart behavior 🛑
+## 4. Disable restart behavior 
 
 To prevent a Docker container from automatically restarting in a Docker Compose file, specify the restart policy as `no`:
 
@@ -49,35 +48,17 @@ services:
     # Other service configurations...
 ```
 
-## 📃Common issues
+## 5. Sharing application state
 
-### Permissions
+Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong. 
 
-* 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/front/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`. 
-* 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)
+1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files).
+2. Wait for the issue to occur.
+3. Search for `================ DEVICES table content  ================` in your logs.
+4. Search for `================ CurrentScan table content  ================` in your logs.
+5. Open a new issue and post (redacted) output into the issue description (or send to the netalertx@gmail.com email if sensitive data present).
+6. Please set `LOG_LEVEL` to `debug` or lower.
 
-### Container restarts / crashes
+## Common issues
 
-* Check the logs for details. Often a required setting for a notification method is missing. 
-
-### unable to resolve host
-
-* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface` as outlined in the instructions above. 
-
-### Invalid JSON
-
-Check the [Invalid JSON errors debug help](/docs/DEBUG_INVALID_JSON.md) docs on how to proceed.
-
-### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 
-
-> sudo: unexpected child termination condition: 0
-
-Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581)
-
-```
-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.
+See [Common issues](./COMMON_ISSUES.md) for details. 

docs/DEVICES_BULK_EDITING.md

@@ -1,14 +1,20 @@
-# 🖊 Multi-editing via the UI
+# Editing multiple devices at once
+
+NetAlertX allows you to mass-edit devices via a CSV export and import feature, or directly in the UI.
+
+## UI multi edit
 
 > [!NOTE] 
-> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](/docs/BACKUPS.md). 
+> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](./BACKUPS.md). 
 
 You can select devices in the _Devices_ view by selecting devices to edit and then clicking the _Multi-edit_ button or via the _Maintenance_ > _Multi-Edit_ section.
 
-![Maintenance > Multi-edit](/docs/img/DEVICES_BULK_EDITING/MULTI-EDIT.gif)
+![Maintenance > Multi-edit](./img/DEVICES_BULK_EDITING/MULTI-EDIT.gif)
 
 
-# 📝Bulk-edit devices via CSV Export/Import
+## CSV bulk edit
+
+The database and device structure may change with new releases. When using the CSV import functionality, ensure the format matches what the application expects. To avoid issues, you can first export the devices and review the column formats before importing any custom data.
 
 > [!NOTE] 
 > As always, backup everything, just in case.
@@ -17,17 +23,19 @@ You can select devices in the _Devices_ view by selecting devices to edit and th
 2. A `devices.csv` is generated in the `/config` folder
 3. Edit the `devices.csv` file however you like. 
 
-![Maintenance > CSV Export](/docs/img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png)
+![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)
 
-![Settings > CSV Backup](/docs/img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png)
+![Settings > CSV Backup](./img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png)
+
+### File encoding format
 
 > [!NOTE] 
 > Keep Linux line endings (suggested editors: Nano, Notepad++)
 
-![Nodepad++ line endings](/docs/img/DEVICES_BULK_EDITING/NOTEPAD++.png)
+![Nodepad++ line endings](./img/DEVICES_BULK_EDITING/NOTEPAD++.png)
 
 
 

docs/DEVICE_DISPLAY_SETTINGS.md

@@ -0,0 +1,20 @@
+# Device Display Settings
+
+This set of settings allows you to group Devices under different views. The Archived toggle allows you to exclude a Device from most listings and notifications. 
+
+
+![Display settings](./img/DEVICE_MANAGEMENT/DeviceDetails_DisplaySettings.png)
+
+
+## Status Colors
+
+![Sattus colors](./img/DEVICE_MANAGEMENT/device_management_status_colors.png)
+
+1. 🔌 Online (Green) = A device that is no longer marked as a "New Device".
+2. 🔌 New (Green) = A newly discovered device that is online and is still marked as a "New Device".
+3. ✖ New (Grey) = Same as No.2 but device is now offline.
+4. ✖ Offline (Grey) = A device that was not detected online in the last scan. 
+5. ⚠ Down (Red) = A device that has "Alert Down" marked and has been offline for the time set in the Setting `NTFPRCS_alert_down_time`. 
+
+
+See also [Notification guide](./NOTIFICATIONS.md).

docs/DEVICE_MANAGEMENT.md

@@ -1,107 +1,50 @@
 # NetAlertX - Device Management
-<!--- --------------------------------------------------------------------- --->
-To edit device information:
-  - Select "Devices" in the menu on the left of the screen
-  - Find the device you want to edit in the central table
-  - Go to the device page by clicking on the device name or status
-  - Press "Details" tab of the device
-  - Edit the device data
-  - Press the "Save" button
+
+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.
+
+> [!NOTE] 
+>
+> You can multi-edit devices by selecting them in the main Devices view, from the Mainetence section, or via the CSV Export functionality under Maintenance. More info can be found in the [Devices Bulk-editing docs](./DEVICES_BULK_EDITING.md).
+
+
+ ![Main Info](./img/DEVICE_MANAGEMENT/DeviceManagement_MainInfo.png)
+
+## Main Info
+
+  - **MAC**: MAC addres of the device. Not editable, unless creating a new dummy device.
+  - **Last IP**: IP addres of the device. Not editable, unless creating a new dummy device.
+  - **Name**: Friendly device name. Autodetected via various 🆎 Name discovery [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change.
+  - **Icon**: Partially autodetected. Select an existing or [add a custom icon](./ICONS.md). You can also auto-apply the same icon on all devices of the same type. 
+  - **Owner**: Device owner (The list is self-populated with existing owners and you can add custom values).
+  - **Type**: Select a device type from the dropdown list (`Smartphone`, `Tablet`,
+      `Laptop`, `TV`, `router`, etc.) or add a new device type. If you want the device to act as a **Network device** (and be able to be a network node in the Network view), select a type under Network Devices or add a new Network Device type in Settings. More information can be found in the [Network Setup docs](./NETWORK_TREE.md). 
+  - **Vendor**: The manufacturing vendor. Automatically updated by NetAlertX when empty or unknown, can be edited.
+  - **Group**: Select a group (`Always on`, `Personal`, `Friends`, etc.) or type
+      your own Group name.
+  - **Location**: Select the location, usually a room, where the device is located (`Kitchen`, `Attic`, `Living room`, etc.) or add a custom Location.  
+  - **Comments**: Add any comments for the device, such as a serial number, or maintenance information.
+
+> [!NOTE] 
+>
+> Please note the above usage of the fields are only suggestions. You can use most of these fields for other purposes, such as storing the network interface, company owning a device, or similar. 
+
+## Dummy devices
+
+You can create dummy devices from the Devices listing screen. 
+
+![Create Dummy Device](./img/DEVICE_MANAGEMENT/Devices_CreateDummyDevice.png)
+
+The **MAC** field and the **Last IP** field will then become editable.
+
+![Save Dummy Device](./img/DEVICE_MANAGEMENT/DeviceEdit_SaveDummyDevice.png)
 
 
 > [!NOTE] 
 >
-> [Bulk-edit devices](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md) by using the _CSV Export_ functionality in the _Maintenance_ section.
+> You can couple this with the `ICMP` plugin which can be used to monitor the status of these devices, if they are actual devices reachable with the `ping` command. If not, you can use a loopback IP address so they appear online, such as `0.0.0.0` or `127.0.0.1`.
+
+## Copying data from an existing device. 
+
+To speed up device population you can also copy data from an existing device. This can be done from the **Tools** tab on the Device details. 
 
 
-![Device Details][screen1]
-
-
-## Main Info
-  - **MAC**: MAC addres of the device. Not editable.
-  - **Name**: Friendly device name
-  - **Owner**: Device owner (The list is self-populated with existing owners)
-  - **Type**: Select a device type from the dropdown list (Smartphone, Table,
-      Laptop, TV, router, ....) or type a new device type
-  - **Vendor**: Automatically updated by NetAlertX when empty or unknown
-  - **Favorite**: Mark the device as favorite and then it will appears at the
-      begining of the device list
-  - **Group**: Select a grouper ('Always on', 'Personal', Friends') or type
-      your own Group name
-  - **Comments**: Type any comments for the device
-
-## Session Info
-  - **Status**: Show device status : On-line / Off-Line
-  - **First Session**: Date and time of the first connection
-  - **Last Offline**: Date and time of the last last time the device was offline
-  - **Last IP**: Last known IP used during the last connection
-  - **Static IP**: Check this box to identify devices that always use the
-      same IP
-
-## Events & Alerts config
-  - **Scan Cycle**: Select the scan cycle: 0, 1', 15'
-    - Some devices do not respond to all ARP packets, for this cases is better
-      to use a 15' cycle.
-    - **For Apple devices I recommend using 15' cycle**
-  - **Alert All Events**: Send a notification in each event (connection,
-      disconnection, IP Changed, ...)
-  - **Alert Down**: Send a notification when the device is down
-    - *(Userful with "always connected" devices: Camera, Alexa,...)*
-  - **Skip repeated notifications during**: Do not send more than one
-      notification to this device for X hours
-    - *(Useful to avoid notification saturation on devices that frequently
-      connects and disconnects)*
-
-# Privacy & Random MAC's
-<!--- --------------------------------------------------------------------- --->
-
-The latest versions of some operating systems (IOS and Android) incorporate a
-new & interesting functionality to improve privacy: **Random MACs**.
-
-This functionality allows you to **hide the true MAC** of the device and
-**assign a random MAC** when we connect to WIFI networks.
-
-This behavior is especially useful when connecting to WIFI's that we do not
-know, but it **is totally useless when connecting to our own WIFI's** or known
-networks.
-
-**I recommend disabling this operation when connecting our devices to our own
-WIFI's**, in this way, NetAlertX will be able to identify the device, and it
-will not identify it as a new device every so often (every time IOS or Android
-decides to change the MAC).
-
-### IOS
-![ios][ios]
-
-  - [Use private Wi-Fi addresses in iOS 14](https://support.apple.com/en-us/HT211227)
-
-### Android
-![Android][Android]
-
-  - [How to Disable MAC Randomization in Android 10](https://support.boingo.com/s/article/How-to-Disable-MAC-Randomization-in-Android-10-Android-Q)
-  - [How do I disable random Wi-Fi MAC address on Android 10](https://support.plume.com/hc/en-gb/articles/360052070714-How-do-I-disable-random-Wi-Fi-MAC-address-on-Android-10-)
-  
-### License
-  GPL 3.0
-  [Read more here](../LICENSE.txt)
-
-### Contact 
-
-  Always use the Issue tracker for the correct fork, for example: 
-  
-  [jokob-sk/NetAlertX](https://github.com/jokob-sk/NetAlertX/issues). Please also follow the guidelines on:
-
-  - ➕ [Pull Request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs) 
-  - 🙏 [Feature request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-feature-requests) 
-  - 🐛 [Issue guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-submitting-an-issue-or-bug)
-
-    
-  ***Suggestions and comments are welcome***
-
-
-<!--- --------------------------------------------------------------------- --->
-[main]:    ./img/1_devices.jpg           "Main screen"
-[screen1]: ./img/2_1_device_details.jpg  "Screen 1"
-[ios]:     https://9to5mac.com/wp-content/uploads/sites/6/2020/08/how-to-use-private-wifi-mac-address-iphone-ipad.png?resize=2048,1009 "ios"
-[Android]: ./img/android_random_mac.jpg  "Android"
-

docs/DEV_ENV_SETUP.md

@@ -1,14 +1,38 @@
-## Development environemnt set up
+# Development environment set up
 
 >[!NOTE]
 > Replace `/development` with the path where your code files will be stored. The default container name is `netalertx` so there might be a conflict with your running containers.
 
-## 1. Download the code:
+## Development Guidelines
+
+Before starting development, please scan the below development guidelines.
+
+### Priority Order (Highest to Lowest)
+
+1. 🔼 Fixing core bugs that lack workarounds.
+2. 🔵 Adding core functionality that unlocks other features (e.g., plugins).
+3. 🔵 Refactoring to enable faster development.
+4. 🔽 UI improvements (PRs welcome).
+
+### Design Philosophy
+
+Focus on core functionality and integrate with existing tools rather than reinventing the wheel.  
+Examples:
+
+- Using **Apprise** for notifications instead of implementing multiple separate gateways.
+- Implementing **regex-based validation** instead of one-off validation for each setting.
+
+> [!NOTE]
+> UI changes have lower priority, however, PRs are welcome, but **keep them small & focused**.
+
+## Development Environment Set Up
+
+### 1. Download the code:
 
 - `mkdir /development`
 - `cd /development && git clone https://github.com/jokob-sk/NetAlertX.git`
 
-## 2. Create a DEV .env_dev file
+### 2. Create a DEV .env_dev file
 
 `touch /development/.env_dev && sudo nano /development/.env_dev`
 
@@ -22,10 +46,12 @@ 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
+# Make sure your GRAPHQL_PORT setting has a port that is unique on your whole host network
+APP_CONF_OVERRIDE={"GRAPHQL_PORT":"22223"} 
 # ALWAYS_FRESH_INSTALL=true # uncommenting this will always delete the content of /config and /db dirs on boot to simulate a fresh install
 ```
 
-## 3. Create /db and /config dirs 
+### 3. Create /db and /config dirs 
 
 Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/volume/docker_appdata`) with 2 subfolders `db` and `config`. 
 
@@ -33,7 +59,7 @@ Create a folder `netalertx` in the `APP_DATA_LOCATION` (in this example in `/vol
 - `mkdir /volume/docker_appdata/netalertx/db`
 - `mkdir /volume/docker_appdata/netalertx/config`
 
-## 4. Run the container
+### 4. Run the container
 
 - `cd /development/NetAlertX &&  sudo docker-compose --env-file ../.env_dev `
 
@@ -42,7 +68,7 @@ You can then modify the python script without restarting/rebuilding the containe
 ![image](https://github.com/jokob-sk/NetAlertX/assets/96159884/3cbf2748-03c8-49e7-b801-f38c7755246b)
 
 
-## 💡 Tips
+## Tips
 
 A quick cheat sheet of useful commands. 
 
@@ -52,13 +78,44 @@ A command to stop, remove the container and the image (replace `netalertx` and `
 
 - `sudo docker container stop netalertx ; sudo docker container rm netalertx ; sudo docker image rm netalertx-netalertx`
 
-### Restart hanging python script
+### Restart the server backend
 
-SSH into the container and kill & restart the main script loop 
+Most code changes can be tested without rebuilding the container. When working on the python server backend, you only need to restart the server.
+
+1. You can usually restart the backend via _Maintenance > Logs > Restart_ server
+
+![image](./img/DEV_ENV_SETUP/Maintenance_Logs_Restart_server.png)
+
+2. If above doesn't work, SSH into the container and kill & restart the main script loop 
 
 - `sudo docker exec -it netalertx /bin/bash`
 - `pkill -f "python /app/server" && python /app/server & `
 
+3. If none of the above work, restart the docker caontainer. 
 
+- This is usually the last resort as sometimes the Docker engine becomes unresponsive and the whole engine needs to be restarted. 
 
+## Contributing & Pull Requests
 
+### Before submitting a PR, please ensure:
+
+✔ Changes are **backward-compatible** with existing installs.  
+✔ No unnecessary changes are made.  
+✔ New features are **reusable**, not narrowly scoped.  
+✔ Features are implemented via **plugins** if possible.  
+
+### Mandatory Test Cases
+
+- Fresh install (no DB/config).
+- Existing DB/config compatibility.
+- Notification testing:
+
+    - Email  
+    - Apprise (e.g., Telegram)  
+    - Webhook (e.g., Discord)  
+    - MQTT (e.g., Home Assistant)  
+
+- Updating Settings and their persistence.
+- Updating a Device
+- Plugin functionality.
+- Error log inspection.

docs/DOCKER_COMPOSE.md

@@ -0,0 +1,139 @@
+# `docker-compose.yaml` Examples
+
+> [!NOTE] 
+> The container needs to run in `network_mode:"host"`. This also means that not all functionality is supported on a Windows host as Docker for Windows doesn't support this networking option. 
+
+### Example 1
+
+```yaml
+services:
+  netalertx:
+    container_name: netalertx
+    # use the below line if you want to test the latest dev image
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: "ghcr.io/jokob-sk/netalertx:latest"      
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - local_path/config:/app/config
+      - local_path/db:/app/db      
+      # (optional) useful for debugging if you have issues setting up the container
+      - local_path/logs:/app/log
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # -  local_path/api:/app/api
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+To run the container execute: `sudo docker-compose up -d`
+
+### Example 2
+
+Example by [SeimuS](https://github.com/SeimusS).
+
+```yaml
+services:
+  netalertx:
+    container_name: NetAlertX
+    hostname: NetAlertX
+    privileged: true
+    # use the below line if you want to test the latest dev image
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: ghcr.io/jokob-sk/netalertx:latest
+    environment:
+      - TZ=Europe/Bratislava
+    restart: always
+    volumes:
+      - ./netalertx/db:/app/db
+      - ./netalertx/config:/app/config
+    network_mode: host
+```
+
+To run the container execute: `sudo docker-compose up -d`
+
+### Example 3
+
+`docker-compose.yml` 
+
+```yaml
+services:
+  netalertx:
+    container_name: netalertx
+    # use the below line if you want to test the latest dev image
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: "ghcr.io/jokob-sk/netalertx:latest"      
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - ${APP_DATA_LOCATION}/netalertx/config:/app/config
+      - ${APP_DATA_LOCATION}/netalertx/db/:/app/db/      
+      # (optional) useful for debugging if you have issues setting up the container
+      - ${LOGS_LOCATION}:/app/log
+      # (API: OPTION 1) use for performance
+      - type: tmpfs
+        target: /app/api
+      # (API: OPTION 2) use when debugging issues 
+      # -  local/path/api:/app/api
+    environment:
+      - TZ=${TZ}      
+      - PORT=${PORT}
+```
+
+`.env` file
+
+```yaml
+#GLOBAL PATH VARIABLES
+
+APP_DATA_LOCATION=/path/to/docker_appdata
+APP_CONFIG_LOCATION=/path/to/docker_config
+LOGS_LOCATION=/path/to/docker_logs
+
+#ENVIRONMENT VARIABLES
+
+TZ=Europe/Paris
+PORT=20211
+
+#DEVELOPMENT VARIABLES
+
+DEV_LOCATION=/path/to/local/source/code
+```
+
+To run the container execute: `sudo docker-compose --env-file /path/to/.env up`
+
+
+### Example 4: Docker swarm
+
+Notice how the host network is defined in a swarm setup:
+
+```yaml
+services:
+  netalertx:
+    # Use the below line if you want to test the latest dev image
+    # image: "jokobsk/netalertx-dev:latest"
+    image: "ghcr.io/jokob-sk/netalertx:latest"
+    volumes:
+      - /mnt/MYSERVER/netalertx/config:/config:rw
+      - /mnt/MYSERVER/netalertx/db:/netalertx/db:rw
+      - /mnt/MYSERVER/netalertx/logs:/netalertx/front/log:rw
+    environment:
+      - TZ=Europe/London
+      - PORT=20211
+    networks:
+      - outside
+    deploy:
+      mode: replicated
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+
+networks:
+  outside:
+    external:
+      name: "host"
+
+
+```

docs/DOCKER_SWARM.md

@@ -0,0 +1,79 @@
+# Docker Swarm Deployment Guide (IPvlan)
+
+This guide describes how to deploy **NetAlertX** in a **Docker Swarm** environment using an `ipvlan` network. This enables the container to receive a LAN IP address directly, which is ideal for network monitoring.
+
+---
+
+## ⚙️ Step 1: Create an IPvlan Config-Only Network on All Nodes
+
+> Run this command on **each node** in the Swarm.
+
+```bash
+docker network create -d ipvlan \
+  --subnet=192.168.1.0/24 \              # 🔧 Replace with your LAN subnet
+  --gateway=192.168.1.1 \                # 🔧 Replace with your LAN gateway
+  -o ipvlan_mode=l2 \
+  -o parent=eno1 \                       # 🔧 Replace with your network interface (e.g., eth0, eno1)
+  --config-only \
+  ipvlan-swarm-config
+```
+
+---
+
+## 🖥️ Step 2: Create the Swarm-Scoped IPvlan Network (One-Time Setup)
+
+> Run this on **one Swarm manager node only**.
+
+```bash
+docker network create -d ipvlan \
+  --scope swarm \
+  --config-from ipvlan-swarm-config \
+  swarm-ipvlan
+```
+
+---
+
+## 🧾 Step 3: Deploy NetAlertX with Docker Compose
+
+Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** assigned via the `swarm-ipvlan` network.
+
+```yaml
+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
+    deploy:
+      mode: replicated
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+      placement:
+        constraints:
+          - node.role == manager        # 🔄 Or use: node.labels.netalertx == true
+
+networks:
+  swarm-ipvlan:
+    external: true
+```
+
+---
+
+## ✅ Notes
+
+* The `ipvlan` setup allows **NetAlertX** to have a direct IP on your LAN.
+* Replace `eno1` with your interface, IP addresses, and volume paths to match your environment.
+* Make sure the assigned IP (`192.168.1.240` above) is not in use or managed by DHCP.
+* You may also use a node label constraint instead of `node.role == manager` for more control.
+
+

docs/FILE_PERMISSIONS.md

@@ -5,37 +5,19 @@
 >  ``` 
 >  docker run -d --rm --network=host \
 >  -e TZ=Europe/Berlin \
+>  -e PUID=200 -e PGID=200 \
 >  -e PORT=20211 \
->  jokobsk/netalertx:latest
+>  ghcr.io/jokob-sk/netalertx:latest
 > ```
-NetAlertX runs on an Nginx web server. On Alpine Linux, Nginx operates as the `nginx` user (user ID 101, group ID 82 - `www-data`). Consequently, files accessed or written by the NetAlertX application are owned by `nginx:www-data`.
+NetAlertX runs on an Nginx web server. On Alpine Linux, Nginx operates as the `nginx` user (if PUID and GID environment variables are not specified, nginx user UID will be set to 102, and its supplementary group `www-data` ID to 82). Consequently, files accessed or written by the NetAlertX application are owned by `nginx:www-data`.
 
-Upon starting, NetAlertX changes the ownership of files on the host system mapped to `/app/config` and `/app/db` in the container to `nginx:www-data`. This ensures that Nginx can access and write to these files. Since the user in the Docker container is mapped to a user on the host system by ID:GID, the files in `/app/config` and `/app/db` on the host system are owned by a user with the same ID and GID (ID 101 and GID 82). On different systems, this ID:GID may belong to different users (on Debian, the user with ID 82 is `uuidd`), or there may not be a user with ID 82 at all.
+Upon starting, NetAlertX changes nginx user UID and www-data GID to specified values (or defaults), and the ownership of files on the host system mapped to `/app/config` and `/app/db` in the container to `nginx:www-data`. This ensures that Nginx can access and write to these files. Since the user in the Docker container is mapped to a user on the host system by ID:GID, the files in `/app/config` and `/app/db` on the host system are owned by a user with the same ID and GID (defaults are ID 102 and GID 82). On different systems, this ID:GID may belong to different users, or there may not be a group with ID 82 at all.
 
-While this generally isn't problematic, it can cause issues for host system users needing to access these files (e.g., backup scripts). If users other than root need access to these files, it is recommended to add those users to the group with GID 82. If that group doesn't exist, it should be created.
+Option to set specific user UID and GID can be useful for host system users needing to access these files (e.g., backup scripts).
 
 ### Permissions Table for Individual Folders
 
 | Folder         | User   | User ID | Group     | Group ID | Permissions | Notes                                                               |
 |----------------|--------|---------|-----------|----------|-------------|---------------------------------------------------------------------|
-| `/app/config`  | nginx  | 101     | www-data  | 82       | rwxr-xr-x   | Ensure `nginx` can read/write; other users can read if in `www-data` |
-| `/app/db`      | nginx  | 101     | www-data  | 82       | rwxr-xr-x   | Same as above                                                       |
-
-### Steps to Add Users to Group
-
-1. **Check if group exists:**
-    ```sh
-    getent group www-data
-    ```
-
-2. **Create group if it does not exist:**
-    ```sh
-    sudo groupadd -g 82 www-data
-    ```
-
-3. **Add user to group:**
-    ```sh
-    sudo usermod -aG www-data <username>
-    ```
-
-Replace `<username>` with the actual username that requires access.
+| `/app/config`  | nginx  | PUID (default 102)     | www-data  | PGID (default 82)       | rwxr-xr-x   | Ensure `nginx` can read/write; other users can read if in `www-data` |
+| `/app/db`      | nginx  | PUID (default 102)     | www-data  | PGID (default 82)       | rwxr-xr-x   | Same as above                                                       |

docs/FIX_OFFLINE_DETECTION.md

@@ -0,0 +1,78 @@
+# Troubleshooting: Devices Show Offline When They Are Online
+
+In some network setups, certain devices may intermittently appear as **offline** in NetAlertX, even though they are connected and responsive. This issue is often more noticeable with devices that have **higher IP addresses** within the subnet.
+
+> [!NOTE]
+>
+> Network presence graph showing increased drop outs before enabling additional `ICMP` scans and continuous online presence after following this guide. This graph shows a sudden spike in drop outs probably caused by a device software update.
+> ![before after presence](./img/FIX_OFFLINE_DETECTION/presence_graph_before_after.png)
+
+## Symptoms
+
+* Devices sporadically show as offline in the presence timeline.
+* This behavior often affects devices with higher IPs (e.g., `192.168.1.240+`).
+* Presence data appears inconsistent or unreliable despite the device being online.
+
+## Cause
+
+This issue is typically related to scanning limitations:
+
+* **ARP scan timeouts** may prevent full subnet coverage.
+* **Sole reliance on ARP** can result in missed detections:
+
+  * Some devices (like iPhones) suppress or reject frequent ARP requests.
+  * ARP responses may be blocked or delayed due to power-saving features or OS behavior.
+
+* **Scanning frequency conflicts**, where devices ignore repeated scans within a short period.
+
+## Recommended Fixes
+
+To improve presence accuracy and reduce false offline states:
+
+### ✅ Increase ARP Scan Timeout
+
+Extend the ARP scanner timeout to ensure full subnet coverage:
+
+```env
+ARPSCAN_RUN_TIMEOUT=360
+```
+
+> Adjust based on your network size and device count.
+
+### ✅ Add ICMP (Ping) Scanning
+
+Enable the `ICMP` scan plugin to complement ARP detection. ICMP is often more reliable for detecting active hosts, especially when ARP fails. 
+
+### ✅ Use Multiple Detection Methods
+
+A combined approach greatly improves detection robustness:
+
+* `ARPSCAN` (default)
+* `ICMP` (ping)
+* `NMAPDEV` (nmap)
+
+This hybrid strategy increases reliability, especially for down detection and alerting. See [other plugins](./PLUGINS.md) that might be compatible with your setup. See benefits and drawbacks of individual scan methods in their respective docs. 
+
+## Results
+
+After increasing the ARP timeout and adding ICMP scanning (on select IP ranges), users typically report:
+
+* More consistent presence graphs
+* Fewer false offline events
+* Better coverage across all IP ranges
+
+## Summary
+
+| Setting               | Recommendation                                |
+| --------------------- | --------------------------------------------- |
+| `ARPSCAN_RUN_TIMEOUT` | Increase to ensure scans reach all IPs        |
+| `ICMP` Scan           | Enable to detect devices ARP might miss       |
+| Multi-method Scanning | Use a mix of ARP, ICMP, and NMAP-based methods |
+
+---
+
+**Tip:** Each environment is unique. Consider fine-tuning scan settings based on your network size, device behavior, and desired detection accuracy.
+
+Let us know in the [NetAlertX Discussions](https://github.com/jokob-sk/NetAlertX/discussions) if you have further feedback or edge cases.
+
+See also [Remote Networks](./REMOTE_NETWORKS.md) for more advanced setups. 

docs/FRONTEND_DEVELOPMENT.md

@@ -1,4 +1,4 @@
-# 🖼 Frontend development 
+# Frontend development 
 
 This page contains tips for frontend development when extending NetAlertX. Guiding principles are:
 
@@ -38,7 +38,7 @@ Some examples how to apply the above:
 
 Some useful frontend JavaScript functions:
 
-- `getDeviceDataByMac(macAddress, devicesColumn)` - method to retrieve any device data (database column) based on MAC address in the frontend 
+- `getDevDataByMac(macAddress, devicesColumn)` - method to retrieve any device data (database column) based on MAC address in the frontend 
 - `getString(string stringKey)` - method to retrieve translated strings in the frontend 
 - `getSetting(string stringKey)` - method to retrieve settings in the frontend 
 

docs/HELPER_SCRIPTS.md

@@ -0,0 +1,21 @@
+# NetAlertX 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.
+
+## Community Scripts
+
+You can find all scripts in this [scripts GitHub folder](https://github.com/jokob-sk/NetAlertX/tree/main/scripts).
+
+| Script Name | Description | Author | Version | Release Date |
+|------------|-------------|--------|---------|--------------|
+| **New Devices Checkmk Script** | Checks for new devices in NetAlertX and reports status to Checkmk. | N/A | 1.0 | 08-Jan-2025 |
+| **DB Cleanup Script** | Queries and removes old device-related entries from the database. | [laxduke](https://github.com/laxduke) | 1.0 | 23-Dec-2024 |
+| **OPNsense DHCP Lease Converter** | Retrieves DHCP lease data from OPNsense and converts it to `dnsmasq` format. | [im-redactd](https://github.com/im-redactd) | 1.0 | 24-Feb-2025 |
+
+## Important Notes
+
+> [!NOTE]  
+> These scripts are community-supplied and not actively maintained. Use at your own discretion.  
+
+For detailed usage instructions, refer to each script's documentation in each [scripts GitHub folder](https://github.com/jokob-sk/NetAlertX/tree/main/scripts).
+

docs/HOME_ASSISTANT.md

@@ -1,11 +1,15 @@
-# Overview
+# Home Assistant integration overview
 
 NetAlertX comes with MQTT support, allowing you to show all detected devices as devices in Home Assistant. It also supplies a collection of stats, such as number of online devices.
 
+> [!TIP]
+> You can install NetAlertX also as a Home Assistant addon [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/) repository. This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
+
 ## ⚠ Note 
 
 - Please note that discovery takes about ~10s per device.
 - Deleting of devices is not handled automatically. Please use [MQTT Explorer](https://mqtt-explorer.com/) to delete devices in the broker (Home Assistant), if needed. 
+- For optimization reasons, the devices are not always fully synchronized. You can delete Plugin objects as described in the [MQTT plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_mqtt#forcing-an-update) docs to force a full synchronization.
 
 
 ## 🧭 Guide
@@ -17,15 +21,18 @@ NetAlertX comes with MQTT support, allowing you to show all detected devices as
 2. Configure a user name and password on your broker.
 
 3. Note down the following details that you will need to configure NetAlertX:
-   - MQTT host url (usually your Home Assistant IP)
-   - MQTT broker port
-   - User
-   - Password
+
+      - MQTT host url (usually your Home Assistant IP)
+      - MQTT broker port
+      - User
+      - Password
 
 4. Open the _NetAlertX_ > _Settings_ > _MQTT_ settings group
-   - Enable MQTT
-   - Fill in the details from above
-   - Fill in remaining settings as per description
+
+      - Enable MQTT
+      - Fill in the details from above
+      - Fill in remaining settings as per description
+      - set MQTT_RUN to schedule or on_notification depending on requirements
 
 ![Configuration Example][configuration] 
 
@@ -36,9 +43,50 @@ NetAlertX comes with MQTT support, allowing you to show all detected devices as
   | ![Screen 3][list] | ![Screen 4][overview] | 
   
 
-  [configuration]:   /docs/img/HOME_ASISSTANT/HomeAssistant-Configuration.png           "configuration"
-  [sensors]:         /docs/img/HOME_ASISSTANT/HomeAssistant-Device-as-Sensors.png       "sensors"
-  [history]:         /docs/img/HOME_ASISSTANT/HomeAssistant-Device-Presence-History.png "history"
-  [list]:            /docs/img/HOME_ASISSTANT/HomeAssistant-Devices-List.png            "list"  
-  [overview]:        /docs/img/HOME_ASISSTANT/HomeAssistant-Overview-Card.png           "overview"
+  [configuration]:   ./img/HOME_ASISSTANT/HomeAssistant-Configuration.png           "configuration"
+  [sensors]:         ./img/HOME_ASISSTANT/HomeAssistant-Device-as-Sensors.png       "sensors"
+  [history]:         ./img/HOME_ASISSTANT/HomeAssistant-Device-Presence-History.png "history"
+  [list]:            ./img/HOME_ASISSTANT/HomeAssistant-Devices-List.png            "list"  
+  [overview]:        ./img/HOME_ASISSTANT/HomeAssistant-Overview-Card.png           "overview"
 
+## Troubleshooting
+
+If you can't see all devices detected, run `sudo arp-scan  --interface=eth0 192.168.1.0/24` (change these based on your setup, read [Subnets](./SUBNETS.md) docs for details). This command has to be executed the NetAlertX container, not in the Home Assistant container.
+
+You can access the NetAlertX container via Portainer on your host or via ssh. The container name will be something like `addon_db21ed7f_netalertx` (you can copy the `db21ed7f_netalertx` part from the browser when accessing the UI of NetAlertX). 
+
+## Accessing the NetAlertX container via SSH
+
+1. Log into your Home Assistant host via SSH
+
+```bash
+local@local:~ $ ssh pi@192.168.1.9
+```
+2. Find the NetAlertX container name, in this case `addon_db21ed7f_netalertx`
+
+```bash
+pi@raspberrypi:~ $ sudo docker container ls | grep netalertx
+06c540d97f67   ghcr.io/alexbelgium/netalertx-armv7:25.3.1                   "/init"               6 days ago      Up 6 days (healthy)    addon_db21ed7f_netalertx
+```
+
+3. SSH into the NetAlertX cointainer
+
+```bash
+pi@raspberrypi:~ $ sudo docker exec -it addon_db21ed7f_netalertx  /bin/sh
+/ #
+```
+
+4. Execute a test `asrp-scan` scan
+
+```bash
+/ # sudo arp-scan --ignoredups --retry=6 192.168.1.0/24 --interface=eth0
+Interface: eth0, type: EN10MB, MAC: dc:a6:32:73:8a:b1, IPv4: 192.168.1.9
+Starting arp-scan 1.10.0 with 256 hosts (https://github.com/royhills/arp-scan)
+192.168.1.1     74:ac:b9:54:09:fb       Ubiquiti Networks Inc.
+192.168.1.21    74:ac:b9:ad:c3:30       Ubiquiti Networks Inc.
+192.168.1.58    1c:69:7a:a2:34:7b       EliteGroup Computer Systems Co., LTD
+192.168.1.57    f4:92:bf:a3:f3:56       Ubiquiti Networks Inc.
+...
+```
+
+If your result doesn't contain results similar to the above, double check your subnet, interface and if you are dealing with an inaccessible network segment, read the [Remote networks documentation](./REMOTE_NETWORKS.md).

docs/HW_INSTALL.md

@@ -5,6 +5,9 @@ To download and install NetAlertX on the hardware/server directly use the `curl`
 > [!NOTE]
 > This is an Experimental feature 🧪 and it relies on community support.
 >
+> 🙏 Looking for maintainers for this installation method 🙂 Curent community volunteers: 
+>   - [slammingprogramming](https://github.com/slammingprogramming)
+>
 > There is no guarantee that the install script or any other script will gracefully handle other installed software.
 > Data loss is a possibility, **it is recommended to install NetAlertX using the supplied Docker image**.
 
@@ -34,6 +37,9 @@ Some facts about what and where something will be changed/installed by the HW in
 
 ## 📥 Installation via CURL
 
+> [!TIP]  
+> If the below fails try grabbing and installing one of the [previous releases](https://github.com/jokob-sk/NetAlertX/releases) and run the installation from the zip package.
+
 ```bash
 curl -o install.debian.sh https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/install.debian.sh && sudo chmod +x install.debian.sh && sudo ./install.debian.sh
 ```

docs/ICONS.md

@@ -1,8 +1,8 @@
 ## Icons overview
 
-Icons are used to visually distinguish devices in the app in most of the device listing tables and the [network tree](/docs/NETWORK_TREE.md). 
+Icons are used to visually distinguish devices in the app in most of the device listing tables and the [network tree](./NETWORK_TREE.md). 
 
-![Raspberry Pi with a brand icon](/docs/img/ICONS/devices-icons.png)
+![Raspberry Pi with a brand icon](./img/ICONS/devices-icons.png)
 
 ### Icons Support
 
@@ -19,33 +19,33 @@ You can assign icons individually on each device in the Details tab.
 
 Copying the SVG (for example from [iconify.design](https://icon-sets.iconify.design/)): 
 
-![iconify svg](/docs/img/ICONS/iconify_design_copy_svg.png)
+![iconify svg](./img/ICONS/iconify_design_copy_svg.png)
 
 Copying the HTML code from [Font Awesome](https://fontawesome.com/search?o=r&m=free).
 
-![Font awesome](/docs/img/ICONS/font_awesome_copy_html.png)
+![Font awesome](./img/ICONS/font_awesome_copy_html.png)
 
 2. Navigate to the device you want to use the icon on and click the "+" icon:
 
-![preview](/docs/img/ICONS/device_add_icon.png)
+![preview](./img/ICONS/device_add_icon.png)
 
 3. Paste in the copied HTML or SVG code and click "OK":
 
-![Paste SVG](/docs/img/ICONS/paste-svg.png)
+![Paste SVG](./img/ICONS/paste-svg.png)
 
 6. "Save" the device
 
 > [!NOTE] 
 > If you want to mass-apply an icon to all devices of the same device type (Field: Type), you can click the mass-copy button (next to the "+" button). A confirmation prompt is displayed. If you proceed, icons of all devices set to the same device type as the current device, will be overwritten with the current device's icon.
 
-- The blue dropdown contains all icons already used in the app for device icons. You need to navigate away or refresh the page once you add a new icon. 
+- The dropdown contains all icons already used in the app for device icons. You might need to navigate away or refresh the page once you add a new icon. 
 
-## 🌟 Pro Font Awesome icons
+## Font Awesome Pro icons
 
 If you own the premium package of Font Awesome icons you can mount it in your Docker container the following way:
 
 ```yaml
-/font-awesome:/app/front/lib/AdminLTE/bower_components/font-awesome:ro
+/font-awesome:/app/front/lib/font-awesome:ro
 ```
 
 You can use the full range of Font Awesome icons afterwards. 

docs/INITIAL_SETUP.md

@@ -0,0 +1,109 @@
+# ⚡ Quick Start Guide
+
+Get **NetAlertX** up and running in a few simple steps.
+
+---
+
+### 1. Configure Scanner Plugin(s)
+
+> [!TIP]
+> Enable additional plugins under **Settings → `LOADED_PLUGINS`**.
+> Make sure to **save** your changes and **reload the page** to activate them.
+> ![Loaded plugins settings](./img/PLUGINS/enable_plugin.gif)
+
+**Initial configuration**: `ARPSCAN`, `INTRNT`
+
+> [!NOTE]
+> `ARPSCAN` and `INTRNT` scan the current network. You can complement them with other `🔍 dev scanner` plugins like `NMAPDEV`, or import devices using `📥 importer` plugins.
+> See the [Subnet & VLAN Setup Guide](./SUBNETS.md) and [Remote Networks](./REMOTE_NETWORKS.md) for advanced configurations.
+
+---
+
+### 2. Choose a Publisher Plugin
+
+**Initial configuration**: `SMTP`
+
+> [!NOTE]
+> Configure your SMTP settings or enable additional `▶️ publisher` plugins to send alerts.
+> For more flexibility, try [📚 `_publisher_apprise`](/front/plugins/_publisher_apprise/), which supports over 80 notification services.
+
+---
+
+### 3. Set Up a Network Topology Diagram
+
+![Network tree](./img/NETWORK_TREE/Network_tree_details.png)
+
+**Initial configuration**: The app auto-selects a root node (MAC `internet`) and attempts to identify other network devices by vendor or name.
+
+> [!NOTE]
+> Visualize and manage your network using the [Network Guide](./NETWORK_TREE.md).
+> Some plugins (e.g., `UNFIMP`) build the topology automatically, or you can use [Custom Workflows](./WORKFLOWS.md) to generate it based on your own rules.
+
+---
+
+### 4. Configure Notifications
+
+![Notification settings](./img/NOTIFICATIONS/Global-notification-settings.png)
+
+**Initial configuration**: Notifies on `new_devices`, `down_devices`, and `events` as defined in `NTFPRCS_INCLUDED_SECTIONS`.
+
+> [!NOTE]
+> Notification settings support global, plugin-specific, and per-device rules.
+> For fine-tuning, refer to the [Notification Guide](./NOTIFICATIONS.md).
+
+---
+
+### 5. Set Up Workflows
+
+![Workflows](./img/WORKFLOWS/workflows.png)
+
+**Initial configuration**: N/A
+
+> [!NOTE]
+> Automate responses to device status changes, group management, topology updates, and more.
+> See the [Workflows Guide](./WORKFLOWS.md) to simplify your network operations.
+
+---
+
+### 6. Backup Your Configuration
+
+![Backups](./img/BACKUPS/Maintenance_Backup_Restore.png)
+
+**Initial configuration**: The `CSVBCKP` plugin creates a daily backup to `/config/devices.csv`.
+
+> [!NOTE]
+> For a complete backup strategy, follow the [Backup Guide](./BACKUPS.md).
+
+---
+
+### 7. (Optional) Create Custom Plugins
+
+[![Custom Plugin Video](./img/YouTube_thumbnail.png)](https://youtu.be/cdbxlwiWhv8)
+
+**Initial configuration**: N/A
+
+> [!NOTE]
+> Build your own scanner, importer, or publisher plugin.
+> See the [Plugin Development Guide](./PLUGINS_DEV.md) and included video tutorials.
+
+---
+
+## 📁 Recommended Guides
+
+* 📘 [PiHole Setup Guide](./PIHOLE_GUIDE.md)
+* 📘 [CSV Import Method](./DEVICES_BULK_EDITING.md)
+* 📘 [Community Guides (Chinese, Korean, German, French)](./COMMUNITY_GUIDES.md)
+
+---
+
+## 🛠️ Troubleshooting & Help
+
+Before opening a new issue:
+
+* 📘 [Common Issues](./COMMON_ISSUES.md)
+* 🧰 [Debugging Tips](./DEBUG_TIPS.md)
+* ✅ [Browse resolved GitHub issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
+
+---
+
+Let me know if you want a condensed README version, separate pages for each section, or UI copy based on this!

docs/INSTALLATION.md

@@ -0,0 +1,25 @@
+# Installation
+
+## Installation options
+
+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] 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) 
+
+
+## Help
+
+If facing issues, please spend a few minutes seraching. 
+
+- Check [common issues](./COMMON_ISSUES.md)
+- Have a look at [Community guides](./COMMUNITY_GUIDES.md) 
+- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue) 
+- Check [Discord](https://discord.gg/NczTUTWyRr)
+
+> [!NOTE]
+> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process. 
+>
+

docs/LOGGING.md

@@ -0,0 +1,26 @@
+# Logging
+
+NetAlertX comes with several logs that help to identify application issues. 
+
+For plugin-specific log debugging, please read the [Debug Plugins](./DEBUG_PLUGINS.md) guide.
+
+When debugging any issue, increase the `LOG_LEVEL` Setting as per the [Debug tips](./DEBUG_TIPS.md) documentation.
+
+
+## Main logs
+
+You can find most of the logs exposed in the UI under _Maintenance -> Logs_. 
+
+If the UI is inaccessible, you can access them under `/app/log`.
+
+![Logs](./img/LOGGING/maintenance_logs.png)
+
+In the _Maintennace -> Logs_ you can **Purge logs**, download the full log file or Filter the lines with some substring to narrow down your search. 
+
+## Plugin logging
+
+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/`). These files are processed at the end of the scan and deleted on successful processing.
+
+The data is in most of the cases then displayed in the application under _Integrations -> Plugins_ (or _Device -> Plugins_ if the plugin is supplying device-specific data). 
+
+![Plugin objects](./img/LOGGING/logging_integrations_plugins.png)

docs/MIGRATION.md

@@ -1,12 +1,12 @@
 # Migration form PiAlert to NetAlertX
 
 > [!WARNING] 
-> Follow this guide only after you you downloaded and started NetAlert X at least once after previously using the PiAlert image.
+> Follow this guide only after you you downloaded and started a version of NetAlertX prior to v25.6.7 (e.g. `docker pull ghcr.io/jokob-sk/netalertx:25.5.24`) at least once after previously using the PiAlert image. Later versions don't support migration and devices and settings will have to migrated manually, e.g. via [CSV import](./DEVICES_BULK_EDITING.md).
 
 ## STEPS: 
 
 > [!TIP] 
-> In short: The application will auto-migrate the database, config, and all device information. A ticker message on top will be displayed until you update your docker mount points. It's always good to have a [backup strategy](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md) in place.
+> In short: The application will auto-migrate the database, config, and all device information. A ticker message on top will be displayed until you update your docker mount points. It's always good to have a [backup strategy](./BACKUPS.md) in place.
 
 1. Backup your current config and database (optional `devices.csv` to have a backup) (See bellow tip if facing issues)
 2. Stop the container 
@@ -38,24 +38,23 @@ The application installation folder in the docker container has changed from `/h
 
 
 > [!NOTE] 
-> The application uses symlinks linking the old db and config locations to the new ones, so data loss should not occur. [Backup strategies](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md) are still recommended to backup your setup.
+> The application uses symlinks linking the old db and config locations to the new ones, so data loss should not occur. [Backup strategies](./BACKUPS.md) are still recommended to backup your setup.
 
 
 # Examples
 
-Exmaples of docker files with the new mount points.
+Examples of docker files with the new mount points.
 
 ## Example 1: Mapping folders
 
 ### Old docker-compose.yml
 
 ```yaml
-version: "3"
 services:
   pialert:
     container_name: pialert
     # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
     image: "jokobsk/pialert:latest"      
     network_mode: "host"        
     restart: unless-stopped
@@ -72,20 +71,19 @@ services:
 ### New docker-compose.yml
 
 ```yaml
-version: "3"
 services:
   netalertx:                                  # ⚠  This has changed (🟡optional) 
     container_name: netalertx                 # ⚠  This has changed (🟡optional) 
     # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: "jokobsk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: "ghcr.io/jokob-sk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
     network_mode: "host"        
     restart: unless-stopped
     volumes:
       - local/path/config:/app/config         # ⚠  This has changed (🔺required) 
       - local/path/db:/app/db                 # ⚠  This has changed (🔺required) 
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/front/log        # ⚠  This has changed (🟡optional) 
+      - local/path/logs:/app/log        # ⚠  This has changed (🟡optional) 
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211
@@ -100,12 +98,11 @@ services:
 ### Old docker-compose.yml
 
 ```yaml
-version: "3"
 services:
   pialert:
     container_name: pialert
     # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
     image: "jokobsk/pialert:latest"      
     network_mode: "host"        
     restart: unless-stopped
@@ -122,20 +119,19 @@ services:
 ### New docker-compose.yml
 
 ```yaml
-version: "3"
 services:
   netalertx:                                  # ⚠  This has changed (🟡optional) 
     container_name: netalertx                 # ⚠  This has changed (🟡optional) 
     # use the below line if you want to test the latest dev image
-    # image: "jokobsk/netalertx-dev:latest" 
-    image: "jokobsk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: "ghcr.io/jokob-sk/netalertx:latest"         # ⚠  This has changed (🟡optional/🔺required in future) 
     network_mode: "host"        
     restart: unless-stopped
     volumes:
       - local/path/config/app.conf:/app/config/app.conf # ⚠  This has changed (🔺required) 
       - local/path/db/app.db:/app/db/app.db             # ⚠  This has changed (🔺required) 
       # (optional) useful for debugging if you have issues setting up the container
-      - local/path/logs:/app/front/log                  # ⚠  This has changed (🟡optional) 
+      - local/path/logs:/app/log                  # ⚠  This has changed (🟡optional) 
     environment:
       - TZ=Europe/Berlin      
       - PORT=20211

docs/NAME_RESOLUTION.md

@@ -0,0 +1,54 @@
+# Device Name Resolution
+
+Name resolution in NetAlertX relies on multiple plugins to resolve device names from IP addresses. If you are seeing `(name not found)` as device names, follow these steps to diagnose and fix the issue.
+
+> [!TIP]  
+> Before proceeding, make sure [Reverse DNS](./REVERSE_DNS.md) is enabled on your network.  
+> You can control how names are handled and cleaned using the `NEWDEV_NAME_CLEANUP_REGEX` setting.  
+> To auto-update Fully Qualified Domain Names (FQDN), enable the `REFRESH_FQDN` setting.
+
+
+## Required Plugins
+
+For best results, ensure the following name resolution plugins are enabled:
+
+- **AVAHISCAN** – Uses mDNS/Avahi to resolve local network names.
+- **NBTSCAN** – Queries NetBIOS to find device names.
+- **NSLOOKUP** – Performs standard DNS lookups.
+- **DIGSCAN** – Performs Name Resolution with the Dig utility (DNS).
+
+You can check which plugins are active in your _Settings_ section and enable any that are missing.
+
+There are other plugins that can supply device names as well, but they rely on bespoke hardware and services. See [Plugins overview](./PLUGINS.md) for details and look for plugins with name discovery (🆎) features.
+
+## Checking Logs
+
+If names are not resolving, check the logs for errors or timeouts.
+
+See how to explore logs in the [Logging guide](./LOGGING.md).
+
+Logs will show which plugins attempted resolution and any failures encountered.
+
+## Adjusting Timeout Settings
+
+If resolution is slow or failing due to timeouts, increase the timeout settings in your configuration, for example.
+
+```ini
+NSLOOKUP_RUN_TIMEOUT = 30
+```
+
+Raising the timeout may help if your network has high latency or slow DNS responses.
+
+## Checking Plugin Objects
+
+Each plugin stores results in its respective object. You can inspect these objects to see if they contain valid name resolution data.
+
+See [Logging guide](./LOGGING.md) and [Debug plugins](./DEBUG_PLUGINS.md) guides for details.
+
+If the object contains no results, the issue may be with DNS settings or network access.
+
+## Improving name resolution
+
+For more details how to improve name resolution refer to the 
+[Reverse DNS Documentation](./REVERSE_DNS.md).
+

docs/NETWORK_TREE.md

@@ -2,7 +2,7 @@
 
 Make sure you have a root device with the MAC `Internet` (No other MAC addresses are currently supported as the root node) set to a network device type (e.g.: **Type**:`Router`).
 
-> 💡 Tip: You can add dummy devices via the [Undiscoverables plugin](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/undiscoverables/README.md)
+> 💡 Tip: You can add dummy devices via the [Create dummy device](./DEVICE_MANAGEMENT.md#dummy-devices) button in the Devices listing page.
 
 > 💡 Tip: Export your configuration of the Network and Devices once in a while via the Export CSV feature under **Maintenance** -> **Backup/Restore** -> **CSV Export**.   
 
@@ -17,7 +17,7 @@ Make sure you have a root device with the MAC `Internet` (No other MAC addresses
 
 > [!NOTE] 
 >
-> [Bulk-edit devices](/docs/DEVICES_BULK_EDITING.md) by using the _CSV Export_ functionality in the _Maintenance_ section. You can use this to fix `Internet` node assignment issues. 
+> [Bulk-edit devices](./DEVICES_BULK_EDITING.md) by using the _CSV Export_ functionality in the _Maintenance_ section. You can use this to fix `Internet` node assignment issues. 
 
 ## 🔍Detailed example:
 
@@ -27,7 +27,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our
 
 - Go to the `Devices` (1) page:
 
-![Device details](/docs/img/NETWORK_TREE/Device_Details_Network_Type.png)
+![Device details](./img/NETWORK_TREE/Device_Details_Network_Type.png)
 
 - In the (2) `Details` tab navigate to the the `Type` (3) dropdown and select the type `Switch` (4).
 
@@ -42,7 +42,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our
 
 - Navigate to your `Network` (1) page:
 
-![Network page](/docs/img/NETWORK_TREE/Network_Page.png)
+![Network page](./img/NETWORK_TREE/Network_Page.png)
 
 - Notice the newly added `raspberrypi` (2) tab which now represents a network node, also showing up in the tree (3).
 - As we asssigned the `raspberrypi` in the previous (1) Device details page section to the `Internet` parent network node in step (6), the link is also showing up in the tree diagram (4)
@@ -52,7 +52,7 @@ In this example you will setup a device named `rapberrypi` as a `Switch` in our
 
 - After clicking the `Assign` button in the previous section, the `(AppleTV)` (1) device is now connected to our `raspberrypi` (2).
 
-![Network page with 2 levels](/docs/img/NETWORK_TREE/Network_Page_2_Levels.png)
+![Network page with 2 levels](./img/NETWORK_TREE/Network_Page_2_Levels.png)
 
 - You can see the `raspberrypi` represents the Network node type `Switch` (3)
 - The `(AppleTV)` to `raspberrypi` connection is also displayed in the table of `Connected devices` (4).

docs/NOTIFICATIONS.md

@@ -9,23 +9,24 @@ There are 4 ways how to influence notifications:
 
 > [!NOTE]
 > It's recommended to use the same schedule interval for all plugins responsible for scanning devices, otherwise false positives might be reported if different devices are discovered by different plugins. Check the **Settings** > **Enabled settings** section for a warning:
-> ![Schedules out-of-sync](/docs/img/NOTIFICATIONS/Schedules_out-of-sync.png)
-
+> ![Schedules out-of-sync](./img/NOTIFICATIONS/Schedules_out-of-sync.png)
 
 ## Device settings 💻
 
-![Device notification settings](/docs/img/NOTIFICATIONS/Device-notification-settings.png)
+![Device notification settings](./img/NOTIFICATIONS/Device-notification-settings.png)
 
 There are 4 settings on the device for influencing notifications. You can:
 
-1. Completely disable the scanning of the device
-2. **Alert all events**, connections, disconnections, IP changes (noisy, usually not recommended)
-3. **Alert down** - alerts when a device goes down. This setting overrides disabled Alert All Events, so you will get a notification of a device going down even if you don't have Alert All Events ticked.
-4. **Skip repeated notifications**, if for example you know there is a temporary issue and want to pause the same notification for this device for a given time.
+1. **Alert Events** - Enables alerts of connections, disconnections, IP changes (down and down reconnected notifications are still sent even if this is disabled).
+2. **Alert Down** - Alerts when a device goes down. This setting overrides a disabled **Alert Events** setting, so you will get a notification of a device going down even if you don't have **Alert Events** ticked. Disabling this will disable down and down reconnected notifications on the device.
+3. **Skip repeated notifications**, if for example you know there is a temporary issue and want to pause the same notification for this device for a given time.
+
+> [!NOTE]
+> Please read through the [NTFPRCS plugin](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/notification_processing/README.md) documentation to understand how device and global settings influence the notification processing. 
 
 ## Plugin settings 🔌
 
-![Plugin notification settings](/docs/img/NOTIFICATIONS/Plugin-notification-settings.png)
+![Plugin notification settings](./img/NOTIFICATIONS/Plugin-notification-settings.png)
 
 On almost all plugins there are 2 core settings, `<plugin>_WATCH` and `<plugin>_REPORT_ON`. 
 
@@ -36,18 +37,18 @@ Click the **Read more in the docs.** Link at the top of each plugin to get more
 
 ## Global settings ⚙
 
-![Global notification settings](/docs/img/NOTIFICATIONS/Global-notification-settings.png)
+![Global notification settings](./img/NOTIFICATIONS/Global-notification-settings.png)
 
 In Notification Processing settings, you can specify blanket rules. These allow you to specify exceptions to the Plugin and Device settings and will override those.
 
-1. Notify on (`NTFPRCS_INCLUDED_SECTIONS`) allows you to specify which events trigger notifications. Usual setups will have `new_devices`, `down_devices`, and possibly `events` set. Setting `plugin` might be too noisy for most setups. More info in the [NTFPRCS plugin](/front/plugins/notification_processing/README.md)
+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 🔕
 
-![Ignoring new devices](/docs/img/NOTIFICATIONS/NEWDEV_ignores.png)
+![Ignoring new devices](./img/NOTIFICATIONS/NEWDEV_ignores.png)
 
 You can completely ignore detected devices globally. This could be because your instance detects docker containers, you want to ignore devices from a specific manufacturer via MAC rules or you want to ignore devices on a specific IP range. 
 

docs/PERFORMANCE.md

@@ -0,0 +1,96 @@
+# 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.
+
+## 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.
+- **Too many background processes** – Disable unnecessary scanners.
+- **Long scan durations** – Limit the number of scanned devices.
+- **Excessive disk operations** – Optimize scanning and logging settings.
+- **Failed maintenance plugins** – Ensure maintenance tasks are running properly.
+
+The application performs regular maintenance and database cleanup. If these tasks fail, performance may degrade.
+
+### 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.
+
+![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.
+> - These numbers vary based on network activity and settings.
+
+---
+
+## Maintenance Plugins
+
+Two plugins help maintain the application’s performance:
+
+### **1. Database Cleanup (DBCLNP)**
+- Responsible for database maintenance.
+- Check settings in the [DB Cleanup Plugin Docs](/front/plugins/db_cleanup/README.md).
+- Ensure it’s not failing by checking logs.
+- Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if needed.
+
+### **2. Maintenance (MAINT)**
+- Handles log cleanup and other maintenance tasks.
+- Check settings in the [Maintenance Plugin Docs](/front/plugins/maintenance/README.md).
+- Ensure it’s running correctly by checking logs.
+- Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed.
+
+---
+
+## Scan Frequency and Coverage
+
+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. 
+
+For example, the **ICMP plugin** allows you to specify a regular expression to scan only IPs that match a specific pattern.
+
+---
+
+## 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.
+
+Using `tmpfs` reduces disk writes and improves performance. However, it should be **disabled** if persistent logs or API data storage are required.
+
+Below is an optimized `docker-compose.yml` snippet:
+
+
+```yaml
+version: "3"
+services:
+  netalertx:
+    container_name: netalertx
+    # Uncomment the line below to test the latest dev image
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest"
+    image: "ghcr.io/jokob-sk/netalertx:latest"      
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - 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
+
+```

docs/PIHOLE_GUIDE.md

@@ -0,0 +1,45 @@
+# Integration with PiHole
+
+NetAlertX comes with 2 plugins suitable for integarting with your existing PiHole instace. One plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine both approaches and also supplement it with other [plugins](/docs/PLUGINS.md). 
+
+## Approach 1: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file
+
+![DHCPLSS sample settings](./img/PIHOLE_GUIDE/DHCPLSS_pihole_settings.png)
+
+### Settings
+
+| Setting | Description | Recommended value |
+| :------------- | :------------- | :-------------|
+| `DHCPLSS_RUN` | When the plugin should run.  | `schedule` |
+| `DHCPLSS_RUN_SCHD` | If you run multiple device scanner plugins, align the schedules of all plugins to the same value.  | `*/5 * * * *` |
+| `DHCPLSS_paths_to_check` | You need to map the value in this setting in the `docker-compose.yml` file. The in-container path must contain `pihole` so it's parsed correctly. | `['/etc/pihole/dhcp.leases']` |
+
+Check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases#overview) for details
+
+### docker-compose changes
+
+| Path | Description |
+| :------------- | :------------- |
+| `:/etc/pihole/dhcp.leases` |  PiHole's `dhcp.leases` file. Required if you want to use PiHole `dhcp.leases` file. This has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (the path in the container must contain `pihole`) |
+
+
+## Approach 2: `PIHOLE` Plugin - Import devices directly from the PiHole database
+
+![DHCPLSS sample settings](./img/PIHOLE_GUIDE/PIHOLE_settings.png)
+
+| Setting | Description | Recommended value |
+| :------------- | :------------- | :-------------| 
+| `PIHOLE_RUN` | When the plugin should run.  | `schedule` |
+| `PIHOLE_RUN_SCHD` | If you run multiple device scanner plugins, align the schedules of all plugins to the same value.  | `*/5 * * * *` |
+| `PIHOLE_DB_PATH` | You need to map the value in this setting in the `docker-compose.yml` file. | `/etc/pihole/pihole-FTL.db` |
+
+Check the [PiHole plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_scan) for details
+
+### docker-compose changes
+
+| Path | Description |
+| :------------- | :------------- |
+| `:/etc/pihole/pihole-FTL.db` |  PiHole's `pihole-FTL.db` database file.  |
+
+
+Check out other [plugins](/docs/PLUGINS.md) that can help you discover more about your network or check how to scan [Remote networks](./REMOTE_NETWORKS.md).

docs/PLUGINS.md

@@ -0,0 +1,117 @@
+# 🔌 Plugins
+
+NetAlertX supports additional plugins to extend its functionality, each with its own settings and options. Plugins can be loaded via the General -> `LOADED_PLUGINS` setting. For custom plugin development, refer to the [Plugin development guide](./PLUGINS_DEV.md).   
+
+>[!NOTE]
+> Please check this [Plugins debugging guide](./DEBUG_PLUGINS.md) and the corresponding Plugin documentation in the below table if you are facing issues.  
+
+## ⚡ Quick start
+
+> [!TIP]
+> You can load additional Plugins via the General -> `LOADED_PLUGINS` setting. You need to save the settings for the new plugins to load (cache/page reload may be necessary). 
+> ![Loaded plugins settings](./img/PLUGINS/enable_plugin.gif)
+
+1. Pick your `🔍 dev scanner` plugin (e.g. `ARPSCAN` or `NMAPDEV`), or import devices into the application with an `📥 importer` plugin. (See **Enabling plugins** below)
+2. Pick a `▶️ publisher` plugin, if you want to send notifications. If you don't see a publisher you'd like to use, look at the  [📚_publisher_apprise](/front/plugins/_publisher_apprise/) plugin which is a proxy for over 80 notification services. 
+3. Setup your [Network topology diagram](./NETWORK_TREE.md)
+4. Fine-tune [Notifications](./NOTIFICATIONS.md)
+5. Setup [Workflows](./WORKFLOWS.md)
+6. [Backup your setup](./BACKUPS.md)
+7. Contribute and [Create custom plugins](./PLUGINS_DEV.md)
+
+
+## Plugin types
+
+| Plugin type    | Icon | Description                                                      | When to run                         | Required | Data source [?](./PLUGINS_DEV.md) |
+| -------------- | ---- | ---------------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------- |
+| publisher      | ▶️    | Sending notifications to services.                               | `on_notification`                   | ✖        | Script                                |
+| dev scanner    | 🔍    | Create devices in the app, manages online/offline device status. | `schedule`                          | ✖        | Script / SQLite DB                    |
+| name discovery | 🆎    | Discovers names of devices via various protocols.                | `before_name_updates`, `schedule`   | ✖        | Script                                |
+| importer       | 📥    | Importing devices from another service.                          | `schedule`                          | ✖        | Script / SQLite DB                    |
+| system         | ⚙    | Providing core system functionality.                             | `schedule` / always on              | ✖/✔      | Script / Template                     |
+| other          | ♻    | Other plugins                                                    | misc                                | ✖        | Script / Template                     |
+
+## Features
+
+| Icon | Description                                                  |
+| ---- | ------------------------------------------------------------ |
+| 🖧    | Auto-imports the network topology diagram                    |
+| 🔄    | Has the option to sync some data back into the plugin source |
+
+
+## Available Plugins
+ 
+Device-detecting plugins insert values into the `CurrentScan` database table.  The plugins that are not required are safe to ignore, however, it makes sense to have at least some device-detecting plugins enabled, such as `ARPSCAN` or `NMAPDEV`. 
+
+
+| ID            | Type    | Description                                | Features | Required | Data source  | Detailed docs                                                       |
+|---------------|---------|--------------------------------------------|----------|----------|--------------|---------------------------------------------------------------------|
+| `APPRISE`     | ▶️      | Apprise notification proxy                |           |          | Script       | [_publisher_apprise](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_apprise/)          |
+| `ARPSCAN`     | 🔍      | ARP-scan on current network               |           |          | Script       | [arp_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/arp_scan/)                              |
+| `AVAHISCAN`   | 🆎      | Avahi (mDNS-based) name resolution        |           |          | Script       | [avahi_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/avahi_scan/)                          |
+| `ASUSWRT`     | 🔍       | Import connected devices from AsusWRT    |           |          | Script       | [asuswrt_import](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/asuswrt_import/)                  |
+| `CSVBCKP`     | ⚙       | CSV devices backup                        |           |          | Script       | [csv_backup](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/csv_backup/)                          |
+| `CUSTPROP`    | ⚙       | Managing custom device properties values  |           |  Yes     | Template     | [custom_props](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/custom_props/)                      |
+| `DBCLNP`      | ⚙       | Database cleanup                          |           |  Yes*    | Script       | [db_cleanup](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/db_cleanup/)                          |
+| `DDNS`        | ⚙       | DDNS update                               |           |          | Script       | [ddns_update](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/ddns_update/)                        |
+| `DHCPLSS`     | 🔍/📥/🆎| Import devices from DHCP leases          |           |          | Script       | [dhcp_leases](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_leases/)                        |
+| `DHCPSRVS`    | ♻       | DHCP servers                              |           |          | Script       | [dhcp_servers](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dhcp_servers/)                      |
+| `DIGSCAN`    | 🆎       | Dig (DNS) Name resolution                 |           |          | Script       | [dig_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/dig_scan/)                      |
+| `FREEBOX`     | 🔍/♻/🆎| Pull data and names from Freebox/Iliadbox |          |          | Script       | [freebox](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/freebox/)                                 |
+| `ICMP`        | ♻      | ICMP (ping) status checker                |           |          | Script       | [icmp_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/icmp_scan/)                            |
+| `INTRNT`      | 🔍      | Internet IP scanner                       |           |          | Script       | [internet_ip](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/internet_ip/)                        |
+| `INTRSPD`     | ♻       | Internet speed test                       |           |          | Script       | [internet_speedtest](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/internet_speedtest/)          |
+| `IPNEIGH`     | 🔍       | Scan ARP (IPv4) and NDP (IPv6) tables    |           |          | Script       | [ipneigh](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/ipneigh/)                                |
+| `LUCIRPC`     | 🔍       | Import connected devices from OpenWRT    |           |          | Script       | [luci_import](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/luci_import/)                        |
+| `MAINT`       | ⚙       | Maintenance of logs, etc.                 |           |          | Script       | [maintenance](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/maintenance/)                        |
+| `MQTT`        | ▶️      | MQTT for synching to Home Assistant       |           |          | Script       | [_publisher_mqtt](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_mqtt/)                |
+| `NBTSCAN`     | 🆎       | Nbtscan (NetBIOS-based) name resolution  |           |          | Script       | [nbtscan_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nbtscan_scan/)                      |
+| `NEWDEV`      | ⚙       | New device template                       |           |  Yes     | Template     | [newdev_template](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/newdev_template/)                |
+| `NMAP`        | ♻       | Nmap port scanning & discovery            |           |          | Script       | [nmap_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nmap_scan/)                            |
+| `NMAPDEV`     | 🔍      | Nmap dev scan on current network          |           |          | Script       | [nmap_dev_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nmap_dev_scan/)                    |
+| `NSLOOKUP`    | 🆎       | NSLookup (DNS-based) name resolution     |           |          | Script       | [nslookup_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nslookup_scan/)                    |
+| `NTFPRCS`     | ⚙       | Notification processing                   |           |  Yes     | Template     | [notification_processing](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/notification_processing/)|
+| `NTFY`        | ▶️      | NTFY notifications                        |           |          | Script       | [_publisher_ntfy](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_ntfy/)                |
+| `OMDSDN`      | 📥/🆎 ❌  |  UNMAINTAINED use `OMDSDNOPENAPI`        |   🖧 🔄  |          | Script       | [omada_sdn_imp](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/omada_sdn_imp/)                    |
+| `OMDSDNOPENAPI`| 📥/🆎   | OMADA TP-Link import via OpenAPI       |   🖧      |          | Script       | [omada_sdn_openapi](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/omada_sdn_openapi/)                    |
+| `PIHOLE`      | 🔍/🆎/📥| Pi-hole device import & sync             |           |          | SQLite DB    | [pihole_scan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_scan/)                        |
+| `PUSHSAFER`   | ▶️      | Pushsafer notifications                   |           |          | Script       | [_publisher_pushsafer](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_pushsafer/)      |
+| `PUSHOVER`    | ▶️      | Pushover notifications                    |           |          | Script       | [_publisher_pushover](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_pushover/)        |
+| `SETPWD`      | ⚙       | Set password                              |           |  Yes     | Template     | [set_password](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/set_password/)                      |
+| `SMTP`        | ▶️      | Email notifications                       |           |          | Script       | [_publisher_email](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_email/)              |
+| `SNMPDSC`     | 🔍/📥   | SNMP device import & sync                 |           |          | Script       | [snmp_discovery](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/snmp_discovery/)                  |
+| `SYNC`        | 🔍/⚙/📥| Sync & import from NetAlertX instances    |   🖧 🔄   | Yes     | Script        | [sync](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/sync/)                                      |
+| `TELEGRAM`    | ▶️      | Telegram notifications                    |           |          | Script       | [_publisher_telegram](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_telegram/)        |
+| `UI`          | ♻       | UI specific settings                      |           |  Yes     | Template     | [ui_settings](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/ui_settings/)                        |
+| `UNFIMP`      | 🔍/📥/🆎| UniFi device import & sync               |  🖧       |          | Script       | [unifi_import](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/unifi_import/)                      |
+| `VNDRPDT`     | ⚙       | Vendor database update                    |           |          | Script       | [vendor_update](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/vendor_update/)                    |
+| `WEBHOOK`     | ▶️      | Webhook notifications                     |           |          | Script       | [_publisher_webhook](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_webhook/)          |
+| `WEBMON`      | ♻       | Website down monitoring                   |           |          | Script       | [website_monitor](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/website_monitor/)                |
+| `WOL`         | ♻       | Automatic wake-on-lan                     |           |          | Script       | [wake_on_lan](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/wake_on_lan/)                        |
+
+
+> \* The database cleanup plugin (`DBCLNP`) is not _required_ but the app will become unusable after a while if not executed.
+> ❌ marked for removal/unmaintained - looking for help
+> ⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.
+
+
+
+## Enabling plugins
+
+Plugins can be enabled via Settings, and can be disabled as needed. 
+
+1. Research which plugin you'd like to use, enable `DISCOVER_PLUGINS` and load the required plugins in Settings via the `LOADED_PLUGINS` setting.
+1. Save the changes and review the Settings of the newly loaded plugins. 
+1. Change the `<prefix>_RUN` Setting to the recommended or custom value as per the documentation of the given setting  
+    - If using `schedule` on a `🔍 dev scanner` plugin, make sure the schedules are the same across all `🔍 dev scanner` plugins
+
+### Disabling, Unloading and Ignoring plugins
+
+1. Change the `<prefix>_RUN` Setting to `disabled` if you want to disable the plugin, but keep the settings
+1. If you want to speed up the application, you can unload the plugin by unselecting it in the `LOADED_PLUGINS` setting.
+    - Careful, once you save the Settings Unloaded plugin settings will be lost (old `app.conf` files are kept in the `/config` folder) 
+1. You can completely ignore plugins by placing a `ignore_plugin` file into the plugin directory. Ignored plugins won't show up in the `LOADED_PLUGINS` setting.
+
+## 🆕 Developing new custom plugins
+
+If you want to develop a custom plugin, please read this [Plugin development guide](./PLUGINS_DEV.md).

docs/PLUGINS_DEV.md

@@ -1,4 +1,4 @@
-## 🌟 Create a custom plugin: Overview
+# Creating a custom plugin
 
 NetAlertX comes with a plugin system to feed events from third-party scripts into the UI and then send notifications, if desired. The highlighted core functionality this plugin system supports, is:
 
@@ -12,7 +12,10 @@ NetAlertX comes with a plugin system to feed events from third-party scripts int
 
 ### 🎥 Watch the video:
 
-[![Watch the video](/docs/img/YouTube_thumbnail.png)](https://youtu.be/cdbxlwiWhv8)
+> [!TIP]
+> Read this guide [Development environment setup guide](./DEV_ENV_SETUP.md) to set up your local environment for development. 👩‍💻
+
+[![Watch the video](./img/YouTube_thumbnail.png)](https://youtu.be/cdbxlwiWhv8)
 
 ### 📸 Screenshots
 
@@ -46,7 +49,7 @@ Please read the below carefully if you'd like to contribute with a plugin yourse
   |----------------------|----------------------|----------------------| 
   | `config.json` | yes | Contains the plugin configuration (manifest) including the settings available to the user. |
   | `script.py` |  no | The Python script itself. You may call any valid linux command.  |
-  | `last_result.log` | no | The file used to interface between NetAlertX and the plugin. Required for a script plugin if you want to feed data into the app. |
+  | `last_result.<prefix>.log` | no | The file used to interface between NetAlertX and the plugin. Required for a script plugin if you want to feed data into the app. Stored in the `/api/log/plugins/` |
   | `script.log` | no | Logging output (recommended) |
   | `README.md` | yes | Any setup considerations or overview  |
 
@@ -83,7 +86,7 @@ The `config.json` file is the manifest of the plugin. It contains mainly setting
 
 ## Execution order
 
-The execution order is used to specify wwhen a plugin is executed. This is useful if a plugin has access and surfaces more information than others. If a device is detected by 2 plugins and inserted into the `CurrentScan` table, the plugin with the higher priority (e.g.: `Level_0` is a higher priority than `Level_1`) will insert it's values first. These values (devices) will be then prioritized over any values inserted later.
+The execution order is used to specify when a plugin is executed. This is useful if a plugin has access and surfaces more information than others. If a device is detected by 2 plugins and inserted into the `CurrentScan` table, the plugin with the higher priority (e.g.: `Level_0` is a higher priority than `Level_1`) will insert it's values first. These values (devices) will be then prioritized over any values inserted later.
 
 ```json
 {
@@ -103,7 +106,7 @@ Currently, these data sources are supported (valid `data_source` value).
 | External SQLite DB query | `sqlite-db-query` | yes | Executes a SQL query from the `CMD` setting on an external SQLite database mapped in the `DB_PATH` setting.  |
 | Plugin type | `plugin_type` | no | Specifies the type of the plugin and in which section the Plugin settings are displayed ( one of `general/system/scanner/other/publisher` ). | 
 
-> * "Needs to return a "table" means that the application expects a `last_result.log` file with some results. It's not a blocker, however warnings in the `app.log` might be logged.
+> * "Needs to return a "table" means that the application expects a `last_result.<prefix>.log` file with some results. It's not a blocker, however warnings in the `app.log` might be logged.
 
 > 🔎Example
 >```json
@@ -120,21 +123,21 @@ You can show or hide the UI on the "Plugins" page and "Plugins" tab for a plugin
 
 ### "data_source":  "script"
 
- If the `data_source` is set to `script` the `CMD` setting (that you specify in the `settings` array section in the `config.json`) contains an executable Linux command, that usually generates a `last_result.log` file (not required if you don't import any data into the app). The `last_result.log` file needs to be saved in the same folder as the plugin. 
+ If the `data_source` is set to `script` the `CMD` setting (that you specify in the `settings` array section in the `config.json`) contains an executable Linux command, that usually generates a `last_result.<prefix>.log` file (not required if you don't import any data into the app). The `last_result.<prefix>.log` file needs to be saved in `/api/log/plugins`. 
 
 > [!IMPORTANT]
-> A lot of the work is taken care of by the [`plugin_helper.py` library](/front/plugins/plugin_helper.py). You don't need to manage the `last_result.log` file if using the helper objects. Check other `script.py` of other plugins for details (The [Undicoverables plugins `script.py` file](/front/plugins/undiscoverables/script.py) is a good example).
+> A lot of the work is taken care of by the [`plugin_helper.py` library](/front/plugins/plugin_helper.py). You don't need to manage the `last_result.<prefix>.log` file if using the helper objects. Check other `script.py` of other plugins for details.
  
- The content of the `last_result.log` file needs to contain the columns as defined in the "Column order and values" section above. The order of columns can't be changed. After every scan it should contain only the results from the latest scan/execution. 
+ The content of the `last_result.<prefix>.log` file needs to contain the columns as defined in the "Column order and values" section above. The order of columns can't be changed. After every scan it should contain only the results from the latest scan/execution. 
 
-- The format of the `last_result.log` is a `csv`-like file with the pipe `|` as a separator. 
+- The format of the `last_result.<prefix>.log` is a `csv`-like file with the pipe `|` as a separator. 
 - 9 (nine) values need to be supplied, so every line needs to contain 8 pipe separators. Empty values are represented by `null`.  
 - Don't render "headers" for these "columns".
 Every scan result/event entry needs to be on a new line.
 - You can find which "columns" need to be present, and if the value is required or optional, in the "Column order and values" section. 
 - The order of these "columns" can't be changed.
 
-#### 🔎 last_result.log examples
+#### 🔎 last_result.prefix.log examples
 
 Valid CSV:
 
@@ -170,20 +173,20 @@ This SQL query is executed on the `app.db` SQLite database file.
 > SQL query example:
 > 
 > ```SQL
-> SELECT  dv.dev_Name as Object_PrimaryID, 
->     cast(dv.dev_LastIP as VARCHAR(100)) || ':' || cast( SUBSTR(ns.Port ,0, INSTR(ns.Port , '/')) as VARCHAR(100)) as Object_SecondaryID,  
+> SELECT  dv.devName as Object_PrimaryID, 
+>     cast(dv.devLastIP as VARCHAR(100)) || ':' || cast( SUBSTR(ns.Port ,0, INSTR(ns.Port , '/')) as VARCHAR(100)) as Object_SecondaryID,  
 >     datetime() as DateTime,  
 >     ns.Service as Watched_Value1,        
 >     ns.State as Watched_Value2,
 >     'null' as Watched_Value3,
 >     'null' as Watched_Value4,
 >     ns.Extra as Extra,
->     dv.dev_MAC as ForeignKey 
+>     dv.devMac as ForeignKey 
 > FROM 
 >     (SELECT * FROM Nmap_Scan) ns 
 > LEFT JOIN 
->     (SELECT dev_Name, dev_MAC, dev_LastIP FROM Devices) dv 
-> ON ns.MAC = dv.dev_MAC
+>     (SELECT devName, devMac, devLastIP FROM Devices) dv 
+> ON ns.MAC = dv.devMac
 > ```
 > 
 > Required `CMD` setting example with above query (you can set `"type": "label"` if you want it to make uneditable in the UI):
@@ -192,7 +195,7 @@ This SQL query is executed on the `app.db` SQLite database file.
 > {
 >             "function": "CMD",
 >            "type": {"dataType":"string", "elements": [{"elementType" : "input", "elementOptions" : [] ,"transformers": []}]},
->            "default_value":"SELECT  dv.dev_Name as Object_PrimaryID, cast(dv.dev_LastIP as VARCHAR(100)) || ':' || cast( SUBSTR(ns.Port ,0, INSTR(ns.Port , '/')) as VARCHAR(100)) as Object_SecondaryID,  datetime() as DateTime,  ns.Service as Watched_Value1,        ns.State as Watched_Value2,        'null' as Watched_Value3,        'null' as Watched_Value4,        ns.Extra as Extra        FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT dev_Name, dev_MAC, dev_LastIP FROM Devices) dv   ON ns.MAC = dv.dev_MAC",
+>            "default_value":"SELECT  dv.devName as Object_PrimaryID, cast(dv.devLastIP as VARCHAR(100)) || ':' || cast( SUBSTR(ns.Port ,0, INSTR(ns.Port , '/')) as VARCHAR(100)) as Object_SecondaryID,  datetime() as DateTime,  ns.Service as Watched_Value1,        ns.State as Watched_Value2,        'null' as Watched_Value3,        'null' as Watched_Value4,        ns.Extra as Extra        FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv   ON ns.MAC = dv.devMac",
 >            "options": [],
 >            "localized": ["name", "description"],
 >            "name" : [{
@@ -361,7 +364,7 @@ Plugin results are always inserted into the standard `Plugin_Objects` database t
 >3.  That's it. The app takes care of the rest. It loops thru the objects discovered by the plugin, takes the results line-by-line, and inserts them into the database table specified in `"mapped_to_table"`. The columns are translated from the generic plugin columns to the target table columns via the `"mapped_to_column"` property in the column definitions.
 
 > [!NOTE] 
-> You can create a column mapping with a default value via the `mapped_to_column_data` property. This means that the value of the given column will always be this value. That also menas that the `"column": "NameDoesntMatter"` is not important as there is no database source column. 
+> You can create a column mapping with a default value via the `mapped_to_column_data` property. This means that the value of the given column will always be this value. That also means that the `"column": "NameDoesntMatter"` is not important as there is no database source column. 
 
 
 >🔍 Example:
@@ -460,7 +463,7 @@ Below are some general additional notes, when defining `params`:
 
 - `"name":"name_value"` - is used as a wildcard replacement in the `CMD` setting value by using curly brackets `{name_value}`. The wildcard is replaced by the result of the `"value" : "param_value"` and `"type":"type_value"` combo configuration below.
 - `"type":"<sql|setting>"` - is used to specify the type of the params, currently only 2 supported (`sql`,`setting`).
-  - `"type":"sql"` - will execute the SQL query specified in the `value` property. The sql query needs to return only one column. The column is flattened and separated by commas (`,`), e.g: `SELECT dev_MAC from DEVICES` -> `Internet,74:ac:74:ac:74:ac,44:44:74:ac:74:ac`. This is then used to replace the wildcards in the `CMD` setting.  
+  - `"type":"sql"` - will execute the SQL query specified in the `value` property. The sql query needs to return only one column. The column is flattened and separated by commas (`,`), e.g: `SELECT devMac from DEVICES` -> `Internet,74:ac:74:ac:74:ac,44:44:74:ac:74:ac`. This is then used to replace the wildcards in the `CMD` setting.  
   - `"type":"setting"` - The setting code name. A combination of the value from `unique_prefix` + `_` + `function` value, or otherwise the code name you can find in the Settings page under the Setting display name, e.g. `PIHOLE_RUN`. 
 - `"value": "param_value"` - Needs to contain a setting code name or SQL query without wildcards.
 - `"timeoutMultiplier" : true` - used to indicate if the value should multiply the max timeout for the whole script run by the number of values in the given parameter.
@@ -474,13 +477,13 @@ Below are some general additional notes, when defining `params`:
 >     "params" : [{
 >            "name"              : "ips",
 >            "type"              : "sql",
->            "value"             : "SELECT dev_LastIP from DEVICES",
+>            "value"             : "SELECT devLastIP from DEVICES",
 >            "timeoutMultiplier" : true
 >        },
 >        {
 >            "name"              : "macs",
 >            "type"              : "sql",
->            "value"             : "SELECT dev_MAC from DEVICES"            
+>            "value"             : "SELECT devMac from DEVICES"            
 >        },
 >        {
 >            "name"              : "timeout",
@@ -500,7 +503,7 @@ Below are some general additional notes, when defining `params`:
 #### ⚙ Setting object structure
 
 > [!NOTE] 
-> The settings flow and when Plugin specific settings are applied is described under the [Settings system](/docs/SETTINGS_SYSTEM.md).
+> The settings flow and when Plugin specific settings are applied is described under the [Settings system](./SETTINGS_SYSTEM.md).
 
 Required attributes are:
 
@@ -518,10 +521,64 @@ Required attributes are:
 | (optional) `"override_value"` | Used to determine a user-defined override for the setting. Useful for template-based plugins, where you can choose to leave the current value or override it with the value defined in the setting. (Work in progress) |
 | (optional) `"events"` | Used to trigger the plugin. Usually used on the `RUN` setting. Not fully tested in all scenarios. Will show a play button next to the setting. After clicking, an event is generated for the backend in the `Parameters` database table to process the front-end event on the next run. |
 
+### UI Component Types Documentation
+
+This section outlines the structure and types of UI components, primarily used to build HTML forms or interactive elements dynamically. Each UI component has a `"type"` which defines its structure, behavior, and rendering options.
+
+#### UI Component JSON Structure
+The UI component is defined as a JSON object containing a list of `elements`. Each element specifies how it should behave, with properties like `elementType`, `elementOptions`, and any associated `transformers` to modify the data. The example below demonstrates how a component with two elements (`span` and `select`) is structured:
+
+```json
+{
+      "function": "devIcon",
+      "type": {
+        "dataType": "string",
+        "elements": [
+          {
+            "elementType": "span",
+            "elementOptions": [
+              { "cssClasses": "input-group-addon iconPreview" },
+              { "getStringKey": "Gen_SelectToPreview" },
+              { "customId": "NEWDEV_devIcon_preview" }
+            ],
+            "transformers": []
+          },
+          {
+            "elementType": "select",
+            "elementHasInputValue": 1,
+            "elementOptions": [
+              { "cssClasses": "col-xs-12" },
+              {
+                "onChange": "updateIconPreview(this)"
+              },
+              { "customParams": "NEWDEV_devIcon,NEWDEV_devIcon_preview" }
+            ],
+            "transformers": []
+          }          
+        ]
+      }
+}
+
+```
+
+### Rendering Logic
+
+The code snippet provided demonstrates how the elements are iterated over to generate their corresponding HTML. Depending on the `elementType`, different HTML tags (like `<select>`, `<input>`, `<textarea>`, `<button>`, etc.) are created with the respective attributes such as `onChange`, `my-data-type`, and `class` based on the provided `elementOptions`. Events can also be attached to elements like buttons or select inputs.
+
+### Key Element Types
+
+- **`select`**: Renders a dropdown list. Additional options like `isMultiSelect` and event handlers (e.g., `onChange`) can be attached.
+- **`input`**: Handles various types of input fields, including checkboxes, text, and others, with customizable attributes like `readOnly`, `placeholder`, etc.
+- **`button`**: Generates clickable buttons with custom event handlers (`onClick`), icons, or labels.
+- **`textarea`**: Creates a multi-line input box for text input.
+- **`span`**: Used for inline text or content with customizable classes and data attributes.
+
+Each element may also have associated events (e.g., running a scan or triggering a notification) defined under `Events`.
+
     
 ##### Supported settings `function` values
 
-You can have any `"function": "my_custom_name"` custom name, however, the ones listed below have a specific functionality attached to them. If you use a custom name, then the setting is mostly used as an input parameter for the `params` section.
+You can have any `"function": "my_custom_name"` custom name, however, the ones listed below have a specific functionality attached to them. 
 
 | Setting | Description |
 | ------- | ----------- |
@@ -536,7 +593,7 @@ You can have any `"function": "my_custom_name"` custom name, however, the ones l
 |  | - "before_config_save" - run before the config is marked as saved. Useful if your plugin needs to modify the `app.conf` file. |
 | `RUN_SCHD` | (required if you include "schedule" in the above `RUN` function) Cron-like scheduling is used if the `RUN` setting is set to `schedule`. |
 | `CMD` | (required) Specifies the command that should be executed. |
-| `API_SQL` | (not implemented) Generates a `table_` + `code_name` + `.json` file as per [API docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md). |
+| `API_SQL` | (not implemented) Generates a `table_` + `code_name` + `.json` file as per [API docs](./API.md). |
 | `RUN_TIMEOUT` | (optional) Specifies the maximum execution time of the script. If not specified, a default value of 10 seconds is used to prevent hanging. |
 | `WATCH` | (optional) Specifies which database columns are watched for changes for this particular plugin. If not specified, no notifications are sent. |
 | `REPORT_ON` | (optional) Specifies when to send a notification. Supported options are: |
@@ -595,7 +652,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
 | See below for information on `threshold`, `replace`. | |
 |  |  |
 | `options` Property | Used in conjunction with types like `threshold`, `replace`, `regex`. |
-| `options_params` Property | Used in conjunction with a `"options": "[{value}]"` template and `text.select`/`list.select`. Can specify SQL query (needs to return 2 columns `SELECT dev_Name as name, dev_Mac as id`) or Setting (not tested) to populate the dropdown. Check example below or have a look at the `NEWDEV` plugin `config.json` file. |
+| `options_params` Property | Used in conjunction with a `"options": "[{value}]"` template and `text.select`/`list.select`. Can specify SQL query (needs to return 2 columns `SELECT devName as name, devMac as id`) or Setting (not tested) to populate the dropdown. Check example below or have a look at the `NEWDEV` plugin `config.json` file. |
 | `threshold` | The `options` array contains objects ordered from the lowest `maximum` to the highest. The corresponding `hexColor` is used for the value background color if it's less than the specified `maximum` but more than the previous one in the `options` array. |
 | `replace` | The `options` array contains objects with an `equals` property, which is compared to the "value." If the values are the same, the string in `replacement` is displayed in the UI instead of the actual "value". |
 | `regex` | Applies a regex to the value.  The `options` array contains objects with an `type` (must be set to `regex`) and `param` (must contain the regex itself) property. |
@@ -603,7 +660,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
 | Type Definitions |  |
 | `device_mac` | The value is considered to be a MAC address, and a link pointing to the device with the given MAC address is generated. |
 | `device_ip` | The value is considered to be an IP address. A link pointing to the device with the given IP is generated. The IP is checked against the last detected IP address and translated into a MAC address, which is then used for the link itself. |
-| `device_name_mac` | The value is considered to be a MAC address, and a link pointing to the device with the given IP is generated. The link label is resolved as the target device name. |
+| `device_name_mac` | The value is considered to be a MAC address, and a link pointing to the device with the given MAC is generated. The link label is resolved as the target device name. |
 | `url` | The value is considered to be a URL, so a link is generated. |
 | `textbox_save` | Generates an editable and saveable text box that saves values in the database. Primarily intended for the `UserData` database column in the `Plugins_Objects` table. |
 | `url_http_https` | Generates two links with the `https` and `http` prefix as lock icons. |
@@ -615,7 +672,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
 
 
 ```json
-        "function": "dev_DeviceType",
+        "function": "devType",
         "type": {"dataType":"string", "elements": [{"elementType" : "select", "elementOptions" : [] ,"transformers": []}]},
         "maxLength": 30,
         "default_value": "",
@@ -624,7 +681,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
             {
                 "name"  : "value",
                 "type"  : "sql",
-                "value" : "SELECT '' as id, '' as name UNION SELECT dev_DeviceType as id, dev_DeviceType as name FROM (SELECT dev_DeviceType FROM Devices UNION SELECT 'Smartphone' UNION SELECT 'Tablet' UNION SELECT 'Laptop' UNION SELECT 'PC' UNION SELECT 'Printer' UNION SELECT 'Server' UNION SELECT 'NAS' UNION SELECT 'Domotic' UNION SELECT 'Game Console' UNION SELECT 'SmartTV' UNION SELECT 'Clock' UNION SELECT 'House Appliance' UNION SELECT 'Phone' UNION SELECT 'AP' UNION SELECT 'Gateway' UNION SELECT 'Firewall' UNION SELECT 'Switch' UNION SELECT 'WLAN' UNION SELECT 'Router' UNION SELECT 'Other') AS all_devices ORDER BY id;"
+                "value" : "SELECT '' as id, '' as name UNION SELECT devType as id, devType as name FROM (SELECT devType FROM Devices UNION SELECT 'Smartphone' UNION SELECT 'Tablet' UNION SELECT 'Laptop' UNION SELECT 'PC' UNION SELECT 'Printer' UNION SELECT 'Server' UNION SELECT 'NAS' UNION SELECT 'Domotic' UNION SELECT 'Game Console' UNION SELECT 'SmartTV' UNION SELECT 'Clock' UNION SELECT 'House Appliance' UNION SELECT 'Phone' UNION SELECT 'AP' UNION SELECT 'Gateway' UNION SELECT 'Firewall' UNION SELECT 'Switch' UNION SELECT 'WLAN' UNION SELECT 'Router' UNION SELECT 'Other') AS all_devices ORDER BY id;"
             },
             {
                 "name"  : "uilang",

docs/RANDOM_MAC.md

@@ -1,53 +1,32 @@
 # Privacy & Random MAC's
 <!--- --------------------------------------------------------------------- --->
 
-The latest versions of some operating systems (IOS and Android) incorporate a
-new & interesting functionality to improve privacy: **Random MACs**.
+Some operating systems incorporate randomize MAC addresses to improve privacy.
 
-This functionality allows you to **hide the real MAC** of the device and
-**assign a random MAC** when we connect to WIFI networks.
+This functionality allows you to **hide the real MAC** of the device and **assign a random MAC** when we connect to WIFI networks.
 
-This behavior is especially useful when connecting to WIFI's that we do not
-know, but it **is totally useless when connecting to our own WIFI's** or known
-networks.
+This behavior is especially useful when connecting to WIFI's that we do not know, but it **is totally useless when connecting to our own WIFI's** or known networks.
 
-**I recommend disabling this operation when connecting our devices to our own
-WIFI's**, in this way, NetAlertX will be able to identify the device, and it
-will not identify it as a new device every so often (every time IOS or Android
-decides to change the MAC).
+**I recommend disabling this on-device functionality when connecting our devices to our own WIFI's**, this way, NetAlertX will be able to identify the device, and it will not identify it as a new device every so often (every time iOS or Android randomizes the MAC).
 
 **Random MACs** are recognized by the characters "2", "6", "A", or "E" as the 2nd character in the Mac address. You can disable specific prefixes to be detected as random MAC addresses by specifying the `UI_NOT_RANDOM_MAC` setting.
 
+## Windows
+
+![windows](./img/RANDOM_MAC/windows_random_mac.png)
+
+  - [How to Disable MAC Randomization on Windows](https://www.androidphonesoft.com/blog/how-to-turn-off-random-mac-address-windows-10/)
+
 ## IOS
-![ios][ios]
+
+![ios](./img/RANDOM_MAC/ios_random_mac.png)
 
   - [Use private Wi-Fi addresses in iOS 14](https://support.apple.com/en-us/HT211227)
 
 ## Android
-![Android][Android]
+
+![ios](./img/RANDOM_MAC/android_random_mac.jpg)
 
   - [How to Disable MAC Randomization in Android 10](https://support.boingo.com/s/article/How-to-Disable-MAC-Randomization-in-Android-10-Android-Q)
   - [How do I disable random Wi-Fi MAC address on Android 10](https://support.plume.com/hc/en-gb/articles/360052070714-How-do-I-disable-random-Wi-Fi-MAC-address-on-Android-10-)
   
-
-### License
-  GPL 3.0
-  [Read more here](../LICENSE.txt)
-
-### Contact
-  Always use the Issue tracker for the correct fork, for example: 
-  
-  [jokob-sk/NetAlertX](https://github.com/jokob-sk/NetAlertX/issues). Please also follow the guidelines on:
-
-  - ➕ [Pull Request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs) 
-  - 🙏 [Feature request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-feature-requests) 
-  - 🐛 [Issue guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-submitting-an-issue-or-bug)
-
-  
-  ***Suggestions and comments are welcome***
-
-
-<!--- --------------------------------------------------------------------- --->
-[ios]: https://9to5mac.com/wp-content/uploads/sites/6/2020/08/how-to-use-private-wifi-mac-address-iphone-ipad.png?resize=2048,1009 "ios"
-[Android]: ./img/android_random_mac.jpg "Android"
-

docs/README.md

@@ -3,7 +3,7 @@
 <details>
   <summary>:information_source: In the app hover over settings or fields/labels or click blue in-app ❔ (question-mark) icons to get to relevant documentation pages.</summary>
 
-  ![In-app help](/docs/img/GENERAL/in-app-help.png)
+  ![In-app help](./img/GENERAL/in-app-help.png)
 
 </details>
 
@@ -17,7 +17,7 @@ There is also an in-app Help / FAQ section that should be answering frequently a
 
 #### 💻 Bare-metal / On-server (Experimental/community supported 🧪)
 
-- [(Experimental 🧪) On-hardware instructions](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 
+- [(Experimental 🧪) On-hardware instructions](./HW_INSTALL.md) 
 
 - Alternative bare-metal install forks: 
   - [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) (maintained)
@@ -27,54 +27,58 @@ There is also an in-app Help / FAQ section that should be answering frequently a
 
 #### 📥 Initial Setup
 
-- [Subnets and VLANs configuration for arp-scan](/docs/SUBNETS.md)
-- [SMTP server config](/docs/SMTP.md)
-- [Custom Icon configuration and support](/docs/ICONS.md)
-- [Notifications](/docs/NOTIFICATIONS.md)
-- [Better name resolution with Reverse DNS](/docs/REVERSE_DNS.md)
-- [Network treemap configuration](/docs/NETWORK_TREE.md)
-- [Backups](/docs/BACKUPS.md)
-- [Plugins overview](/front/plugins/README.md)
+- [Synology Guide](./SYNOLOGY_GUIDE.md)
+- [Subnets and VLANs configuration for arp-scan](./SUBNETS.md)
+- [Scanning Remote Networks](./REMOTE_NETWORKS.md)
+- [SMTP server config](./SMTP.md)
+- [Custom Icon configuration and support](./ICONS.md)
+- [Notifications](./NOTIFICATIONS.md)
+- [Better name resolution with Reverse DNS](./REVERSE_DNS.md)
+- [Network treemap configuration](./NETWORK_TREE.md)
+- [Backups](./BACKUPS.md)
+- [Plugins overview](/docs/PLUGINS.md)
 
 #### 🐛 Debugging help & tips
 
-- [Debugging tips](/docs/DEBUG_TIPS.md)
-- [Debugging UI not showing](/docs/WEB_UI_PORT_DEBUG.md)
-- [Invalid JSON errors debug help](/docs/DEBUG_INVALID_JSON.md)
-- [Troubleshooting Plugins](/docs/DEBUG_PLUGINS.md)
-- [File Permissions](/docs/FILE_PERMISSIONS.md)
+- [Debugging tips](./DEBUG_TIPS.md)
+- [Debugging UI not showing](./WEB_UI_PORT_DEBUG.md)
+- [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md)
+- [Troubleshooting Plugins](./DEBUG_PLUGINS.md)
+- [File Permissions](./FILE_PERMISSIONS.md)
+- [Performance tips](./PERFORMANCE.md)
 
 #### 🔝 Popular/Suggested
 
-- [Home Assistant](/docs/HOME_ASSISTANT.md)
-- [Bulk edit devices](/docs/DEVICES_BULK_EDITING.md)
+- [Home Assistant](./HOME_ASSISTANT.md)
+- [Bulk edit devices](./DEVICES_BULK_EDITING.md)
 
 #### ⚙ System Management
 
-- [Manage devices (legacy docs)](/docs/DEVICE_MANAGEMENT.md)
-- [Random MAC/MAC icon meaning (legacy docs)](/docs/RANDOM_MAC.md)
-
+- [Manage devices (legacy docs)](./DEVICE_MANAGEMENT.md)
+- [Random MAC/MAC icon meaning (legacy docs)](./RANDOM_MAC.md)
 
 #### 🔎 Examples
 
-- [N8N webhook example](/docs/WEBHOOK_N8N.md)
+- [N8N webhook example](./WEBHOOK_N8N.md)
 
 #### ♻ Misc
 
-- [Version history (legacy)](/docs/VERSIONS_HISTORY.md)
-- [Reverse proxy (Nginx, Apache, SWAG)](/docs/REVERSE_PROXY.md)
+- [Version history (legacy)](./VERSIONS_HISTORY.md)
+- [Reverse proxy (Nginx, Apache, SWAG)](./REVERSE_PROXY.md)
+- [Installing Updates](./UPDATES.md)
+- [Setting up Authelia](./AUTHELIA.md) (DRAFT)
 
 #### 👩‍💻For Developers👨‍💻
 
-- [Setting up your DEV environment](/docs/DEV_ENV_SETUP.md)
+- [Setting up your DEV environment](./DEV_ENV_SETUP.md)
 - [Server APP code structure](/server/README.md)
-- [Database structure](/docs/DATABASE.md)
-- [API endpoints details](/docs/API.md)
-- [Plugin development guide](/docs/PLUGINS_DEV.md)
-- [Settings system](/docs/SETTINGS_SYSTEM.md)
-- [New Version notifications](/docs/VERSIONS.md)
-- [Frontend development tips](/docs/FRONTEND_DEVELOPMENT.md)
-- [Webhook secrets](/docs/WEBHOOK_SECRET.md)
+- [Database structure](./DATABASE.md)
+- [API endpoints details](./API.md)
+- [Plugin development guide](./PLUGINS_DEV.md)
+- [Settings system](./SETTINGS_SYSTEM.md)
+- [New Version notifications](./VERSIONS.md)
+- [Frontend development tips](./FRONTEND_DEVELOPMENT.md)
+- [Webhook secrets](./WEBHOOK_SECRET.md)
 
 Feel free to suggest or submit new docs via a PR. 
 
@@ -133,8 +137,8 @@ Some additional context:
 
 Before submitting a new issue please spend a couple of minutes on research:
 
-* Check [🛑 Common issues](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md#common-issues) 
+* Check [🛑 Common issues](./DEBUG_TIPS.md#common-issues) 
 * Check [💡 Closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) if a similar issue was solved in the past.
-* When submitting an issue ❗[enable debug](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md)❗
+* When submitting an issue ❗[enable debug](./DEBUG_TIPS.md)❗
 
 ⚠ Please follow the pre-defined issue template to resolve your issue faster.

docs/REMOTE_NETWORKS.md

@@ -0,0 +1,52 @@
+# Scanning Remote or Inaccessible Networks
+
+By design, local network scanners such as `arp-scan` use ARP (Address Resolution Protocol) to map IP addresses to MAC addresses on the local network. Since ARP operates at Layer 2 (Data Link Layer), it typically works only within a single broadcast domain, usually limited to a single router or network segment.
+
+> [!NOTE]
+> Ping and `ARPSCAN` use different protocols so even if you can ping devices it doesn't mean `ARPSCAN` can detect them.
+
+To scan multiple locally accessible network segments, add them as subnets according to the [subnets](./SUBNETS.md) documentation. If `ARPSCAN` is not suitable for your setup, read on.
+
+## Complex Use Cases
+
+The following network setups might make some devices undetectable with `ARPSCAN`. Check the specific setup to understand the cause and find potential workarounds to report on these devices.
+
+### Wi-Fi Extenders
+
+Wi-Fi extenders typically create a separate network or subnet, which can prevent network scanning tools like `arp-scan` from detecting devices behind the extender.
+
+> **Possible workaround**: Scan the specific subnet that the extender uses, if it is separate from the main network.
+
+### VPNs
+
+ARP operates at Layer 2 (Data Link Layer) and works only within a local area network (LAN). VPNs, which operate at Layer 3 (Network Layer), route traffic between networks, preventing ARP requests from discovering devices outside the local network.
+
+VPNs use virtual interfaces (e.g., `tun0`, `tap0`) to encapsulate traffic, bypassing ARP-based discovery. Additionally, many VPNs use NAT, which masks individual devices behind a shared IP address.
+
+> **Possible workaround**: Configure the VPN to bridge networks instead of routing to enable ARP, though this depends on the VPN setup and security requirements.
+
+# Other Workarounds
+
+The following workarounds should work for most complex network setups.
+
+## Supplementing Plugins
+
+You can use supplementary plugins that employ alternate methods. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](./PLUGINS.md) to find a plugin that works with your router and network setup.
+
+## Multiple NetAlertX Instances
+
+If you have servers in different networks, you can set up separate NetAlertX instances on those subnets and synchronize the results into one instance using the [`SYNC` plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/sync).
+
+## Manual Entry
+
+If you don't need to discover new devices and only need to report on their status (`online`, `offline`, `down`), you can manually enter devices and check their status using the [`ICMP` plugin](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/icmp_scan/), which uses the `ping` command internally.
+
+For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation.
+
+To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) so they appear online.
+
+## NMAP and Fake MAC Addresses
+
+Scanning remote networks with NMAP is possible (via the `NMAPDEV` plugin), but since it cannot retrieve the MAC address, you need to enable the `NMAPDEV_FAKE_MAC` setting. This will generate a fake MAC address based on the IP address, allowing you to track devices. However, this can lead to inconsistencies, especially if the IP address changes or a previously logged device is rediscovered. If this setting is disabled, only the IP address will be discovered, and devices with missing MAC addresses will be skipped.
+
+Check the [NMAPDEV plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nmap_dev_scan) for details

docs/REVERSE_DNS.md

@@ -2,13 +2,17 @@
 
 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.  
+> 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.
+
 
 > Example 1: Reverse DNS `disabled`
 > 
 > ```
 > jokob@Synology-NAS:/$ nslookup 192.168.1.58
 > ** server can't find 58.1.168.192.in-addr.arpa: NXDOMAIN
-> 
 > ```
 
 > Example 2: Reverse DNS `enabled`
@@ -27,6 +31,29 @@ If you are running a DNS server, such as **AdGuard**, set up **Private reverse D
 5. Click **Apply** to save your settings.
 
 
+### Specifying the DNS in the container
+
+You can specify the DNS server in the docker-compose to improve name resolution on your network. 
+
+```yaml
+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
+```
+
 ### Using a custom resolv.conf file
 
 You can configure a custom **/etc/resolv.conf** file in **docker-compose.yml** and set the nameserver to your LAN DNS server (e.g.: Pi-Hole). See the relevant [resolv.conf man](https://www.man7.org/linux/man-pages/man5/resolv.conf.5.html) entry for details. 
@@ -38,12 +65,12 @@ version: "3"
 services:
   netalertx:
     container_name: netalertx
-    image: "jokobsk/netalertx:latest"
+    image: "ghcr.io/jokob-sk/netalertx:latest"
     restart: unless-stopped
     volumes:
       - ./config/app.conf:/app/config/app.conf
       - ./db:/app/db
-      - ./log:/app/front/log
+      - ./log:/app/log
       - ./config/resolv.conf:/etc/resolv.conf                          # Mapping the /resolv.conf file for better name resolution
     environment:
       - TZ=Europe/Berlin

docs/REVERSE_PROXY.md

@@ -477,7 +477,7 @@ docker run -d --rm --network=host \
   -v /appl/docker/netalertx/default:/etc/nginx/sites-available/default \
   -e TZ=Europe/Amsterdam \
   -e PORT=20211 \
-  jokobsk/netalertx:latest
+  ghcr.io/jokob-sk/netalertx:latest
 
 ```
 

docs/SECURITY.md

@@ -0,0 +1,102 @@
+## 🧭 Responsibility Disclaimer
+
+NetAlertX provides powerful tools for network scanning, presence detection, and automation. However, **it is up to you—the deployer—to ensure that your instance is properly secured**.
+
+This includes (but is not limited to):
+- Controlling who has access to the UI and API
+- Following network and container security best practices
+- Running NetAlertX only on networks where you have legal authorization
+- Keeping your deployment up to date with the latest patches
+
+> NetAlertX is not responsible for misuse, misconfiguration, or unsecure deployments. Always test and secure your setup before exposing it to the outside world.
+
+# 🔐 Securing Your NetAlertX Instance
+
+NetAlertX is a powerful network scanning and automation framework. With that power comes responsibility. **It is your responsibility to secure your deployment**, especially if you're running it outside a trusted local environment.
+
+---
+
+## ⚠️ TL;DR – Key Security Recommendations
+
+- ✅ **NEVER expose NetAlertX directly to the internet without protection**
+- ✅ Use a **VPN or Tailscale** to access remotely
+- ✅ Enable **password protection** for the web UI
+- ✅ Harden your container environment (e.g., no unnecessary privileges)
+- ✅ Use **firewalls and IP whitelisting**
+- ✅ Keep the software **updated**
+- ✅ Limit the scope of **plugins and API keys**
+
+---
+
+## 🔗 Access Control with VPN (or Tailscale)
+
+NetAlertX is designed to be run on **private LANs**, not the open internet.
+
+**Recommended**: Use a VPN to access NetAlertX from remote locations.
+
+### ✅ Tailscale (Easy VPN Alternative)
+
+Tailscale sets up a private mesh network between your devices. It's fast to configure and ideal for NetAlertX.  
+👉 [Get started with Tailscale](https://tailscale.com/)
+
+---
+
+## 🔑 Web UI Password Protection
+
+By default, NetAlertX does **not** require login. Before exposing the UI in any way:
+
+1. Enable password protection:
+   ```ini
+   SETPWD_enable_password=true
+   SETPWD_password=your_secure_password
+   ```
+
+2. Passwords are stored as SHA256 hashes
+
+3. Default password (if not changed): 123456 — change it ASAP!
+
+
+> To disable authenticated login, set `SETPWD_enable_password=false` in `app.conf`
+
+
+---
+
+## 🔥 Additional Security Measures
+
+- **Firewall / Network Rules**  
+  Restrict UI/API access to trusted IPs only.
+
+- **Limit Docker Capabilities**  
+  Avoid `--privileged`. Use `--cap-add=NET_RAW` and others **only if required** by your scan method.
+
+- **Keep NetAlertX Updated**  
+  Regular updates contain bug fixes and security patches.
+
+- **Plugin Permissions**  
+  Disable unused plugins. Only install from trusted sources.
+
+- **Use Read-Only API Keys**  
+  When integrating NetAlertX with other tools, scope keys tightly.
+
+---
+
+## 🧱 Docker Hardening Tips
+
+- Use `read-only` mount options where possible (`:ro`)
+- Avoid running as `root` unless absolutely necessary
+- Consider using `docker scan` or other container image vulnerability scanners
+- Run with `--network host` **only on trusted networks** and only if needed for ARP-based scans
+
+---
+
+## 📣 Responsible Disclosure
+
+If you discover a vulnerability or security concern, please report it **privately** to:
+
+📧 [jokob@duck.com](mailto:jokob@duck.com?subject=NetAlertX%20Security%20Disclosure)
+
+We take security seriously and will work to patch confirmed issues promptly. Your help in responsible disclosure is appreciated!
+
+---
+
+By following these recommendations, you can ensure your NetAlertX deployment is both powerful **and** secure.

docs/SESSION_INFO.md

@@ -0,0 +1,62 @@
+# Sessions Section in 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.
+
+ ![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png)
+
+---
+
+## Key Fields
+
+1. **Date and Time of First Connection**
+   - **Description:** Displays the first detected connection time for the device.
+   - **Editability:** Uneditable (auto-detected).
+   - **Source:** Automatically captured when the device is first added to the system.
+
+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
+
+### 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)`
+
+- Devices scanned in the current cycle (**CurrentScan**) are checked against the **Devices** table.
+- 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
+When a new connection is detected, the system creates a session record:
+
+`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)`
+
+- A new session is logged in the **Sessions** table if no prior session exists.
+- 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.
+
+### 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**.
+
+![Monitoring Device Presence](./img/SESSION_INFO/Monitoring_Presence.png)
+
+

docs/SETTINGS_SYSTEM.md

@@ -10,11 +10,11 @@ The source of truth for user-defined values is the `app.conf` file. Editing the
 
 #### Settings database table
 
-The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](/docs/DATABASE.md). 
+The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md). 
 
 #### table_settings.json
 
-This is the [API endpoint](/docs/API.md) that reflects the state of the `Settings` database table. Settings can be accessed with the:
+This is the [API endpoint](./API.md) that reflects the state of the `Settings` database table. Settings can be accessed with the:
 
 * `getSetting(key)` JavaScript method
 
@@ -32,7 +32,7 @@ The App generates two `app.conf` entries for every setting (Since version 23.8+)
 > [!NOTE] 
 > This is the preferred way adding settings going forward. I'll be likely migrating all app settings into plugin-based settings.
 
-Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
+Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
 
 ![Screen 1][screen1]
 

docs/SMTP.md

@@ -1,6 +1,49 @@
-# 📧 SMTP guides
+# 📧 SMTP server guides
 
-## Using the GMX SMTP server
+The SMTP plugin supports any SMTP server. Here are some commonly used services to help speed up your configuration.
+
+> [!NOTE]
+> If you are using a self hosted SMTP server ssh into the container and verify (e.g. via ping) that your server is reachable from within the NetAlertX container. See also how to ssh into the container if you are running it as a [Home Assistant](./HOME_ASSISTANT.md) addon. 
+
+## Gmail
+    
+1. Create an app password by following the instructions from Google, you need to Enable 2FA for this to work.
+[https://support.google.com/accounts/answer/185833](https://support.google.com/accounts/answer/185833)
+
+2. Specify the following settings:
+
+```python
+    SMTP_RUN='on_notification'
+    SMTP_SKIP_TLS=True
+    SMTP_FORCE_SSL=True 
+    SMTP_PORT=465
+    SMTP_SERVER='smtp.gmail.com'
+    SMTP_PASS='16-digit passcode from google'
+    SMTP_REPORT_TO='some_target_email@gmail.com'
+```
+
+## Brevo
+
+Brevo allows for 300 free emails per day as of time of writing. 
+
+1. Create an account on Brevo: https://www.brevo.com/free-smtp-server/
+2. Click your name -> SMTP & API
+3. Click Generate a new SMTP key
+4. Save the details and fill in the NetAlertX settings as below.
+
+```python
+SMTP_SERVER='smtp-relay.brevo.com'
+SMTP_PORT=587
+SMTP_SKIP_LOGIN=False
+SMTP_USER='user@email.com'
+SMTP_PASS='xsmtpsib-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxx'
+SMTP_SKIP_TLS=False
+SMTP_FORCE_SSL=False
+SMTP_REPORT_TO='some_target_email@gmail.com'
+SMTP_REPORT_FROM='NetAlertX <user@email.com>'
+```
+
+## GMX
 
 1. Go to your GMX account https://account.gmx.com
 2. Under Security Options enable 2FA (Two-factor authentication)
@@ -21,21 +64,3 @@
     SMTP_REPORT_TO='some_target_email@gmail.com'
 ```
 
-
-## Using the Gmail SMTP server
-    
-1. Create an app password by following the instructions from Google, you need to Enable 2FA for this to work.
-[https://support.google.com/accounts/answer/185833](https://support.google.com/accounts/answer/185833)
-
-2. Specify the following settings:
-
-```python
-    SMTP_RUN='on_notification'
-    SMTP_SKIP_TLS=True
-    SMTP_FORCE_SSL=True 
-    SMTP_PORT=465
-    SMTP_SERVER='smtp.gmail.com'
-    SMTP_PASS='16-digit passcode from google'
-    SMTP_REPORT_TO='some_target_email@gmail.com'
-```
-

docs/SUBNETS.md

@@ -1,107 +1,122 @@
-# Subnets configuration
+# Subnets Configuration
 
-You need to specify the network interface and the network mask. You can also configure multiple subnets and specify VLANS (see exceptions below).
+You need to specify the network interface and the network mask. You can also configure multiple subnets and specify VLANs (see VLAN exceptions below).
 
-> [!TIP]
-> You may need to increase the time between scans `ARPSCAN_RUN_SCHD` and the timeout `ARPSCAN_RUN_TIMEOUT` (and similar setting on related plugins) when adding more subnets. If the timeout setting is exceeded, the scan is cancelled to prevent application hanging from rogue plugins. Check [debugging plugins](/docs/DEBUG_PLUGINS.md) for more tips.
+`ARPSCAN` can scan multiple networks if the network allows it. To scan networks directly, the subnets must be accessible from the network where NetAlertX is running. This means NetAlertX needs to have access to the interface attached to that subnet. 
 
-## Examples
+> [!WARNING] 
+> If you don't see all expected devices run the following command in the NetAlertX container (replace the interface and ip mask):
+> `sudo arp-scan --interface=eth0 192.168.1.0/24`
+> 
+>  If this command returns no results, the network is not accessible due to your network or firewall restrictions (Wi-Fi Extenders, VPNs and inaccessible networks). If direct scans are not possible, check the [remote networks documentation](./REMOTE_NETWORKS.md) for workarounds. 
+
+
+## Example Values
 
 > [!NOTE] 
-> Please use the UI to configure settings as that ensures that the config file is in the correct format. Edit `app.conf` directly only when really necessary.
-> ![settings](/docs/img/SUBNETS/subnets-setting-location.png)
+> Please use the UI to configure settings as it ensures the config file is in the correct format. Edit `app.conf` directly only when really necessary.  
+> ![Settings location](./img/SUBNETS/subnets-setting-location.png)
 
-* Examples for one and two subnets  (❗ Note the `['...','...']` format):
-   * One subnet:   `SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0']`
-   * Two subnets:  `SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0','192.168.1.0/24 --interface=eth1 -vlan=107']` 
+* **Examples for one and two subnets:**
+  * One subnet: `SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0']`
+  * Two subnets: `SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0','192.168.1.0/24 --interface=eth1 --vlan=107']`
 
-If you get timeout messages, decrease the network mask (e.g.: from a `/16` to `/24`) or increase the `TIMEOUT` setting (e.g.: `ARPSCAN_RUN_TIMEOUT` to `300` (a timeout of 5min)) for the plugin and the interval between scans (e.g.: `ARPSCAN_RUN_SCHD` to `*/10 * * * *` (scans every 10 min)). 
+> [!TIP]  
+> When adding more subnets, you may need to increase both the scan interval (`ARPSCAN_RUN_SCHD`) and the timeout (`ARPSCAN_RUN_TIMEOUT`)—as well as similar settings for related plugins.  
+>  
+> If the timeout is too short, you may see timeout errors in the log. To prevent the application from hanging due to unresponsive plugins, scans are canceled when they exceed the timeout limit.  
+>  
+> To fix this:  
+> - Reduce the subnet size (e.g., change `/16` to `/24`).  
+> - Increase the timeout (e.g., set `ARPSCAN_RUN_TIMEOUT` to `300` for a 5-minute timeout).  
+> - Extend the scan interval (e.g., set `ARPSCAN_RUN_SCHD` to `*/10 * * * *` to scan every 10 minutes).  
+>  
+> For more troubleshooting tips, see [Debugging Plugins](./DEBUG_PLUGINS.md).
+
+---
 
 ## Explanation
 
-### Network mask
+### Network Mask
 
-**Example value: `192.168.1.0/24`**
+**Example value:** `192.168.1.0/24`
 
-The arp-scan time itself depends on the number of IP addresses to check. 
+The `arp-scan` time itself depends on the number of IP addresses to check.
 
-> The number of IPs to check depends on the [network mask](https://www.calculator.net/ip-subnet-calculator.html) you set on the `SCAN_SUBNETS` setting. 
-> For example, a `/24` mask results in 256 IPs to check, whereas a `/16` mask checks around 65,536. Every IP takes a couple of seconds. This means that with an incorrect configuration, the arp-scan will take hours to complete instead of seconds.
+> The number of IPs to check depends on the [network mask](https://www.calculator.net/ip-subnet-calculator.html) you set in the `SCAN_SUBNETS` setting.  
+> For example, a `/24` mask results in 256 IPs to check, whereas a `/16` mask checks around 65,536 IPs. Each IP takes a couple of seconds, so an incorrect configuration could make `arp-scan` take hours instead of seconds.
 
-Specify the network filter (which **significantly** speeds up the scan process). For example, the filter `192.168.1.0/24` covers IP ranges `192.168.1.0` to `192.168.1.255`.
+Specify the network filter, which **significantly** speeds up the scan process. For example, the filter `192.168.1.0/24` covers IP ranges from `192.168.1.0` to `192.168.1.255`.
 
-### Network interface (adapter)
+### Network Interface (Adapter)
 
-**Example value: `--interface=eth0`**
+**Example value:** `--interface=eth0`
 
-The adapter will probably be `eth0` or `eth1`. (Check `System info` > `Network Hardware` or run `iwconfig` in the container to find your interface name(s)) 
+The adapter will probably be `eth0` or `eth1`. (Check `System Info` > `Network Hardware`, or run `iwconfig` in the container to find your interface name(s)).
 
-![Network hardware](/docs/img/SUBNETS/system_info-network_hardware.png)
+![Network hardware](./img/SUBNETS/system_info-network_hardware.png)
 
-> [!TIP]
-> Alterantive to `iwconfig` run `ip -o link show | awk -F': ' '!/lo|vir|docker/ {print $2}'` in your container to find your interface name(s) (e.g.: `eth0`, `eth1`).
+> [!TIP]  
+> As an alternative to `iwconfig`, run `ip -o link show | awk -F': ' '!/lo|vir|docker/ {print $2}'` in your container to find your interface name(s) (e.g.: `eth0`, `eth1`):
+> ```bash
+> Synology-NAS:/# ip -o link show | awk -F': ' '!/lo|vir|docker/ {print $2}'
+> sit0@NONE
+> eth1
+> eth0
+> ```
 
 ### VLANs
 
-**Example value: `-vlan=107`**
+**Example value:** `--vlan=107`
 
-- Append e.g.: ` -vlan=107` to the interface field (e.g.: `eth0 -vlan=107`) for multiple vlans. More details in this [comment in this issue](https://github.com/jokob-sk/NetAlertX/issues/170#issuecomment-1419902988)
+- Append `--vlan=107` to the `SCAN_SUBNETS` field (e.g.: `192.168.1.0/24 --interface=vmbr0 --vlan=107`) for multiple VLANs.
+
+#### VLANs on a Hyper-V Setup
+
+> Community-sourced content by [mscreations](https://github.com/mscreations) from this [discussion](https://github.com/jokob-sk/NetAlertX/discussions/404).
+
+**Tested Setup:** Bare Metal → Hyper-V on Win Server 2019 → Ubuntu 22.04 VM → Docker → NetAlertX.
+
+**Approach 1 (may cause issues):**  
+Configure multiple network adapters in Hyper-V with distinct VLANs connected to each one using Hyper-V's network setup. However, this action can potentially lead to the Docker host's inability to handle network traffic correctly. This might interfere with other applications such as Authentik.
+
+**Approach 2 (working example):**
+
+Network connections to switches are configured as trunk and allow all VLANs access to the server.
+
+By default, Hyper-V only allows untagged packets through to the VM interface, blocking VLAN-tagged packets. To fix this, follow these steps:
+
+1. Run the following command in PowerShell on the Hyper-V machine:
+
+   ```powershell
+   Set-VMNetworkAdapterVlan -VMName <Docker VM Name> -Trunk -NativeVlanId 0 -AllowedVlanIdList "<comma separated list of vlans>"
+   ```
 
 
-#### VLANs on a Hyper-V setup
+2. Within the VM, set up sub-interfaces for each VLAN to enable scanning. On Ubuntu 22.04, Netplan can be used. In /etc/netplan/00-installer-config.yaml, add VLAN definitions:
 
-> Community sourced content by [mscreations](https://github.com/mscreations) from this [discussion](https://github.com/jokob-sk/NetAlertX/discussions/404).
+  ```yaml
+      network:
+        ethernets:
+          eth0:
+            dhcp4: yes
+        vlans:
+          eth0.2:
+            id: 2
+            link: eth0
+            addresses: [ "192.168.2.2/24" ]
+            routes:
+              - to: 192.168.2.0/24
+                via: 192.168.1.1
+  ```
 
-> [!NOTE] 
-> The setup this was tested on: Bare Metal -> Hyper-V on Win Server 2019 -> Ubuntu 22.04 VM -> Docker -> NetAlertX. 
+3. Run `sudo netplan apply` to activate the interfaces for scanning in NetAlertX.
 
-**Approach 1 (may cause issues):**
+In this case, use `192.168.2.0/24 --interface=eth0.2` in NetAlertX.
 
-Configure multiple network adapters in Hyper-V with distinct VLANs connected to each one using Hyper-V's network setup. However, this action can potentially lead to the Docker host's inability to handle network traffic correctly. The issue may stem from the creation of routes for network time servers or domain controllers on every interface, thereby preventing proper synchronization of the underlying Ubuntu VM. This interference can affect the performance of other applications such as Authentik.
+#### VLAN Support & Exceptions
 
-**Approach 2 (working example)**
-
-Network connections to switches are configured as trunk and allow all VLANs access to the server. 
-
-By default Hyper-V only allows untagged packets through to the VM interface and no VLAN tagged packets get through. In order to fix this follow these steps:
-
-1) Run the following command in Powershell on the Hyper-V machine: 
-
-```shell
-Set-VMNetworkAdapterVlan -VMName <Docker VM Name> -Trunk -NativeVlanId 0 -AllowedVlanIdList "<comma separated list of vlans>"
-```
-
-(There might be other ways how adjust this.)
-
-2) Within the VM, set up sub-interfaces for each of the VLANs so they can be scanned. On Ubuntu 22.04 Netplan can be used.
-
-In /etc/netplan/00-installer-config.yaml, add vlan definitions:
-
-```
-network:
-  ethernets:
-    eth0:
-      dhcp4: yes
-  vlans:
-    eth0.2:
-      id: 2
-      link: eth0
-      addresses: [ "192.168.2.2/24" ]
-      routes:
-        - to: 192.168.2.0/24
-          via: 192.168.1.1 
-```
-
-3) Run `sudo netplan apply` and the interfaces are then available to scan in NetAlertX. 
-4) In this case, use `192.168.2.0/24 --interface=eth0.2` in NetAlertX
-
-#### VLAN 🔍Example:
-
-![Vlan configuration example](/docs/img/SUBNETS/subnets_vlan.png)
-
-#### Support for VLANS (& exceptions)
-
-Please note the accessibility of the macvlans when they are configured on the same computer. My understanding this is a general networking behavior, but feel free to clarify via a PR/issue.
+Please note the accessibility of macvlans when configured on the same computer. This is a general networking behavior, but feel free to clarify via a PR/issue.
 
 - NetAlertX does not detect the macvlan container when it is running on the same computer.
 - NetAlertX recognizes the macvlan container when it is running on a different computer.

docs/SYNOLOGY_GUIDE.md

@@ -0,0 +1,74 @@
+# Installation on a Synology NAS
+
+There are different ways to install NetAlertX on a Synology, including SSH-ing into the machine and using the command line. For this guide, we will use the Project option in Container manager. 
+
+## Create the folder structure
+
+The folders you are creating below will contain the configuration and the database. Back them up regularly. 
+
+1. Create a parent folder named `netalertx`
+2. Create a `db` sub-folder
+
+![Folder structure](./img/SYNOLOGY/01_Create_folder_structure.png)
+![Folder structure](./img/SYNOLOGY/02_Create_folder_structure_db.png)
+![Folder structure](./img/SYNOLOGY/03_Create_folder_structure_db.png)
+
+3. Create a `config` sub-folder
+
+![Folder structure](./img/SYNOLOGY/04_Create_folder_structure_config.png)
+
+4. Note down the folders Locations:
+
+![Getting the location](./img/SYNOLOGY/05_Access_folder_properties.png)
+![Getting the location](./img/SYNOLOGY/06_Note_location.png)
+
+5. Open **Container manager** -> **Project** and click **Create**.
+6. Fill in the details:
+
+- Project name: `netalertx`
+- Path: `/app_storage/netalertx` (will differ from yours)
+- Paste in the following template:
+
+```yaml
+version: "3"
+services:
+  netalertx:
+    container_name: netalertx
+    # use the below line if you want to test the latest dev image
+    # image: "ghcr.io/jokob-sk/netalertx-dev:latest" 
+    image: "ghcr.io/jokob-sk/netalertx:latest"      
+    network_mode: "host"        
+    restart: unless-stopped
+    volumes:
+      - local/path/config:/app/config
+      - local/path/db:/app/db      
+      # (optional) useful for debugging if you have issues setting up the container
+      - local/path/logs:/app/log
+    environment:
+      - TZ=Europe/Berlin      
+      - PORT=20211
+```
+
+![Project settings](./img/SYNOLOGY/07_Create_project.png)
+
+7. Replace the paths to your volume and comment out unnecessary line(s):
+
+- This is only an example, your paths will differ.
+
+```yaml
+ volumes:
+      - /volume1/app_storage/netalertx/config:/app/config
+      - /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)
+
+8. (optional) Change the port number from `20211` to an unused port if this port is already used.
+9. Build the project:
+
+![Build](./img/SYNOLOGY/09_Run_and_build.png)
+
+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. 

docs/UPDATES.md

@@ -0,0 +1,116 @@
+# Docker Update Strategies to upgrade NetAlertX
+
+> [!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. Alternatovelly, devices and settings can be migrated manually, e.g. via [CSV import](./DEVICES_BULK_EDITING.md).
+
+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:
+
+- Manual: Direct commands to stop, remove, and rebuild containers.
+- Dockcheck: Semi-automated with more control, suited for bulk updates.
+- Watchtower: Fully automated, runs continuously to check and update containers.
+
+You can choose any approach that fits your workflow.
+
+> In the examples I assume that the container name is `netalertx` and the image name is `netalertx` as well.
+
+> [!NOTE]
+> See also [Backup strategies](./BACKUPS.md) to be on the safe side.  
+
+## 1. Manual Updates
+
+Use this method when you need precise control over a single container or when dealing with a broken container that needs immediate attention.
+Example Commands
+
+To manually update the `netalertx` container, stop it, delete it, remove the old image, and start a fresh one with `docker-compose`.
+
+```bash
+# Stop the container
+sudo docker container stop netalertx
+
+# Remove the container
+sudo docker container rm netalertx
+
+# Remove the old image
+sudo docker image rm netalertx
+
+# Pull and start a new container
+sudo docker-compose up -d
+```
+
+### Alternative: Force Pull with Docker Compose
+
+You can also use `--pull always` to ensure Docker pulls the latest image before starting the container:
+
+```bash
+sudo docker-compose up --pull always -d
+```
+
+## 2. Dockcheck for Bulk Container Updates
+
+Always check the [Dockcheck](https://github.com/mag37/dockcheck) docs if encountering issues with the guide below. 
+
+Dockcheck is a useful tool if you have multiple containers to update and some flexibility for handling potential issues that might arise during mass updates. Dockcheck allows you to inspect each container and decide when to update.
+
+### Example Workflow with Dockcheck
+
+You might use Dockcheck to:
+
+- Inspect container versions.
+- Pull the latest images in bulk.
+- Apply updates selectively.
+
+Dockcheck can help streamline bulk updates, especially if you’re managing multiple containers.
+
+Below is a script I use to run an update of the Dockcheck script and start a check for new containers:
+
+```bash
+cd /path/to/Docker &&
+rm dockcheck.sh &&
+wget https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh &&
+sudo chmod +x dockcheck.sh &&
+sudo ./dockcheck.sh
+```
+
+## 3. Automated Updates with Watchtower
+
+Always check the [watchtower](https://github.com/containrrr/watchtower) docs if encountering issues with the guide below. 
+
+Watchtower monitors your Docker containers and automatically updates them when new images are available. This is ideal for ongoing updates without manual intervention.
+
+### Setting Up Watchtower
+
+#### 1. Pull the Watchtower Image:
+
+```bash
+docker pull containrrr/watchtower
+```
+
+#### 2. Run Watchtower to update all images:
+
+```bash
+docker run -d \
+  --name watchtower \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  containrrr/watchtower \
+  --interval 300 # Check for updates every 5 minutes
+```
+
+#### 3. Run Watchtower to update only NetAlertX: 
+
+You can specify which containers to monitor by listing them. For example, to monitor netalertx only:
+
+```bash
+docker run -d \
+  --name watchtower \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  containrrr/watchtower netalertx
+
+```
+
+## Summary
+
+- Manual: Ideal for individual or critical updates.
+- Dockcheck: Suitable for controlled, mass updates.
+- Watchtower: Fully automated, best for continuous deployment setups.
+
+These approaches allow you to maintain flexibility in how you update Docker containers, depending on the urgency and scale of the update.

docs/VERSIONS.md

@@ -8,18 +8,18 @@ If you are not on the latest version, the app will notify you, that a new releas
 
 If any notification occurs and an email is sent, the email will contain a note that a new version is available. See the sample email below:
 
-![Sample email if a new version is available](/docs/img/VERSIONS/new-version-available-email.png)
+![Sample email if a new version is available](./img/VERSIONS/new-version-available-email.png)
 
 ### 🆕 In the UI
 
 In the UI via a notification Icon and via a custom message in the Maintenance section.
 
-![UI screenshot if a new version is available](/docs/img/VERSIONS/new-version-available-maintenance.png)
+![UI screenshot if a new version is available](./img/VERSIONS/new-version-available-maintenance.png)
 
 For a comparison, this is how the UI looks like if you are on the latest stable image:
 
-![UI screenshot if on latest version](/docs/img/VERSIONS/latest-version-maintenance.png)
+![UI screenshot if on latest version](./img/VERSIONS/latest-version-maintenance.png)
 
 ## Implementation details
 
-During build a [/app/front/buildtimestamp.txt](https://github.com/jokob-sk/NetAlertX/blob/092797e75ccfa8359444ad149e727358ac4da05f/Dockerfile#L44) file is created. The app then periodically checks if a new release is available with a newer timestamp in GitHub's rest-based JSON endpoint (check the `def isNewVersion():` method for details).   
+During build a [/app/front/buildtimestamp.txt](https://github.com/jokob-sk/NetAlertX/blob/092797e75ccfa8359444ad149e727358ac4da05f/Dockerfile#L44) file is created. The app then periodically checks if a new release is available with a newer timestamp in GitHub's rest-based JSON endpoint (check the `def isNewVersion:` method for details).   

docs/VERSIONS_HISTORY.md

@@ -1,87 +0,0 @@
-# Pi.Alert Version History
-<!--- --------------------------------------------------------------------- --->
-
-  | Version | Description                                                     |
-  | ------- | --------------------------------------------------------------- |
-  |  v3.00  | Major set of New features & Enhancements                        |
-  |  v2.70  | New features & Usability improvements in the web prontal        |
-  |  v2.61  | Bug fixing                                                      |
-  |  v2.60  | Improved the compability of installation process (Ubuntu)       |
-  |  v2.56  | Bug fixing                                                      |
-  |  v2.55  | Bug fixing                                                      |
-  |  v2.52  | Bug fixing                                                      |
-  |  v2.51  | Bug fixing                                                      |
-  |  v2.50  | First public release                                            |
-
-
-# 🆕 2022+ [Newest Release notes](https://github.com/jokob-sk/NetAlertX/issues/138)
-
-## Pi.Alert v3.02
-<!--- --------------------------------------------------------------------- --->
- **PENDING UPDATE DOC**
-  - Fixed: UNIQUE constraint failed with Local MAC #114
-
-
-## Pi.Alert v3.01
-<!--- --------------------------------------------------------------------- --->
- **PENDING UPDATE DOC**
-  - Fixed: Problem with local MAC & IP (raspberry) #106
- 
-
-## Pi.Alert v3.00
-<!--- --------------------------------------------------------------------- --->
- **PENDING UPDATE DOC**
-  - `arp-scan` config options: interface, several subnets. #101 #15
-  - Next/previos button while editing devices #66 #37
-  - Internet presence/sessions monitoring #63
-  - Logical delete / archive / hide Device #93
-  - Flag to mark device with random MAC's #87
-  - New Device Types predefined in combobox #92
-  - Ask before leave the page with unsaved changes #104
-  - Option to don't mark devices as new during installation #94
-  - Uninstall script #62
-  - Fixed: Error updating name of devices w/o IP #97
-  - Fixed: Deleted devices reappear #84
-  - Fixed: Device running Pi.Alert must be marked as "on-line" #76
-  - Fixed: Incorrect calculation of presence hours #102
-  - Fixed: Problem redirect to homepage clicking in logo #103
-
-
-## Pi.Alert v2.70
-<!--- --------------------------------------------------------------------- --->
-  - Added Client names resolution #43
-  - Added Check to mark devices as "known" #16
-  - Remember "Show XXX entries" dropdown value #16 #26
-  - Remember "sorting" in devices #16
-  - Remember "Device panel " in device detail #16
-  - Added "All" option to "Show x Entries" option #16
-  - Added optional Location field (Door, Basement, etc.) to devices #16
-  - "Device updated successfully" message now is not modal #16
-  - Now is possible to delete Devices #16
-  - Added Device Type Singleboard Computer (SBC) #16
-  - Allowed to use " in device name #42
-
-
-## Pi.Alert v2.60
-<!--- --------------------------------------------------------------------- --->
-  - `pialert.conf` moved from `back` to `config` folder
-  - `pialert.conf` splitted in two files: `pialert.conf` and `version.conf`
-  - Added compatibility with Python 3 (default version installed with Ubuntu)
-  - Added compatibility in the Installation guide with Ubuntu server
-  - Eliminated some unnecessary packages from the installation
-  
-
-
-### License
-  GPL 3.0
-  [Read more here](../LICENSE.txt)
-
-### Contact
-  Always use the Issue tracker for the correct fork, for example: 
-  
-  [jokob-sk/NetAlertX](https://github.com/jokob-sk/NetAlertX/issues). Please also follow the guidelines on:
-
-  - ➕ [Pull Request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs) 
-  - 🙏 [Feature request guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-feature-requests) 
-  - 🐛 [Issue guidelines](https://github.com/jokob-sk/NetAlertX/tree/main/docs#-submitting-an-issue-or-bug)
-

docs/WEBHOOK_N8N.md

@@ -1,12 +1,15 @@
 ### Create a simple n8n workflow
 
+> [!NOTE]
+> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.  
+
 N8N can be used for more advanced conditional notification use cases. For example, you want only to get notified if two out of a specified list of devices is down. Or you can use other plugins to process the notifiations further. The below is a simple example of sending an email on a webhook.  
 
-![n8n workflow](/docs/img/WEBHOOK_N8N/n8n_workflow.png)
+![n8n workflow](./img/WEBHOOK_N8N/n8n_workflow.png)
 
 ### Specify your email template 
 See [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json) if you want to see the JSON paths used in the email template below
-![Email template](/docs/img/WEBHOOK_N8N/n8n_send_email_settings.png)
+![Email template](./img/WEBHOOK_N8N/n8n_send_email_settings.png)
 
 ```
 Events count: {{ $json["body"]["attachments"][0]["text"]["events"].length }}
@@ -14,7 +17,7 @@ New devices count: {{ $json["body"]["attachments"][0]["text"]["new_devices"].len
 ```
 
 ### Get your webhook in n8n
-![n8n webhook URL](/docs/img/WEBHOOK_N8N/n8n_webhook_settings.png)
+![n8n webhook URL](./img/WEBHOOK_N8N/n8n_webhook_settings.png)
 
 ### Configure NetAlertX to point to the above URL
-![NetAlertX config](/docs/img/WEBHOOK_N8N/Webhook_settings.png)
+![NetAlertX config](./img/WEBHOOK_N8N/Webhook_settings.png)

docs/WEBHOOK_SECRET.md

@@ -1,5 +1,8 @@
 # Webhook Secrets
 
+> [!NOTE]
+> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.  
+
 ## How does the signing work?
 
 NetAlertX will use the configured secret to create a hash signature of the request body. This SHA256-HMAC signature will appear in the `X-Webhook-Signature` header of each request to the webhook target URL. You can use the value of this header to validate the request was sent by NetAlertX.

docs/WEB_UI_PORT_DEBUG.md

@@ -1,51 +1,72 @@
 # Debugging inaccessible UI
 
-## 1. Port conflicts
+The application uses the following default ports:
 
-When opening an issue please:
+- **Web UI**: `20211`  
+- **GraphQL API**: `20212`
+
+The **Web UI** is served by an **nginx** server, while the **API backend** runs on a **Flask (Python)** server.
+
+## Changing Ports
+
+- To change the **Web UI** port, update the `PORT` environment variable in the `docker-compose.yml` file.
+- To change the **GraphQL API** port, use the `GRAPHQL_PORT` setting, either directly or via Docker:
+  ```yaml
+  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).
+
+## Possible issues and troubleshooting
+
+Follow all of the below in order to disqualify potential causes of issues and to troubleshoot these problems faster.
+
+### 1. Port conflicts
+
+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. [Follow steps 1, 2, 3, 4  on this page](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md) 
+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:
-   1. `sudo apk add lsof`
-   1. `sudo lsof -i`
-1. Try running the `nginx` command in the container
-   1. if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number
+   - `sudo apk add lsof`
+   - `sudo lsof -i`
+1. Try running the `nginx` command in the container:
+   - if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number
 
 
-![lsof ports](/docs/img/WEB_UI_PORT_DEBUG/container_port.png)
+![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png)
 
-## 2. JavaScript issues 
+### 2. JavaScript issues 
 
 Check for browser console (F12 browser dev console) errors + check different browsers.
 
-## 3. Clear the app cache and cached JavaScript files
+### 3. Clear the app cache and cached JavaScript files
 
 Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. 
 
-## 4. Disable proxy
+### 4. Disable proxies
 
 If you have any reverse proxy or similar, try disabling it. 
 
-## 5. Disable your firewall
+### 5. Disable your firewall
 
 If you are using a firewall, try to temporarily disabling it. 
 
-## 6. Post your docker start details
+### 6. Post your docker start details
 
 If you haven't, post your docker compose/run command.
 
-## 7. Check for errors in your PHP/NGINX error logs
+### 7. Check for errors in your PHP/NGINX error logs
 
-In the container execute:
+In the container execute and investigate:
 
 `cat /var/log/nginx/error.log`
 
-`cat /app/front/log/app.php_errors.log`
+`cat /app/log/app.php_errors.log`
 
-## 8. Make sure permissions are correct
+### 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. 
 
-Please read the [Permissions troubleshooting guide](/docs/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 `/app/db` and `app/config` directories. 

docs/WORKFLOWS.md

@@ -0,0 +1,130 @@
+# Workflows Overview
+
+The workflows module in allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
+
+![Workflows diagram](./img/WORKFLOWS/workflows_diagram.png)
+
+Below are a few examples that demonstrate how this module can be used to simplify network management tasks.
+
+## Updating Workflows
+
+> [!NOTE] 
+> In order to apply a workflow change, you must first **Save** the changes and then reload the application by clicking **Restart server**.
+
+## Workflow components
+
+### Triggers
+
+![Trigger example](./img/WORKFLOWS/trigger.jpg)
+
+Triggers define the event that activates a workflow. They monitor changes to objects within the system, such as updates to devices or the insertion of new entries. When the specified event occurs, the workflow is executed.
+
+> [!TIP]
+> Workflows not running? Check the [Workflows debugging](./WORKFLOWS_DEBUGGING.md) guide how to troubleshoot triggers and conditions.
+
+#### Example Trigger:
+- **Object Type**: `Devices`
+- **Event Type**: `update`
+  
+This trigger will activate when a `Device` object is updated.
+
+### Conditions
+
+![Conditions example](./img/WORKFLOWS/conditions.png)
+
+Conditions determine whether a workflow should proceed based on certain criteria. These criteria can be set for specific fields, such as whether a device is from a certain vendor, or whether it is new or archived. You can combine conditions using logical operators (`AND`, `OR`).
+
+> [!TIP]
+> To better understand how to use specific Device fields, please read through the [Database overview](./DATABASE.md) guide.
+
+#### Example Condition:
+- **Logic**: `AND`
+  - **Field**: `devVendor`
+  - **Operator**: `contains` (case in-sensitive)
+  - **Value**: `Google`
+  
+  This condition checks if the device's vendor is `Google`. The workflow will only proceed if the condition is true.
+
+### Actions
+
+![Actions example](./img/WORKFLOWS/actions.jpg)
+
+Actions define the tasks that the workflow will perform once the conditions are met. Actions can include updating fields or deleting devices.
+
+You can include multiple actions that should execute once the conditions are met.
+
+#### Example Action:
+- **Action Type**: `update_field`
+  - **Field**: `devIsNew`
+  - **Value**: `0`
+  
+  This action updates the `devIsNew` field to `0`, marking the device as no longer new.
+
+
+# Examples
+
+Below you can find a couple of configuration examples.
+
+![Workflow example](./img/WORKFLOWS/workflows.png)
+
+---
+
+## Example 1: Assign Device to Network Node Based on IP
+
+This workflow assigns newly added devices with IP addresses in the `192.168.1.*` range to the device with the MAC address `6c:6d:6d:6c:6c:6c`.
+
+### Trigger:
+- **Object Type**: `Devices`
+- **Event Type**: `insert`
+
+### Conditions:
+- **Logic**: `AND`
+  - `Field`: `devLastIP`
+  - `Operator`: `contains`
+  - `Value`: `192.168.1.`
+  
+  This condition ensures that the workflow only applies to devices with an IP address in the `192.168.1.*` range.
+
+### Actions:
+- **Action Type**: `update_field`
+  - **Field**: `devNetworkNode`
+  - **Value**: `6c:6d:6d:6c:6c:6c`
+
+---
+
+## Example 2: Mark Device as Not New and Delete If from Google Vendor
+
+This workflow automates the process of marking Google devices as not new and deleting them if they meet the criteria.
+
+### Trigger:
+- **Object Type**: `Devices`
+- **Event Type**: `update`
+
+### Conditions:
+- **Logic**: `AND`
+  - `Field`: `devVendor`
+  - `Operator`: `contains`
+  - `Value`: `Google`
+  
+  This condition checks if the device's vendor is `Google`.
+
+- **Logic**: `AND`
+  - `Field`: `devIsNew`
+  - `Operator`: `equals`
+  - `Value`: `1`
+  
+  This ensures the workflow applies only to new devices.
+
+### Actions:
+1. **Action Type**: `update_field`
+   - **Field**: `devIsNew`
+   - **Value**: `0`
+
+   This action marks the device as no longer new.
+
+2. **Action Type**: `delete_device`
+   
+   This action deletes the device after it is marked as not new.
+
+> [!TIP]
+> Share your workflows in [Discord](https://discord.com/invite/NczTUTWyRr) or [GitHub Discussions](https://github.com/jokob-sk/NetAlertX/discussions).  

docs/WORKFLOWS_DEBUGGING.md

@@ -0,0 +1,38 @@
+# Workflows debugging and troubleshooting
+
+> [!TIP]
+> Before troubleshooting, please ensure you have [Debugging enabled](./DEBUG_TIPS.md).
+
+Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application. 
+
+## Troubleshooting triggers
+
+> [!NOTE]
+> Workflow events are processed once every 5 seconds. However, if a scan or other background tasks are running, this can cause a delay up to a few minutes. 
+
+If an event doesn't trigger a workflow as expected, check the _App Events_ section for the event. You can filter these by the ID of the device (`devMAC` or `devGUID`). 
+
+![App events search](./img/WORKFLOWS/workflows_app_events_search.png)
+
+Once you find the _Event Guid_ and _Object GUID_, use them to find relevant debug entries. 
+
+Navigate to _Mainetenace -> Logs_ where you can filter the logs based on the _Event or Object GUID_. 
+
+![Log events search](./img/WORKFLOWS/workflows_logs_search.png)
+
+Below you can find some example `app.log` entries that will help you understand why a Workflow was or was not triggered.
+
+```bash
+16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Sample Device Update Workflow'
+16:27:03 [WF] self.triggered 'False' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "insert"}' 
+16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Location Change'
+16:27:03 [WF] self.triggered 'True' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "update"}' 
+16:27:03 [WF] Event with GUID '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggered the workflow 'Location Change'
+```
+
+Note how one trigger executed, but the other didn't based on different `"event_type"` values. One is `"event_type": "insert"`, the other `"event_type": "update"`.
+
+Given the Event is a update event (note `...['online'], ['update'], [None]...` in the event structure), the `"event_type": "insert"` trigger didn't execute.
+
+
+

docs/WORKFLOW_EXAMPLES.md

@@ -0,0 +1,60 @@
+# Workflow examples
+
+Workflows in NetAlertX automate actions based on real-time events and conditions. Below are practical examples that demonstrate how to build automation using triggers, conditions, and actions.
+
+## Un-archive devices if detected online
+
+This workflow automatically unarchives a device if it was previously archived but has now been detected as online.
+
+### 📋 Use Case
+
+Sometimes devices are manually archived (e.g., no longer expected on the network), but they reappear unexpectedly. This workflow reverses the archive status when such devices are detected during a scan.
+
+### ⚙️ Workflow Configuration
+
+```json
+{
+  "name": "Un-archive devices if detected online",
+  "trigger": {
+    "object_type": "Devices",
+    "event_type": "update"
+  },
+  "conditions": [
+    {
+      "logic": "AND",
+      "conditions": [
+        {
+          "field": "devIsArchived",
+          "operator": "equals",
+          "value": "1"
+        },
+        {
+          "field": "devPresentLastScan",
+          "operator": "equals",
+          "value": "1"
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "type": "update_field",
+      "field": "devIsArchived",
+      "value": "0"
+    }
+  ],
+  "enabled": "Yes"
+}
+```
+
+### 🔍 Explanation
+
+    - Trigger: Listens for updates to device records.
+    - Conditions:
+        - `devIsArchived` is `1` (archived).
+        - `devPresentLastScan` is `1` (device was detected in the latest scan).
+    - Action: Updates the device to set `devIsArchived` to `0` (unarchived).
+
+### ✅ Result
+
+Whenever a previously archived device shows up during a network scan, it will be automatically unarchived — allowing it to reappear in your device lists and dashboards.