From 00e953a7ce06d76768bf76998d2ae5f02051089f Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 09:52:12 +1100 Subject: [PATCH] DOCS: cleanup Signed-off-by: jokob-sk --- docs/COMMON_ISSUES.md | 120 +++++++++++++++++++++++++----------- docs/DEBUG_PLUGINS.md | 13 ++-- docs/DEBUG_TIPS.md | 12 +--- docs/FILE_PERMISSIONS.md | 19 ++++-- docs/WORKFLOWS_DEBUGGING.md | 16 ++--- mkdocs.yml | 14 ++--- 6 files changed, 124 insertions(+), 70 deletions(-) diff --git a/docs/COMMON_ISSUES.md b/docs/COMMON_ISSUES.md index d97e9954..4d196319 100755 --- a/docs/COMMON_ISSUES.md +++ b/docs/COMMON_ISSUES.md @@ -1,66 +1,114 @@ -### Loading... +# Troubleshooting Common Issues -Often if the application is misconfigured the `Loading...` dialog is continuously displayed. This is most likely caused by the backed failing to start. The **Maintenance -> Logs** section should give you more details on what's happening. If there is no exception, check the Portainer log, or start the container in the foreground (without the `-d` parameter) to observe any exceptions. It's advisable to enable `trace` or `debug`. Check the [Debug tips](./DEBUG_TIPS.md) on detailed instructions. +> [!TIP] +> Before troubleshooting, ensure you have set the correct [Debugging and LOG_LEVEL](./DEBUG_TIPS.md). -The issue might be related to the backend server, so please check [Debugging GraphQL issues](./DEBUG_API_SERVER.md). +--- -Please also check the browser logs (usually accessible by pressing `F12`): +## Docker Container Doesn't Start -1. Switch to the Console tab and refresh the page -2. Switch to teh Network tab and refresh the page - -If you are not sure how to resolve the errors yourself, please post screenshots of the above into the issue, or discord discussion, where your problem is being solved. - -### 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. +Initial setup issues are often caused by **missing permissions** or **incorrectly mapped volumes**. Always double-check your `docker run` or `docker-compose.yml` against the [official setup guide](./DOCKER_INSTALLATION.md) before proceeding. ### Permissions -Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly. +Make sure your [file permissions](./FILE_PERMISSIONS.md) are correctly set: -* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/tmp/log`. -* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /data/db/app.db`. -* If still facing issues, try to map the app.db file (⚠ not folder) to `:/data/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details) +* If you encounter AJAX errors, cannot write to the database, or see an empty screen, check that permissions are correct and review the logs under `/tmp/log`. +* To fix permission issues with the database, update the owner and group of `app.db` as described in the [File Permissions guide](./FILE_PERMISSIONS.md). -### Container restarts / crashes +### Container Restarts / Crashes -* Check the logs for details. Often a required setting for a notification method is missing. +* Check the logs for details. Often, required settings are missing. +* For more detailed troubleshooting, see [Debug and Troubleshooting Tips](./DEBUG_TIPS.md). +* To observe errors directly, run the container in the foreground instead of `-d`: -### unable to resolve host +```bash +docker run --rm -it +``` -* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See the [subnets docs for details](./SUBNETS.md). +--- -### Invalid JSON +## Docker Container Starts, But the Application Misbehaves -Check the [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) docs on how to proceed. +If the container starts but the app shows unexpected behavior, the cause is often **data corruption**, **incorrect configuration**, or **unexpected input data**. -### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 +### Continuous "Loading..." Screen -> sudo: unexpected child termination condition: 0 +A misconfigured application may display a persistent `Loading...` dialog. This is usually caused by the backend failing to start. -Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581) +**Steps to troubleshoot:** + +1. Check **Maintenance → Logs** for exceptions. +2. If no exception is visible, check the Portainer logs. +3. Start the container in the foreground to observe exceptions. +4. Enable `trace` or `debug` logging for detailed output (see [Debug Tips](./DEBUG_TIPS.md)). +5. Verify that `GRAPHQL_PORT` is correctly configured. +6. Check browser logs (press `F12`): + + * **Console tab** → refresh the page + * **Network tab** → refresh the page + +If you are unsure how to resolve errors, provide screenshots or log excerpts in your issue report or Discord discussion. + +--- + +### Common Configuration Issues + +#### Incorrect `SCAN_SUBNETS` + +If `SCAN_SUBNETS` is misconfigured, you may see only a few devices in your device list after a scan. See the [Subnets Documentation](./SUBNETS.md) for proper configuration. + +#### Duplicate Devices and Notifications + +* Devices are identified by their **MAC address**. +* If a device's MAC changes, it will be treated as a new device, triggering notifications. +* Prevent this by adjusting your device configuration for Android, iOS, or Windows. See the [Random MACs Guide](./RANDOM_MAC.md). + +#### Unable to Resolve Host + +* Ensure `SCAN_SUBNETS` uses the correct mask and `--interface`. +* Refer to the [Subnets Documentation](./SUBNETS.md) for detailed guidance. + +#### Invalid JSON Errors + +* Follow the steps in [Invalid JSON Errors Debug Help](./DEBUG_INVALID_JSON.md). + +#### Sudo Execution Fails (e.g., on arpscan on Raspberry Pi 4) + +Error: ``` +sudo: unexpected child termination condition: 0 +``` + +**Resolution**: + +```bash wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb ``` -The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url. +> ⚠️ The link may break over time. Check [Debian Packages](https://packages.debian.org/sid/armhf/libseccomp2/download) for the latest version. -### Only Router and own device show up +#### Only Router and Own Device Show Up -Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your device/NAS has multiple ethernet ports, you probably need to change `eth0` to something else. +* Verify the subnet and interface in `SCAN_SUBNETS`. +* On devices with multiple Ethernet ports, you may need to change `eth0` to the correct interface. -### Losing my settings and devices after an update +#### Losing Settings or Devices After Update -If you lose your devices and/or settings after an update that means you don't have the `/data/db` and `/data/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command. +* Ensure `/data/db` and `/data/config` are mapped to persistent storage. +* Without persistent volumes, these folders are recreated on every update. +* See [Docker Volumes Setup](./DOCKER_COMPOSE.md) for proper configuration. +#### Application Performance Issues -### The application is slow +Slowness can be caused by: + +* Incorrect settings (causing app restarts) → check `app.log`. +* Too many background processes → disable unnecessary scanners. +* Long scans → limit the number of scanned devices. +* Excessive disk operations or failing maintenance plugins. + +> See [Performance Tips](./PERFORMANCE.md) for detailed optimization steps. -Slowness is usually caused by incorrect settings (the app might restart, so check the `app.log`), too many background processes (disable unnecessary scanners), too long scans (limit the number of scanned devices), too many disk operations, or some maintenance plugins might have failed. See the [Performance tips](./PERFORMANCE.md) docs for details. \ No newline at end of file diff --git a/docs/DEBUG_PLUGINS.md b/docs/DEBUG_PLUGINS.md index 5df99769..e1a086c7 100755 --- a/docs/DEBUG_PLUGINS.md +++ b/docs/DEBUG_PLUGINS.md @@ -1,5 +1,8 @@ # Troubleshooting plugins +> [!TIP] +> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md). + ## High-level overview If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`). @@ -9,7 +12,7 @@ For a more in-depth overview on how plugins work check the [Plugins development ### Prerequisites - Make sure you read and followed the specific plugin setup instructions. -- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md) +- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md) ### Potential issues @@ -47,9 +50,9 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo 17:31:05 [Plugins] history_to_insert count: 4 17:31:05 [Plugins] objects_to_insert count: 0 17:31:05 [Plugins] objects_to_update count: 4 -17:31:05 [Plugin utils] In pluginEvents there are 2 events with the status "watched-not-changed" -17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan" -17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed" +17:31:05 [Plugin utils] In pluginEvents there are 2 events with the status "watched-not-changed" +17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan" +17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed" 17:31:05 [Plugins] Mapping objects to database table: CurrentScan 17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "cur_MAC", "cur_IP", "cur_LastQuery", "cur_Name", "cur_Vendor", "cur_ScanMethod") VALUES ( ?, ?, ?, ?, ?, ?) 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')] @@ -80,7 +83,7 @@ These values, if formatted correctly, will also show up in the UI: ### 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. +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. diff --git a/docs/DEBUG_TIPS.md b/docs/DEBUG_TIPS.md index 4362f32c..03c5d23e 100755 --- a/docs/DEBUG_TIPS.md +++ b/docs/DEBUG_TIPS.md @@ -55,15 +55,7 @@ services: ## 5. TMP mount directories to rule host out permission issues -Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. - -```bash -docker run --rm --network=host \ - -v /etc/localtime:/etc/localtime:ro \ - --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ - -e PORT=20211 \ - ghcr.io/jokob-sk/netalertx:latest -``` +Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. See teh [Permissions guide](./FILE_PERMISSIONS.md) for details. ## 6. Sharing application state @@ -79,4 +71,4 @@ Sometimes specific log sections are needed to debug issues. The Devices and Curr ## Common issues -See [Common issues](./COMMON_ISSUES.md) for details. +See [Common issues](./COMMON_ISSUES.md) for additional troubleshooting tips. diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index d634e516..0738d83b 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -1,8 +1,23 @@ # Managing File Permissions for NetAlertX on a Read-Only Container +Sometimes, permission issues arise if your existing host directories were created by a previous container running as root or another UID. The container will fail to start with "Permission Denied" errors. + > [!TIP] > NetAlertX runs in a **secure, read-only Alpine-based container** under a dedicated `netalertx` user (UID 20211, GID 20211). All writable paths are either mounted as **persistent volumes** or **`tmpfs` filesystems**. This ensures consistent file ownership and prevents privilege escalation. +Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. + +```bash +docker run --rm --network=host \ + -v /etc/localtime:/etc/localtime:ro \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ + -e PORT=20211 \ + ghcr.io/jokob-sk/netalertx:latest +``` + +> [!WARNING] +> The above should be only used as a test - once the container restarts, all data is lost. + --- ## Writable Paths @@ -25,10 +40,6 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b --- -## Fixing Permission Problems - -Sometimes, permission issues arise if your existing host directories were created by a previous container running as root or another UID. The container will fail to start with "Permission Denied" errors. - ### Solution 1. **Run the container once as root** (`--user "0"`) to allow it to correct permissions automatically: diff --git a/docs/WORKFLOWS_DEBUGGING.md b/docs/WORKFLOWS_DEBUGGING.md index 79eec5ba..29d83366 100755 --- a/docs/WORKFLOWS_DEBUGGING.md +++ b/docs/WORKFLOWS_DEBUGGING.md @@ -1,22 +1,22 @@ # Workflows debugging and troubleshooting > [!TIP] -> Before troubleshooting, please ensure you have [Debugging enabled](./DEBUG_TIPS.md). +> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md). -Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application. +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. +> 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`). +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. +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_. +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) @@ -24,9 +24,9 @@ Below you can find some example `app.log` entries that will help you understand ```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] 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] 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' ``` diff --git a/mkdocs.yml b/mkdocs.yml index 0f708c29..ee42eef7 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,13 +65,13 @@ nav: - Troubleshooting: - Common issues: COMMON_ISSUES.md - Inspecting Logs: LOGGING.md - - Debugging Tips: DEBUG_TIPS.md - - Debugging GraphQL: DEBUG_GRAPHQL.md - - Debugging Invalid JSON: DEBUG_INVALID_JSON.md - - Debugging PHP: DEBUG_PHP.md - - Debugging Plugins: DEBUG_PLUGINS.md - - Debugging Web UI Port: WEB_UI_PORT_DEBUG.md - - Debugging Workflows: WORKFLOWS_DEBUGGING.md + - General Tips: DEBUG_TIPS.md + - API Server Issues: DEBUG_API_SERVER.md + - Invalid JSON Issues: DEBUG_INVALID_JSON.md + - PHP Issues: DEBUG_PHP.md + - Plugin Issues: DEBUG_PLUGINS.md + - Web UI Port Issues: WEB_UI_PORT_DEBUG.md + - Workflows Issues: WORKFLOWS_DEBUGGING.md - Development: - Plugin and app development: - Environment Setup: DEV_ENV_SETUP.md