Inventory/docs/LOCAL_DEPLOY.md

Lokales Deployment der Inventarverwaltung

Diese Anleitung enthält die benötigten Schritte für Kollegen, die die bestehende LAN-Installation aktualisieren oder administrativ auf die Datenbank zugreifen.

Zugang

Zweck	Adresse / Wert
Anwendung	https://192.168.178.17/
Anmeldung	https://192.168.178.17/accounts/login/
SSH-Server	192.168.178.17, Port 22
SSH-Benutzer	inventar
Projektverzeichnis	/home/inventar/inventar
Git-Branch	master
Dienste	web (Django), db (PostgreSQL), traefik (HTTPS)

Voraussetzung ist Zugang zum Servernetz sowie ein freigegebener SSH-Zugang. Anmeldedaten und gegebenenfalls die benötigten Administratorrechte bei der zuständigen Administration anfordern. Anwendungskonto, SSH-Zugang und Datenbankpasswort sind getrennt.

Installation aktualisieren

Ein kurzes Wartungsfenster einplanen: Beim Neustart ist die Anwendung vorübergehend nicht erreichbar. Bei einem Fehler zuerst dessen Ursache klären; nicht mit dem nächsten Schritt fortfahren.

1. Auf dem Server anmelden

Im Terminal des eigenen Arbeitsplatzes:

ssh inventar@192.168.178.17

Alle folgenden Shell-Befehle werden auf dem Server ausgeführt:

cd /home/inventar/inventar
pwd
git status --short --branch
git branch --show-current
docker compose ps
docker compose config --quiet

Erwartet werden Branch master und die Dienste db, web, traefik. config --quiet prüft die Compose-Konfiguration, ohne die aufgelösten Passwörter auszugeben. Docker und Git müssen mit einem dafür berechtigten Konto bedient werden. Falls dafür eine Root-Sitzung vorgesehen ist, su - ausführen und danach erneut cd /home/inventar/inventar eingeben.

Lokale Änderungen vor dem Update klären. Nicht mit git reset --hard oder git clean entfernen. Eine lokale docker-compose.override.yml kann zur Serverkonfiguration gehören und muss erhalten bleiben.

2. Backup erstellen

sh scripts/backup.sh
git rev-parse HEAD

Das Skript erstellt und prüft eine komprimierte PostgreSQL-Sicherung unter /home/inventar/inventar/backups/. Es meldet den genauen Dateinamen. Diesen zusammen mit der ausgegebenen Git-Revision für eine mögliche Wiederherstellung notieren. Nur nach erfolgreicher Sicherung fortfahren.

Das Skript sichert ausschließlich die Datenbank. .env, die lokale Compose-Konfiguration, tls/ und die Uploads im Docker-Volume media_data gehören ebenfalls zur Installation und müssen separat geschützt gesichert werden. Regelmäßige Sicherungen zusätzlich auf einem anderen System aufbewahren.

3. Aktualisieren und starten

Den gesamten Block im Projektverzeichnis ausführen. Bei einem Fehler beendet set -eu den Block, bevor weitere Schritte ausgeführt werden.

(
  set -eu
  git pull --ff-only origin master
  docker compose config --quiet
  docker compose build web
  docker compose up -d --wait --wait-timeout 180 web traefik
)

--ff-only verhindert unbeabsichtigte Merge-Commits auf dem Server. Meldet Git abweichende lokale Änderungen oder eine abweichende Historie, diese mit der Administration klären.

Beim Web-Containerstart werden Datenbankmigrationen automatisch angewendet, Auswahlwerte ergänzt und statische Dateien gesammelt. Ein zusätzliches python manage.py migrate auf dem Host ist nicht nötig. Migration 0014 ergänzt Kamera/Sound für Laptop und AiO sowie Monitoranschlüsse und Seitenverhältnis. Bestehende Anschlussnotizen bleiben erhalten; neue JA/NEIN-Felder beginnen mit „UNBEKANNT“.

.env, Zertifikate und persistente Volumes bei Updates beibehalten. Kein docker compose down -v verwenden: Dieser Befehl löscht die Datenbank- und Upload-Volumes.

4. Update prüfen

docker compose ps
docker compose logs --tail 100 web traefik
docker compose exec -T web python manage.py check --deploy
docker compose exec -T web python manage.py migrate --check
docker compose exec -T web python manage.py showmigrations inventory
curl --fail --show-error --cacert tls/ca/root.crt https://192.168.178.17/health/

Erwartet werden gesunde Dienste, keine ausstehenden Migrationen und ein erfolgreicher Healthcheck. Angewendete Migrationen tragen in der Liste [X]; für diesen Stand muss auch 0014 markiert sein. Warnungen und Fehler vor dem Abschluss des Updates prüfen.

Anschließend im Browser anmelden und prüfen:

• Geräteliste und ein bestehendes Gerät öffnen sich mit den gespeicherten Daten.
• Die Liste lässt sich auch im kleinen Fenster scrollen.
• Benutzerdefinierte Spalten und gespeicherte JA/NEIN-Werte erscheinen korrekt.
• Hardwarefelder passen zum Gerätetyp; Monitoranschlüsse lassen sich filtern.
• Ablauf, Aufgaben und Archiv öffnen sich.

Für fortlaufende Logs:

docker compose logs -f web

Mit Strg+C nur die Logansicht beenden; die Container laufen weiter. Den eingesetzten Git-Stand und das Prüfergebnis im Betriebsprotokoll festhalten.

HTTPS und Zertifikate

Der Browser muss der lokalen Zertifizierungsstelle vertrauen. Das aktuelle öffentliche Stammzertifikat liegt bei der LAN-Konfiguration auf dem Server unter /home/inventar/inventar/tls/ca/root.crt. Eine bestätigte Kopie von der Administration beziehen. Nicht ungeprüft die CA einer früheren Installation verwenden und niemals den privaten Schlüssel root.key verteilen.

Den SHA-256-Fingerabdruck auf dem Server anzeigen und mit der Administration abgleichen:

openssl x509 -in tls/ca/root.crt -noout -subject -dates -fingerprint -sha256

Auf einem Windows-Arbeitsplatz die bestätigte Datei als root.crt speichern und in PowerShell aus deren Verzeichnis importieren:

Import-Certificate -FilePath .\root.crt -CertStoreLocation Cert:\CurrentUser\Root

Browser anschließend neu starten. Browser mit eigenem Zertifikatsspeicher benötigen den Import dort ebenfalls. Bleibt eine Warnung bestehen, zusätzlich prüfen, ob das Serverzertifikat für 192.168.178.17 ausgestellt wurde.

Die TLS-Routine lässt sich im Projektverzeichnis durch ein berechtigtes Konto aufrufen:

python3 scripts/renew_local_tls.py --hostname 192.168.178.17

Bei eingerichteter automatischer Erneuerung die tatsächlich installierte Unit kontrollieren:

systemctl cat csr-inventory-tls.service
systemctl list-timers csr-inventory-tls.timer
journalctl -u csr-inventory-tls.service --no-pager

Die mitgelieferte Service-Vorlage enthält noch den früheren Pfad /home/inventar/csr-inventory. Bei ihrer Installation WorkingDirectory, EnvironmentFile und ExecStart auf /home/inventar/inventar anpassen. Die Server-.env muss APP_HOST=192.168.178.17 enthalten; ebenso müssen ALLOWED_HOSTS und CSRF_TRUSTED_ORIGINS die aktuelle Adresse berücksichtigen.

Fehlerbehebung und Wiederherstellung

Problem	Nächster Schritt
SSH nicht erreichbar	Servernetz/VPN, IP und Port 22 prüfen.
Docker-Zugriff verweigert	Berechtigtes Verwaltungskonto verwenden; nach einem Benutzerwechsel wieder ins Projektverzeichnis wechseln.
Git-Update scheitert	git status prüfen und lokale Änderungen mit der Administration klären.
Start dauert länger als 180 Sekunden	Logs prüfen; das Zeitlimit allein sagt nicht, ob Migrationen bereits angewendet wurden.
Migration oder Webstart scheitert	docker compose logs --tail 200 web db prüfen; Datenbank und Volumes erhalten.
HTTPS/Anmeldung schlägt fehl	Zertifikatsvertrauen und aktuelle IP in .env prüfen.
Oberfläche zeigt alte Dateien	Erfolgreichen Build prüfen und Browser vollständig neu laden.

Ein einfaches Zurücksetzen des Codes macht bereits ausgeführte Datenbankmigrationen nicht rückgängig. Für eine Wiederherstellung müssen Git-Revision, Datenbanksicherung und Konfiguration zusammenpassen.

scripts/restore.sh erwartet eine leere Zieldatenbank und überschreibt bestehende Tabellen nicht. Eine Sicherung zuerst in einer getrennten Testinstanz mit eigenen Volumes und eigener Konfiguration prüfen. Dort lautet der Aufruf mit dem tatsächlich ausgewählten Dateinamen:

sh scripts/restore.sh backups/backup_DATUM_UHRZEIT.sql.gz

Eine produktive Wiederherstellung mit der Administration abstimmen; Änderungen seit dem Backup können verloren gehen. Keine produktive Datenbank für einen Restore-Test löschen.

Datenbankzugriff mit DBeaver

PostgreSQL wird auf dem Server ausschließlich an 127.0.0.1:15432 gebunden. Für DBeaver eine PostgreSQL-Verbindung mit diesen Angaben anlegen:

Einstellung	Wert
Datenbankhost	127.0.0.1
Datenbankport	15432
Datenbank	csr_inventory oder POSTGRES_DB aus .env
Datenbankbenutzer	csr_inventory oder POSTGRES_USER aus .env
Datenbankpasswort	POSTGRES_PASSWORD aus der geschützten Server-.env
SSH-Tunnel	aktivieren
SSH-Host / Port	192.168.178.17 / 22
SSH-Benutzer	inventar
SSH-Authentifizierung	freigegebener SSH-Schlüssel oder SSH-Passwort

Die Verbindung über die Host-Felder konfigurieren, nicht über eine abweichende fest eingetragene JDBC-URL. Der SSH-Tunnel erreicht den lokalen Datenbankport; eine direkte LAN-Freigabe für PostgreSQL ist nicht erforderlich.

Das Datenbankpasswort steht in /home/inventar/inventar/.env und ist getrennt vom SSH-Passwort. Nur berechtigte Administratoren sollen diese Datei einsehen. Passwörter nicht in Screenshots, Tickets oder Git übernehmen. Normale Gerätepflege erfolgt über die Anwendung, damit Rechteprüfung und Änderungshistorie erhalten bleiben.