From 22a4b71653e06fe9122b95a0727a2bee9d364371 Mon Sep 17 00:00:00 2001
From: Arunavo Ray <rayanup3@gmail.com>
Date: Wed, 28 May 2025 09:21:01 +0530
Subject: [PATCH] docs: add SQLite permission troubleshooting for direct
 installation

- Add new section 'Database Permissions for Direct Installation' to README
- Explain common SQLite permission errors when running without Docker
- Provide secure permission fixes (chmod 755/644 instead of 777)
- Clarify why Docker deployment avoids these issues
- Recommend Docker/Docker Compose as preferred deployment method

Addresses permission issues reported by users running the application directly on their systems.
---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index 6f3bca5..e98e9c7 100644
--- a/README.md
+++ b/README.md
@@ -282,6 +282,36 @@ bun run reset-users
 bun run check-db
 ```
 
+##### Database Permissions for Direct Installation
+
+> [!IMPORTANT]
+> **If you're running the application directly** (not using Docker), you may encounter SQLite permission errors. This is because SQLite requires both read/write access to the database file and write access to the directory containing the database.
+
+**Common Error:**
+```
+Error: [ERROR] SQLiteError: attempt to write a readonly database
+```
+
+**Solution:**
+```bash
+# Ensure the data directory exists and has proper permissions
+mkdir -p data
+chmod 755 data
+
+# If the database file already exists, ensure it's writable
+chmod 644 data/gitea-mirror.db
+
+# Make sure the user running the application owns the data directory
+chown -R $(whoami) data/
+```
+
+**Why Docker doesn't have this issue:**
+- Docker containers run with a dedicated user (`gitea-mirror`) that owns the `/app/data` directory
+- The container setup ensures proper permissions are set during image build
+- Volume mounts are handled by Docker with appropriate permissions
+
+**Recommended approach:** Use Docker or Docker Compose for deployment to avoid permission issues entirely.
+
 ### Configuration
 
 Gitea Mirror can be configured through environment variables or through the web UI. See the [Configuration Guide](src/content/docs/configuration.md) for more details.