From b51ad2ff1add6b0aeb872b722ede46ec75d323a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=B6rdle=20Bot?= <bot@hoerdle.local>
Date: Mon, 1 Dec 2025 16:50:24 +0100
Subject: [PATCH] docs: add troubleshooting guide and fix permissions script
 for database issues

- Introduced a comprehensive troubleshooting guide for common application errors, particularly focusing on database permission issues after migrating databases.
- Added a script to automate the fixing of database permissions, ensuring SQLite can write to the necessary files and directories.
- Included detailed steps for diagnosing and resolving various container and database-related problems to enhance user support.
---
 TROUBLESHOOTING.md                  | 206 ++++++++++++++++++++++++++++
 scripts/fix-database-permissions.sh |  75 ++++++++++
 2 files changed, 281 insertions(+)
 create mode 100644 TROUBLESHOOTING.md
 create mode 100755 scripts/fix-database-permissions.sh

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 0000000..78686e4
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,206 @@
+# Troubleshooting Guide
+
+## Application Error: "a server-side exception has occurred"
+
+Dieser Fehler tritt auf, wenn die Next.js-Anwendung auf dem Server einen Fehler hat.
+
+### ⚠️ Datenbank-Berechtigungen (wenn DB von anderem Server kopiert wurde)
+
+**Symptom**: Application Error nach dem Kopieren einer Datenbank von einem anderen Server
+
+**Ursache**: SQLite benötigt Schreibrechte auf:
+- Die Datenbankdatei selbst (`prod.db`)
+- Das Datenbankverzeichnis (für temporäre Dateien wie `-wal`, `-shm`)
+
+**Sofort-Lösung (auf dem Server ausführen)**:
+```bash
+# 1. Setze Berechtigungen für Datenbankverzeichnis und Datei
+chmod 775 ./data
+chmod 664 ./data/prod.db
+
+# 2. Falls temporäre SQLite-Dateien existieren, auch diese:
+chmod 664 ./data/*.db-wal 2>/dev/null || true
+chmod 664 ./data/*.db-shm 2>/dev/null || true
+
+# 3. Oder verwende das Fix-Skript:
+./scripts/fix-database-permissions.sh
+
+# 4. Container neu starten
+docker compose restart hoerdle
+
+# 5. Logs prüfen
+docker logs hoerdle --tail=50
+```
+
+**Warum passiert das?**
+- Wenn du eine Datenbankdatei von einem anderen Server kopierst, behält sie die ursprünglichen Berechtigungen
+- SQLite muss Schreibrechte haben, um zu funktionieren
+- Auch das Verzeichnis braucht Schreibrechte (für SQLite-WAL-Modus) 
+
+### Sofort-Diagnose (auf dem Server ausführen)
+
+```bash
+# 1. Container-Logs prüfen (die wichtigste Information!)
+docker logs hoerdle --tail=100
+
+# 2. Container-Status prüfen
+docker ps | grep hoerdle
+
+# 3. Prüfe ob Datenbank existiert
+docker exec hoerdle ls -lh /app/data/prod.db
+
+# 4. Prüfe ob Server auf Port 3000 antwortet (intern)
+docker exec hoerdle curl -f http://localhost:3000/api/daily
+
+# 5. Prüfe Health Check
+docker inspect hoerdle --format='{{json .State.Health}}' | python3 -m json.tool
+```
+
+### Häufige Ursachen und Lösungen
+
+#### 1. Datenbankfehler / Migrationen fehlgeschlagen
+
+**Symptom**: Logs zeigen Prisma-Fehler oder "database locked"
+
+**Lösung**:
+```bash
+# Container-Logs prüfen
+docker logs hoerdle | grep -i "migration\|database\|prisma"
+
+# Falls Migrationen fehlgeschlagen sind:
+docker compose restart hoerdle
+
+# Bei persistierenden Problemen: Datenbank-Backup prüfen
+ls -lh ./backups/
+```
+
+#### 2. Container läuft nicht oder ist crashed
+
+**Symptom**: Container existiert nicht oder Status zeigt "Exited"
+
+**Lösung**:
+```bash
+# Container-Status prüfen
+docker ps -a | grep hoerdle
+
+# Container neu starten
+docker compose up -d
+
+# Falls Container nicht startet, Logs prüfen
+docker logs hoerdle --tail=200
+```
+
+#### 3. Caddy kann Container nicht erreichen
+
+**Symptom**: 502 Bad Gateway oder "connection refused" in Caddy-Logs
+
+**Lösung**:
+```bash
+# Prüfe ob hoerdle Container läuft
+docker ps | grep hoerdle
+
+# Prüfe Netzwerk
+docker network inspect hoerdle_default
+
+# Prüfe Caddy-Logs
+docker logs hoerdle-caddy --tail=50
+
+# Stelle sicher, dass Caddyfile Port 3000 verwendet (nicht 3010!)
+grep "reverse_proxy" Caddyfile
+```
+
+#### 4. Fehlende Umgebungsvariablen
+
+**Symptom**: Logs zeigen undefined variables
+
+**Lösung**:
+```bash
+# Prüfe wichtige Umgebungsvariablen
+docker exec hoerdle env | grep -E "DATABASE_URL|NODE_ENV"
+
+# Prüfe .env Datei (falls vorhanden)
+cat .env | grep DATABASE_URL
+```
+
+#### 5. Build-Fehler oder fehlerhafte Dateien
+
+**Symptom**: Container startet, aber App crasht sofort
+
+**Lösung**:
+```bash
+# Container komplett neu bauen
+docker compose down
+docker compose build --no-cache
+docker compose up -d
+
+# Prüfe Build-Logs
+docker compose build 2>&1 | tee build.log
+```
+
+### Detaillierte Log-Analyse
+
+```bash
+# Alle Fehler in Logs finden
+docker logs hoerdle 2>&1 | grep -i -E "error|exception|fatal|panic" | tail -50
+
+# Prisma-spezifische Fehler
+docker logs hoerdle 2>&1 | grep -i prisma | tail -20
+
+# Next.js-spezifische Fehler
+docker logs hoerdle 2>&1 | grep -i "next\|react" | tail -20
+```
+
+### Netzwerk-Debugging
+
+```bash
+# Teste Verbindung von Caddy zu Hördle
+docker exec hoerdle-caddy wget -O- http://hoerdle:3000/api/daily
+
+# Prüfe alle Container im Netzwerk
+docker network inspect hoerdle_default --format='{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{"\n"}}{{end}}'
+```
+
+### Datenbank-Debugging
+
+```bash
+# Prüfe Datenbank-Integrität
+docker exec hoerdle npx prisma db pull
+
+# Prüfe Datenbank-Struktur
+docker exec hoerdle npx prisma studio &
+# (dann Browser öffnen - erfordert X11 forwarding oder lokalen Zugriff)
+```
+
+### Quick-Fix: Vollständiger Neustart
+
+Wenn nichts anderes hilft:
+
+```bash
+# 1. Backup erstellen
+cp ./data/prod.db ./backups/prod_$(date +%Y%m%d_%H%M%S).db
+
+# 2. Container stoppen
+docker compose down
+
+# 3. Container neu starten
+docker compose up -d
+
+# 4. Logs beobachten
+docker compose logs -f
+```
+
+## Bei weiterem Bedarf
+
+Sammle folgende Informationen für weitere Hilfe:
+
+```bash
+echo "=== Container Status ===" && \
+docker ps -a | grep hoerdle && \
+echo -e "\n=== Letzte 50 Log-Zeilen ===" && \
+docker logs hoerdle --tail=50 && \
+echo -e "\n=== Fehler in Logs ===" && \
+docker logs hoerdle 2>&1 | grep -i error | tail -20
+```
+
+Kopiere die vollständige Ausgabe und sende sie weiter.
+
diff --git a/scripts/fix-database-permissions.sh b/scripts/fix-database-permissions.sh
new file mode 100755
index 0000000..e7424b3
--- /dev/null
+++ b/scripts/fix-database-permissions.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+# Script zum Reparieren von Datenbank-Berechtigungen
+# Wichtig: Wenn eine Datenbank von einem anderen Server kopiert wurde,
+# müssen die Berechtigungen angepasst werden, damit SQLite schreiben kann.
+
+set -e
+
+echo "🔧 Repariere Datenbank-Berechtigungen..."
+
+# Datenbank-Pfad aus docker-compose.yml oder .env ermitteln
+DB_DIR="./data"
+DB_FILE="$DB_DIR/prod.db"
+
+# Prüfe ob Datenbankverzeichnis existiert
+if [ ! -d "$DB_DIR" ]; then
+    echo "❌ Datenbankverzeichnis '$DB_DIR' existiert nicht!"
+    echo "   Erstelle Verzeichnis..."
+    mkdir -p "$DB_DIR"
+fi
+
+# Prüfe ob Datenbankdatei existiert
+if [ ! -f "$DB_FILE" ]; then
+    echo "⚠️  Datenbankdatei '$DB_FILE' existiert nicht!"
+    echo "   Das ist okay, wenn du eine neue Datenbank erstellst."
+    echo ""
+    echo "   Setze Berechtigungen für das Verzeichnis..."
+else
+    echo "✅ Datenbankdatei gefunden: $DB_FILE"
+fi
+
+# Setze Berechtigungen für Datenbankverzeichnis
+# SQLite braucht Schreibrechte auf:
+# 1. Die Datenbankdatei selbst
+# 2. Das Verzeichnis (für -wal und -shm Dateien)
+
+echo "📝 Setze Berechtigungen..."
+
+# Verzeichnis: Lesen, Schreiben, Ausführen für Owner und Gruppe
+chmod 775 "$DB_DIR"
+
+# Datenbankdatei: Lesen und Schreiben für Owner und Gruppe
+if [ -f "$DB_FILE" ]; then
+    chmod 664 "$DB_FILE"
+    
+    # Auch für alle SQLite-temporären Dateien
+    chmod 664 "$DB_DIR"/*.db-wal 2>/dev/null || true
+    chmod 664 "$DB_DIR"/*.db-shm 2>/dev/null || true
+    chmod 664 "$DB_DIR"/*.db-journal 2>/dev/null || true
+fi
+
+# Setze Besitzer (wichtig: Container läuft als root laut docker-compose.yml)
+# Aber falls ein bestimmter User benötigt wird:
+if [ -n "$SUDO_USER" ]; then
+    echo "👤 Setze Besitzer auf: $SUDO_USER"
+    chown -R "$SUDO_USER:$SUDO_USER" "$DB_DIR"
+else
+    echo "ℹ️  Container läuft als root, keine Besitzer-Änderung nötig"
+fi
+
+# Prüfe aktuelle Berechtigungen
+echo ""
+echo "📋 Aktuelle Berechtigungen:"
+ls -lh "$DB_DIR"/*.db* 2>/dev/null || echo "   (Keine .db Dateien gefunden)"
+
+echo ""
+echo "✅ Berechtigungen gesetzt!"
+echo ""
+echo "💡 Wichtig für SQLite:"
+echo "   - Die Datenbankdatei braucht Schreibrechte (rw-rw-r--)"
+echo "   - Das Verzeichnis braucht Schreibrechte (rwxrwxr-x)"
+echo "   - SQLite erstellt temporäre Dateien (-wal, -shm) im gleichen Verzeichnis"
+echo ""
+echo "🔄 Starte Container neu, damit die Änderungen wirksam werden:"
+echo "   docker compose restart hoerdle"
+