241 lines
9.4 KiB
Markdown
241 lines
9.4 KiB
Markdown
# 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 | `denis` |
|
|
| 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 denis@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/denis/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 | `denis` |
|
|
| 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.
|