Web-Interface selbst hosten

Onesimus Web ist eine Django/HTMX-Anwendung, die von Daphne (ASGI) hinter nginx ausgeliefert wird. Die Einrichtung dauert auf einem frischen Debian/Ubuntu-Server etwa 15 Minuten.

Voraussetzungen: Debian 12+ / Ubuntu 22.04+, Python 3.11+, nginx ≥ 1.18, ein Domainname mit DNS-Eintrag auf den Server.

1. System-Abhängigkeiten

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip nginx git

2. Service-User und Verzeichnis anlegen

sudo useradd -r -s /usr/sbin/nologin www-data   # auf den meisten Systemen vorhanden
sudo mkdir -p /srv/onesimus-web
sudo chown www-data:www-data /srv/onesimus-web

3. Klonen und installieren

cd /srv/onesimus-web
sudo -u www-data git clone https://github.com/Beerlesklopfer/onesimus-web.git .

# Virtualenv erstellen und Abhängigkeiten installieren
sudo -u www-data python3 -m venv .venv
sudo -u www-data .venv/bin/pip install -r requirements-prod.txt

4. Umgebungskonfiguration

Umgebungsvariablen liegen in /etc/onesimus/onesimus.env. Das install-system-Make-Ziel legt diese Datei automatisch aus einer Vorlage an. Manuell erstellen:

sudo mkdir -p /etc/onesimus
sudo tee /etc/onesimus/onesimus.env <<EOF
DJANGO_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
DJANGO_DEBUG=false
DJANGO_ALLOWED_HOSTS=onesimus.beispiel.de
CSRF_TRUSTED_ORIGINS=https://onesimus.beispiel.de
DJANGO_LOG_LEVEL=INFO
EOF
sudo chmod 640 /etc/onesimus/onesimus.env
sudo chown root:www-data /etc/onesimus/onesimus.env

onesimus.beispiel.de durch die eigene Domain ersetzen. Die Datei wird von systemd über EnvironmentFile=/etc/onesimus/onesimus.env geladen.

5. Datenbank und statische Dateien

sudo -u www-data .venv/bin/python manage.py migrate
sudo -u www-data .venv/bin/python manage.py collectstatic --noinput

# Ersten Admin-Benutzer anlegen
sudo -u www-data .venv/bin/python manage.py createsuperuser

6. Log-Verzeichnis

sudo mkdir -p /var/log/onesimus
sudo chown www-data:www-data /var/log/onesimus

7. systemd-Service

Unit-Datei aus dem Repository kopieren:

sudo cp contrib/onesimus.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable onesimus
sudo systemctl start onesimus
sudo systemctl status onesimus

Prüfen ob Daphne auf Port 8888 lauscht:

ss -tlnp | grep 8888

8. nginx-Konfiguration

sudo cp contrib/onesimus-web.nginx.conf /etc/nginx/sites-available/onesimus

Datei bearbeiten und onesimus.example.com durch die eigene Domain ersetzen:

sudo nano /etc/nginx/sites-available/onesimus

Site aktivieren:

sudo ln -s /etc/nginx/sites-available/onesimus /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

9. TLS-Zertifikat (Let’s Encrypt)

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d onesimus.beispiel.de

Certbot aktualisiert die nginx-Konfiguration automatisch. Danach nginx neu laden:

sudo systemctl reload nginx

10. Überprüfen

https://onesimus.beispiel.de im Browser öffnen. Die Login-Seite sollte erscheinen.

Mit den Zugangsdaten aus Schritt 5 anmelden. Die App verbindet sich über das Director-Protokoll mit Bareos — Verbindung unter Datei → Verbinden konfigurieren.

Aktualisieren

cd /srv/onesimus-web
sudo -u www-data git pull
sudo -u www-data .venv/bin/pip install -r requirements-prod.txt
sudo -u www-data .venv/bin/python manage.py migrate
sudo -u www-data .venv/bin/python manage.py collectstatic --noinput
sudo chown -R www-data:www-data /srv/onesimus-web /var/log/onesimus
sudo systemctl restart onesimus
sudo nginx -t && sudo systemctl reload nginx

Oder einfach mit dem Makefile:

sudo make update

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Lösung
502 Bad Gateway	Daphne läuft nicht	`systemctl status onesimus`
403 CSRF-Fehler	`CSRF_TRUSTED_ORIGINS` fehlt	`.env` anpassen, Service neu starten
Statische Dateien 404	`collectstatic` nicht ausgeführt	`manage.py collectstatic --noinput`
Login-Weiterleitungsschleife	`DJANGO_ALLOWED_HOSTS` falsch	`.env` prüfen, neu starten
Logs fehlen	Falscher Verzeichnis-Eigentümer	`chown www-data:www-data /var/log/onesimus`

Logs werden nach /var/log/onesimus/onesimus.log geschrieben und automatisch rotiert.

Makefile verwenden

Das Repository enthält ein Makefile, das den gesamten Deployment-Ablauf automatisiert. Repository auf dem Server klonen und ausführen:

Befehl	Was er tut
`sudo make sysdeps`	System-Pakete installieren (apt)
`sudo make install-system`	`/etc/onesimus/onesimus.env`-Vorlage anlegen, systemd-Unit und nginx-Config installieren
`sudo make update`	Code synchronisieren, Abhängigkeiten installieren, migrate, collectstatic, Rechte korrigieren, Service neu starten, nginx neu laden
`make superuser`	Ersten Admin-Benutzer interaktiv anlegen
`sudo make mockdata`	Datenbank mit Testdaten befüllen

Empfohlenes Ersteinrichtungs-Vorgehen:

git clone https://github.com/Beerlesklopfer/onesimus-web.git
cd onesimus-web
sudo make sysdeps
sudo make install-system   # dann /etc/onesimus/onesimus.env bearbeiten
sudo make update
make superuser

Nach dem Bearbeiten von /etc/onesimus/onesimus.env genügt für jedes spätere Update ein einziger Befehl:

sudo make update