From 89df3ed9e3be82fe75a71415129beb536aea1c7c Mon Sep 17 00:00:00 2001
From: Michael Skrynski <zlorfi@gmail.com>
Date: Thu, 15 Jan 2026 10:02:13 +0100
Subject: [PATCH] Add init-db service and update deployment docs

---
 DEPLOYMENT.md   | 52 +++++++++++++++++++++++++++++++++++++++++++++----
 QUICK_DEPLOY.md | 24 ++++++++++++++++-------
 deploy.sh       | 17 ++++++++++++++++
 3 files changed, 82 insertions(+), 11 deletions(-)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index ca87c7f..ad2bd5d 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -486,15 +486,59 @@ docker-compose config
 sudo netstat -tulpn | grep LISTEN
 ```
 
-### Database Issues
+### Database Issues / "unable to open database file"
+
+**Error:**
+```
+Failed to initialize database: SqliteError: unable to open database file
+```
+
+This occurs when the Docker volume directory doesn't exist or lacks write permissions.
+
+**Solution:**
+
+```bash
+# 1. Stop services
+docker-compose down
+
+# 2. Find the volume path
+docker volume inspect edh-stats_sqlite_data
+
+# Look for the "Mountpoint" value - example: /var/lib/docker/volumes/edh-stats_sqlite_data/_data
+
+# 3. Create directories with proper permissions
+VOLUME_PATH="/var/lib/docker/volumes/edh-stats_sqlite_data/_data"
+sudo mkdir -p "$VOLUME_PATH"
+sudo chmod 755 "$VOLUME_PATH"
+
+# 4. Do the same for logs volume
+LOGS_PATH="/var/lib/docker/volumes/edh-stats_app_logs/_data"
+sudo mkdir -p "$LOGS_PATH"
+sudo chmod 755 "$LOGS_PATH"
+
+# 5. Start services again
+docker-compose up -d
+
+# 6. Check logs
+docker-compose logs -f backend
+```
+
+**Or use the automatic init service:**
+
+If you're using the updated docker-compose (with `init-db` service), it will automatically create directories. Just run:
+
+```bash
+docker-compose up -d
+docker-compose logs init-db  # Watch initialization
+docker-compose logs -f backend
+```
+
+**Verify after fix:**
 
 ```bash
 # Check database file exists
 docker-compose exec backend ls -lh /app/database/data/
 
-# Verify permissions
-docker-compose exec backend chmod 666 /app/database/data/edh-stats.db
-
 # Check database integrity
 docker-compose exec backend sqlite3 /app/database/data/edh-stats.db "PRAGMA integrity_check;"
 ```
diff --git a/QUICK_DEPLOY.md b/QUICK_DEPLOY.md
index e67b2ff..ecf54ac 100644
--- a/QUICK_DEPLOY.md
+++ b/QUICK_DEPLOY.md
@@ -349,16 +349,26 @@ docker-compose down
 docker-compose up -d
 ```
 
-### Database Issues
+### Database Issues / "unable to open database file"
 ```bash
-# Check database exists
-docker-compose exec backend ls -lh /app/database/data/
+# If you see: "Failed to initialize database: SqliteError: unable to open database file"
 
-# Verify integrity
-docker-compose exec backend sqlite3 /app/database/data/edh-stats.db "PRAGMA integrity_check;"
+# Stop services
+docker-compose down
 
-# Check permissions
-docker-compose exec backend chmod 666 /app/database/data/edh-stats.db
+# Find volume path
+VOLUME_PATH=$(docker volume inspect edh-stats_sqlite_data | grep -o '"Mountpoint": "[^"]*' | cut -d'"' -f4)
+echo "Volume path: $VOLUME_PATH"
+
+# Create directories with permissions
+sudo mkdir -p "$VOLUME_PATH"
+sudo chmod 755 "$VOLUME_PATH"
+
+# Start again
+docker-compose up -d
+
+# Check logs
+docker-compose logs -f backend
 ```
 
 ---
diff --git a/deploy.sh b/deploy.sh
index e27822e..5d8f499 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -262,6 +262,12 @@ generate_deployment_config() {
 #   JWT_SECRET=\$(openssl rand -base64 32)
 #   CORS_ORIGIN=https://yourdomain.com
 #   ALLOW_REGISTRATION=false
+#
+# FIRST TIME SETUP:
+# 1. Create .env file with above variables
+# 2. Run: docker-compose up -d
+# 3. If database error occurs, run: docker volume inspect ${PROJECT_NAME}_sqlite_data
+# 4. Note the Mountpoint path and ensure it's writable by Docker
 
 version: '3.8'
 
@@ -298,6 +304,17 @@ services:
     networks:
       - edh-stats-network
     stop_grace_period: 30s
+    depends_on:
+      - init-db
+
+  init-db:
+    image: alpine:latest
+    volumes:
+      - sqlite_data:/app/database/data
+      - app_logs:/app/logs
+    command: sh -c "mkdir -p /app/database/data /app/logs && chmod 755 /app/database/data /app/logs && echo 'Database directories initialized'"
+    networks:
+      - edh-stats-network
 
   frontend:
     image: ${FRONTEND_IMAGE}