From 4fe22e353931fe4d790e7b070311f509b493bb45 Mon Sep 17 00:00:00 2001
From: Beda Schmid <beda@tukutoi.com>
Date: Mon, 2 Mar 2026 18:58:19 -0300
Subject: [PATCH] Document bind-mount permissions and ignore runtime data tree

---
 .gitignore                          |  4 +---
 README.md                           |  2 ++
 doc/operations-and-configuration.md | 16 ++++++++++++++++
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 242269c..8f185ec 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,9 +20,7 @@ build/
 !.env.example
 
 # Data and generated artifacts (runtime only)
-data/postgres/
-data/redis/
-data/storage/
+data/
 
 # OS / IDE
 .DS_Store
diff --git a/README.md b/README.md
index 9cfb0be..7474734 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,8 @@ LedgerDock stores data in Docker volumes so it survives container restarts:
 - `dcm-storage` for uploaded files and app storage
 - `typesense-data` for the search index
 
+If you switch to host bind mounts (for example under `./data/`), create those directories and grant write access to container runtime user `uid=10001` for backend storage paths.
+
 To remove everything, including data:
 
 ```bash
diff --git a/doc/operations-and-configuration.md b/doc/operations-and-configuration.md
index 8577758..5b4e883 100644
--- a/doc/operations-and-configuration.md
+++ b/doc/operations-and-configuration.md
@@ -42,6 +42,22 @@ Tail logs:
 docker compose logs -f
 ```
 
+## Host Bind Mounts
+
+If you replace Docker named volumes with host bind mounts (for example `./data/storage:/data/storage`), ensure host directories exist and are writable by the backend runtime user.
+
+Backend and worker run as non-root user `uid=10001` inside containers. For host-mounted storage paths:
+
+```bash
+mkdir -p ./data/storage
+sudo chown -R 10001:10001 ./data/storage
+sudo chmod -R u+rwX,g+rwX ./data/storage
+```
+
+If permissions are incorrect, API startup fails with errors similar to:
+- `PermissionError: [Errno 13] Permission denied: '/data/storage'`
+- `FileNotFoundError` for `/data/storage/originals`
+
 ## Frontend Build Baseline
 
 The frontend Dockerfile uses `node:22-slim` with a standard `npm ci --no-audit` install step and no npm-specific build tuning flags.