From a5aa3d550d7e0fa2cfc3bcc0c845d79bbde28df7 Mon Sep 17 00:00:00 2001 From: Jokob-sk Date: Sat, 8 Jul 2023 09:24:46 +1000 Subject: [PATCH] docs --- dockerfiles/README.md | 16 +--------------- docs/DEBUG_TIPS.md | 31 ++++++++++++++++++++++++++++++- docs/README.md | 3 ++- 3 files changed, 33 insertions(+), 17 deletions(-) diff --git a/dockerfiles/README.md b/dockerfiles/README.md index daf03607..3a62aea0 100755 --- a/dockerfiles/README.md +++ b/dockerfiles/README.md @@ -80,21 +80,7 @@ These are the most important settings to get at least some output in your Device πŸ’‘ Before creating a new issue, please check if a similar issue was [already resolved](https://github.com/jokob-sk/Pi.Alert/issues?q=is%3Aissue+is%3Aclosed). -**Permissions** - -* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/home/pi/pialert/front/log`. -* To solve permission issues you can try setting the owner and group of the `pialert.db` by executing the following on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. -* Map to local User and Group IDs. Specify the enviroment variables `HOST_USER_ID` and `HOST_USER_GID` if needed. -* If still facing issues, try to map the pialert.db file (⚠ not folder) to `:/home/pi/pialert/db/pialert.db` (see Examples below 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` as outlined in the instructions above. - +Check also common issues and [debugging tips](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/DEBUG_TIPS.md). Docker-compose examples can be found below. diff --git a/docs/DEBUG_TIPS.md b/docs/DEBUG_TIPS.md index 4b5d8882..46f6986c 100755 --- a/docs/DEBUG_TIPS.md +++ b/docs/DEBUG_TIPS.md @@ -13,7 +13,7 @@ If possible, check if your issue got fixed in the `_dev` image before opening a > ⚠ Please backup your DB and config beforehand! -PLease also search [open issues](https://github.com/jokob-sk/Pi.Alert/issues). +Please also search [open issues](https://github.com/jokob-sk/Pi.Alert/issues). ## Surfacing errors when container restarts @@ -45,3 +45,32 @@ services: # Other service configurations... ``` +## πŸ“ƒCommon issues + +### Permissions + +* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/home/pi/pialert/front/log`. +* To solve permission issues you can try setting the owner and group of the `pialert.db` by executing the following on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. +* Map to local User and Group IDs. Specify the enviroment variables `HOST_USER_ID` and `HOST_USER_GID` if needed. +* If still facing issues, try to map the pialert.db file (⚠ not folder) to `:/home/pi/pialert/db/pialert.db` (see Examples below 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` as outlined in the instructions above. + +### 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. diff --git a/docs/README.md b/docs/README.md index e790190d..4121d0d7 100755 --- a/docs/README.md +++ b/docs/README.md @@ -93,7 +93,7 @@ Suggested test cases: Some additional context: * Permanent settings/config is stored in the `pialert.conf` file -* Currently temporary (session?) settings are stored in the `Parameters` DB table as key - value pairs. This table is wiped during a container rebuild/restart and it's values re-initialized from cookies / session data from the browser. +* Currently temporary (session?) settings are stored in the `Parameters` DB table as key-value pairs. This table is wiped during a container rebuild/restart and it's values re-initialized from cookies / session data from the browser. ## πŸ› Submitting an issue or bug @@ -101,5 +101,6 @@ Before submitting a new issue please spend a couple of minutes on research: * Check [πŸ›‘ Common issues](https://github.com/jokob-sk/Pi.Alert/tree/main/dockerfiles#-common-issues) * Check [πŸ’‘ Closed issues](https://github.com/jokob-sk/Pi.Alert/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/Pi.Alert/blob/main/docs/DEBUG_TIPS.md)❗ ⚠ Please follow the pre-defined issue template to resolve your issue faster.