Fix device issues and document current LAN deployment
This commit is contained in:
240
docs/LOCAL_DEPLOY.md
Normal file
240
docs/LOCAL_DEPLOY.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user