# 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:

```sh
ssh inventar@192.168.178.17
```

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

```sh
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
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.

```sh
(
  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

```sh
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:

```sh
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:

```sh
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:

```powershell
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:

```sh
python3 scripts/renew_local_tls.py --hostname 192.168.178.17
```

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

```sh
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
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.