Zum Inhalt

Podman-Deployment

Bifolk unterstützt die Bereitstellung mit Podman über Quadlets — systemd-Unit-Dateien, mit denen systemd Podman-Container nativ verwalten kann. Dies ist die empfohlene Produktionsmethode bei Verwendung von Podman.

Zielgruppe: Systemadministratoren, die Bifolk mit Podman unter Linux betreiben

Voraussetzungen

  • Podman 4.4 oder höher
  • systemd (Standard auf den meisten Linux-Distributionen)
  • Git zum Klonen des Repositories
  • Mindestens 1 GB Festplattenspeicher

Lingering aktivieren

Rootless Podman-Dienste laufen innerhalb Ihrer Benutzersitzung. Damit sie auch nach dem Abmelden aktiv bleiben, aktivieren Sie Lingering für Ihren Benutzer:

loginctl enable-linger $USER

Quadlet-Dateien

Die Quadlets befinden sich im Repository unter docker/quadlets/:

Variante Verzeichnis Datenbank
SQLite docker/quadlets/sqlite/ SQLite (einfacher, einzelne Datei)
PostgreSQL docker/quadlets/postgres/ PostgreSQL (empfohlen für die Produktion)

Installation

1. Repository klonen

git clone <repo-url>
cd bifolk

2. Podman-Secrets erstellen

Secrets werden im Podman-Secret-Speicher abgelegt und als schreibgeschützte Dateien in den Container eingebunden. Der Entrypoint liest sie über die *_FILE-Umgebungsvariablen.

SQLite-Variante (2 Secrets):

# Django Secret Key generieren und speichern
python3 -c "import secrets; print(secrets.token_urlsafe(50))" > /tmp/secret_key.txt
podman secret create bifolk_secret_key /tmp/secret_key.txt
rm /tmp/secret_key.txt

# E-Mail-Passwort speichern (leer lassen, wenn keine E-Mail konfiguriert ist)
echo "" > /tmp/email_password.txt
podman secret create bifolk_email_password /tmp/email_password.txt
rm /tmp/email_password.txt

PostgreSQL-Variante (3 Secrets):

# Django Secret Key generieren und speichern
python3 -c "import secrets; print(secrets.token_urlsafe(50))" > /tmp/secret_key.txt
podman secret create bifolk_secret_key /tmp/secret_key.txt
rm /tmp/secret_key.txt

# Datenbankpasswort generieren und speichern
python3 -c "import secrets; print(secrets.token_urlsafe(32))" > /tmp/db_password.txt
podman secret create bifolk_db_password /tmp/db_password.txt
rm /tmp/db_password.txt

# E-Mail-Passwort speichern (leer lassen, wenn keine E-Mail konfiguriert ist)
echo "" > /tmp/email_password.txt
podman secret create bifolk_email_password /tmp/email_password.txt
rm /tmp/email_password.txt

3. Umgebungsdatei erstellen

mkdir -p ~/.config/containers/systemd

Kopieren Sie die Beispiel-Umgebungsdatei für Ihre gewählte Variante:

# SQLite
cp docker/quadlets/sqlite/bifolk.env ~/.config/containers/systemd/bifolk.env

# PostgreSQL
cp docker/quadlets/postgres/bifolk.env ~/.config/containers/systemd/bifolk.env

Bearbeiten Sie die Datei und passen Sie Domain, Zeitzone und E-Mail-Einstellungen an:

nano ~/.config/containers/systemd/bifolk.env

Wichtige Einstellungen:

DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=ihredomain.de,www.ihredomain.de
DJANGO_CSRF_TRUSTED_ORIGINS=https://ihredomain.de
TIME_ZONE=Europe/Berlin

4. Quadlet-Dateien installieren

Kopieren Sie die Quadlet-Dateien für Ihre gewählte Variante in das systemd-Quadlet-Verzeichnis:

# SQLite
cp docker/quadlets/sqlite/*.container \
   docker/quadlets/sqlite/*.network \
   docker/quadlets/sqlite/*.volume \
   ~/.config/containers/systemd/

# PostgreSQL
cp docker/quadlets/postgres/*.container \
   docker/quadlets/postgres/*.network \
   docker/quadlets/postgres/*.volume \
   ~/.config/containers/systemd/

5. systemd neu laden und Dienste starten

systemctl --user daemon-reload

Überprüfen Sie, ob die Quadlets erkannt wurden:

systemctl --user list-units 'bifolk*'

Starten Sie die Dienste:

# SQLite
systemctl --user start bifolk-app.service bifolk-docs.service

# PostgreSQL (zuerst die Datenbank, dann die Anwendung starten)
systemctl --user start bifolk-db.service bifolk-app.service bifolk-docs.service

6. Superuser erstellen

podman exec -it bifolk-app python /bifolk/app/manage.py createsuperuser

7. Überprüfung

# Dienststatus prüfen
systemctl --user status bifolk-app.service

# Anwendungs-Zustandsprüfung
curl http://localhost:8000/health/

# Aktuelle Logs anzeigen
journalctl --user -u bifolk-app --since "10 minutes ago"

Häufige Befehle

Logs anzeigen

journalctl --user -u bifolk-app -f
journalctl --user -u bifolk-db -f

Dienst neu starten

systemctl --user restart bifolk-app.service

Alle Dienste stoppen

systemctl --user stop bifolk-app.service bifolk-docs.service

# Nur PostgreSQL
systemctl --user stop bifolk-db.service

Bifolk aktualisieren

# Neuestes Image herunterladen
podman pull ghcr.io/mwtechnican/bifolk:latest

# Dienst neu starten, um die Aktualisierung anzuwenden
systemctl --user restart bifolk-app.service

Rootful-Deployment (systemweit)

Um Bifolk als systemweiten Dienst (rootful, für alle Benutzer zugänglich) zu betreiben, kopieren Sie die Quadlets in das Systemverzeichnis und verwenden Sie systemctl ohne --user:

sudo cp docker/quadlets/sqlite/*.container \
        docker/quadlets/sqlite/*.network \
        docker/quadlets/sqlite/*.volume \
        /etc/containers/systemd/

sudo cp docker/quadlets/sqlite/bifolk.env /etc/containers/systemd/bifolk.env

sudo systemctl daemon-reload
sudo systemctl start bifolk-app.service bifolk-docs.service

Warning

Rootful Podman führt Container als Root auf dem Host aus. Bevorzugen Sie das Rootless-Deployment, sofern Ihre Infrastruktur keine systemweiten Dienste erfordert.

Fehlerbehebung

Dienst startet nicht

Prüfen Sie das Journal auf Fehlerdetails:

journalctl --user -u bifolk-app --since "5 minutes ago" -n 50

Quadlets werden nach daemon-reload nicht erkannt

Überprüfen Sie, ob die Dateien im richtigen Verzeichnis mit den richtigen Dateiendungen liegen:

ls ~/.config/containers/systemd/

Prüfen Sie auf Syntaxfehler in den Quadlet-Dateien:

/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

Secret nicht gefunden

Listen Sie vorhandene Secrets auf, um die Erstellung zu überprüfen:

podman secret ls

Erstellen Sie fehlende Secrets mit den Befehlen aus Schritt 2 neu.

Zugriffsfehler bei Volumes

Das :Z-Flag bei Volume-Mounts setzt SELinux-Labels neu. Falls Zugriffsfehler auftreten, die nicht mit SELinux zusammenhängen, stellen Sie sicher, dass der Container als Root (UID 0) startet, damit der Entrypoint chown ausführen und dann auf den bifolk-Benutzer wechseln kann.

Nächste Schritte