From dc7ff8317cd71dd990ff0acf9b6704c4a04f0bd3 Mon Sep 17 00:00:00 2001
From: jokob-sk <jokob.sk@gmail.com>
Date: Sun, 7 Dec 2025 21:40:40 +1100
Subject: [PATCH] DOCS: pihole DB troubleshooting permissions #1330

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
---
 front/plugins/pihole_scan/README.md | 48 +++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/front/plugins/pihole_scan/README.md b/front/plugins/pihole_scan/README.md
index 9b63d9ed..be0a84bc 100755
--- a/front/plugins/pihole_scan/README.md
+++ b/front/plugins/pihole_scan/README.md
@@ -1,7 +1,6 @@
 ## Overview
 
-A plugin allowing for importing devices from the PiHole database. This is an import plugin using an SQLite database as a source. 
-
+A plugin allowing for importing devices from the PiHole database. This is an import plugin using an SQLite database as a source.
 
 ### Usage
 
@@ -9,3 +8,48 @@ A plugin allowing for importing devices from the PiHole database. This is an imp
   - `PIHOLE_RUN` is used to enable the import by setting it e.g. to `schedule` or `once`   (pre-set to `disabled`)
   - `PIHOLE_RUN_SCHD` is to configure how often the plugin is executed if `PIHOLE_RUN` is set to `schedule` (pre-set to every 30 min)
   - `PIHOLE_DB_PATH` setting must match the location of your PiHole database (pre-set to `/etc/pihole/pihole-FTL.db`)
+
+Here’s an ultra-condensed “1-minute fix” version:
+
+---
+
+## Troubleshooting
+
+### Permission problems:
+
+NetAlertX cannot read Pi-hole DB (`/etc/pihole/pihole-FTL.db`) due to permissions:
+
+```
+[Plugins] ⚠ ERROR: ATTACH DATABASE failed with SQL ERROR: unable to open database: /etc/pihole/pihole-FTL.db
+```
+
+#### Solution:
+
+1. **Mount full Pi-hole directory (read-only):**
+
+```yaml
+volumes:
+  - /etc/pihole:/etc/pihole:ro
+```
+
+2. **Add NetAlertX to Pi-hole group:**
+
+```yaml
+group_add:
+  - 1001  # check with `getent group pihole`
+```
+
+**Verify:**
+
+```bash
+docker exec -it netalertx id
+# groups=1001,...  ✅ pihole group included
+```
+
+#### Notes:
+
+* Avoid mounting single DB files.
+* Keep mount read-only (`:ro`) to protect Pi-hole data.
+* Use `group_add` instead of chmod.
+
+