Fehlerbehebung¶

Lösungen für häufige Probleme bei der Bifolk-Bereitstellung.

Zielgruppe: Systemadministratoren

Allgemeiner Ansatz¶

Logs prüfen: docker logs bifolk-app --tail 100
Konfiguration verifizieren: docker compose config
Django-Prüfung ausführen: docker compose exec bifolk-app python manage.py check
Konnektivität testen: docker compose exec bifolk-db pg_isready -U bifolk

Container-Probleme¶

Container beendet sich sofort¶

Logs auf Ursache prüfen:

docker logs bifolk-app

Häufige Ursachen:

Fehler	Ursache	Lösung
`ImproperlyConfigured`	Fehlende oder ungültige `.env`	`.env` existiert und Werte sind korrekt
`OperationalError: could not connect`	Datenbank nicht bereit	Warten, dann `docker compose restart bifolk-app`
`ProgrammingError: relation does not exist`	Fehlende Migrationen	`docker compose exec bifolk-app python manage.py migrate`

Container startet wiederholt neu¶

# Neustart-Zähler prüfen
docker inspect bifolk-app --format '{{.RestartCount}}'

# Ressourcennutzung prüfen
docker stats bifolk-app --no-stream

Port-Konflikt:

# Finden, was den Port verwendet
sudo lsof -i :8000

# Port in .env ändern falls nötig
# APP_PORT=8001

Build schlägt fehl¶

# Ohne Cache neu bauen
docker compose build --no-cache bifolk-app

Datenbankprobleme¶

Verbindung zur Datenbank nicht möglich¶

# Prüfen, ob Datenbankcontainer läuft
docker ps | grep bifolk-db

# Datenbankgesundheit prüfen
docker compose exec bifolk-db pg_isready -U bifolk

# DB_HOST in .env verifizieren (muss "bifolk-db" sein, nicht "localhost")
grep DB_HOST .env

# Docker-Netzwerk prüfen
docker network inspect bifolknet

Authentifizierung fehlgeschlagen¶

FATAL: password authentication failed for user "bifolk"

Das Passwort in .env oder secrets/db_password.txt stimmt nicht mit PostgreSQL überein. Entweder Secret-Datei aktualisieren oder PostgreSQL-Passwort zurücksetzen:

# Passwort in PostgreSQL auf Secret-Wert zurücksetzen
PASS=$(cat secrets/db_password.txt)
echo "ALTER USER bifolk WITH PASSWORD '$PASS';" | \
  docker compose exec -T bifolk-db psql -U postgres

docker compose restart bifolk-app

Datenbank existiert nicht¶

docker compose exec bifolk-db psql -U bifolk -d postgres -c "CREATE DATABASE bifolk;"
docker compose exec bifolk-app python manage.py migrate
docker compose restart bifolk-app

Berechtigungsprobleme¶

Secret-Dateien können nicht gelesen werden¶

# Berechtigungsskript ausführen
bash scripts/bifolk_set_permissions.sh

# Neu starten
docker compose restart

Medien-Upload schlägt fehl¶

# Medienverzeichnis-Eigentümer im Container korrigieren
docker compose exec bifolk-app chown -R django:django /bifolk/media

SQLite-Zugriff verweigert (Entwicklung)¶

# Dateiberechtigungen korrigieren
chmod 664 app/db.sqlite3
chmod 775 app/

Konfigurationsprobleme¶

bifolk.json wird nicht generiert¶

Die Konfigurationsdatei wird beim Container-Start generiert. Wenn sie fehlt:

# Entrypoint-Logs prüfen
docker logs bifolk-app | head -20

# Generation manuell auslösen
docker compose exec bifolk-app python /bifolk/generate_config.py

# Neu starten
docker compose restart bifolk-app

ALLOWED_HOSTS-Fehler¶

DisallowedHost at / - Invalid HTTP_HOST header: 'example.com'

Domain zu DJANGO_ALLOWED_HOSTS in .env hinzufügen:

DJANGO_ALLOWED_HOSTS=example.com,www.example.com,localhost

Dann neu starten: docker compose restart bifolk-app

Statische Dateien werden nicht geladen¶

Wenn die Web-Oberfläche ungestyltes HTML zeigt:

# Statische Dateien sammeln
docker compose exec bifolk-app python manage.py collectstatic --no-input --clear

# Neu starten
docker compose restart bifolk-app

# Browser-Cache leeren (Strg+Umschalt+R)

E-Mail-Probleme¶

E-Mails werden nicht gesendet¶

# E-Mail-Konfiguration verifizieren
grep EMAIL .env

# Senden testen
docker compose exec bifolk-app python manage.py shell -c "
from django.core.mail import send_mail
send_mail('Test', 'Testnachricht', 'from@example.com', ['to@example.com'])
"

Häufige Lösungen:

Gmail erfordert ein App-Passwort (nicht Ihr normales Passwort)
Port 587 erfordert EMAIL_USE_TLS=True, EMAIL_USE_SSL=False
Port 465 erfordert EMAIL_USE_TLS=False, EMAIL_USE_SSL=True — beide auf True führen zu einem Verbindungsfehler
Wenn DEBUG=True, gehen E-Mails an die Konsole statt über SMTP

Leistungsprobleme¶

Langsame Antwortzeiten¶

# Ressourcennutzung prüfen
docker stats --no-stream

# Datenbank vacuumen
docker compose exec bifolk-db psql -U bifolk -d bifolk -c "VACUUM ANALYZE;"

# Lang laufende Abfragen prüfen
docker compose exec bifolk-db psql -U bifolk -d bifolk -c "
  SELECT pid, now() - query_start AS duration, query
  FROM pg_stat_activity
  WHERE state = 'active' AND now() - query_start > interval '5 seconds';"

Festplatte voll¶

# Festplattennutzung prüfen
df -h
docker system df

# Docker-Ressourcen bereinigen
docker system prune -a -f

Hilfe bekommen¶

Beim Melden von Problemen sammeln Sie Folgendes:

# Anwendungslogs
docker logs bifolk-app > bifolk-app.log

# Datenbanklogs
docker logs bifolk-db > bifolk-db.log

# Container-Status
docker ps -a > container-status.txt

# Django-Prüfung
docker compose exec bifolk-app python manage.py check > django-check.txt

# Systeminformationen
docker version > system-info.txt
uname -a >> system-info.txt

Note

Entfernen Sie immer Secrets und Passwörter, bevor Sie Konfigurationsdateien teilen.