From b917b30830f0edc045b0b0c4cb9ce7b8c452b765 Mon Sep 17 00:00:00 2001
From: Arunavo Ray <rayanup3@gmail.com>
Date: Wed, 28 May 2025 13:37:07 +0530
Subject: [PATCH] docs: add Docker bind mount vs named volume permission
 guidance

- Add new section 'Docker Volume Types and Permissions'
- Explain difference between named volumes and bind mounts
- Provide solution for bind mount permission issues (UID 1001)
- Clarify why named volumes are recommended and used in official docker-compose.yml
- Address SQLite permission errors in Docker environments using bind mounts

Addresses issue reported by user using bind mounts in Portainer.
---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index e98e9c7..569170b 100644
--- a/README.md
+++ b/README.md
@@ -513,6 +513,36 @@ Try the following steps:
 >
 > This setup provides a complete containerized deployment for the Gitea Mirror application.
 
+#### Docker Volume Types and Permissions
+
+> [!IMPORTANT]
+> **Named Volumes vs Bind Mounts**: If you encounter SQLite permission errors even when using Docker, check your volume configuration:
+
+**✅ Named Volumes (Recommended):**
+```yaml
+volumes:
+  - gitea-mirror-data:/app/data  # Docker manages permissions automatically
+```
+
+**⚠️ Bind Mounts (Requires Manual Permission Setup):**
+```yaml
+volumes:
+  - /host/path/to/data:/app/data  # Host filesystem permissions apply
+```
+
+**If using bind mounts**, ensure the host directory is owned by UID 1001 (the `gitea-mirror` user):
+```bash
+# Set correct ownership for bind mount
+sudo chown -R 1001:1001 /host/path/to/data
+sudo chmod -R 755 /host/path/to/data
+```
+
+**Why named volumes work better:**
+- Docker automatically handles permissions
+- Better portability across different hosts
+- No manual permission setup required
+- Used by our official docker-compose.yml
+
 
 #### Database Maintenance