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.
This commit is contained in:
Hördle Bot
206
TROUBLESHOOTING.md
Normal file
206
TROUBLESHOOTING.md
Normal file
@@ -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.
|
||||
|
||||
75
scripts/fix-database-permissions.sh
Executable file
75
scripts/fix-database-permissions.sh
Executable file
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user