dilib_operations/START_HERE.md

# dilib Operations 1.1 – vollständiges Projekt

Die Anwendung läuft mit Django, PostgreSQL, Celery, Redis, Flower und NiceGUI.
Der gesamte Betrieb erfolgt ohne Docker. Nginx oder Apache liefert HTTPS und die
WebSocket-Verbindung zur Oberfläche; Certbot kann Zertifikate einrichten.

## 1. Dateien auf den Zentralserver kopieren

Das Archiv enthält `dilib_dashboard/`. Diesen Ordner nach `/opt/dilib-dashboard`
kopieren. Zielsystem für die Installationsskripte: Ubuntu 24.04 mit Python 3.12.

```bash
cd /opt/dilib-dashboard
sudo bash scripts/install-central.sh
sudo .venv/bin/python scripts/configure.py --domain dashboard.example.com
```

`dashboard.example.com` durch die eigene Domain ersetzen. Der Installer legt eine
virtuelle Umgebung, Dienstbenutzer, Konfigurationsdatei und systemd-Dienste an.
Er installiert keinen konkurrierenden Webserver und startet die Anwendung noch nicht.

## 2. PostgreSQL und Konfiguration

Für eine neue Datenbank:

```bash
sudo systemctl enable --now postgresql redis-server
sudo -u postgres createuser --pwprompt dilib
sudo -u postgres createdb --owner=dilib dilib_dashboard
sudoedit /etc/dilib-dashboard/dashboard.env
```

`DATABASE_URL` mit dem gesetzten Passwort eintragen (URL-Sonderzeichen kodieren).
`ALLOWED_HOSTS` und `CSRF_TRUSTED_ORIGINS` setzt configure.py anhand der Domain.
Redis DB 5 und 6 sind voreingestellt und müssen frei bzw. für dieses Projekt vorgesehen sein.
Optional SMTP-Einstellungen und Empfänger setzen. Bei externer DB entsprechend eigene
Verbindung konfigurieren und die beiden createuser/createdb-Befehle auslassen.

```bash
sudo bash scripts/finalize-install.sh
sudo bash scripts/manage-env.sh createsuperuser
```

Dies führt Migrationen aus, sammelt statische Dateien, prüft DB/Redis/Broker und
startet API, UI, Celery-Worker und Beat. `doctor --workers` prüft danach die Antwort
mindestens eines Workers. Es ist kein umfassender Last- oder Verfügbarkeitstest.

## 3. Webserver – eine Variante auswählen

### Nginx

```bash
sudo apt-get install nginx certbot python3-certbot-nginx
.venv/bin/python scripts/render-proxy.py --domain dashboard.example.com --server nginx --output dashboard.conf
sudo install -m 644 dashboard.conf /etc/nginx/conf.d/dilib-dashboard.conf
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d dashboard.example.com
```

Bei noch nicht gestartetem Nginx `sudo systemctl start nginx` verwenden.

### Bestehender Apache

```bash
sudo apt-get install certbot python3-certbot-apache
sudo a2enmod proxy proxy_http headers alias
.venv/bin/python scripts/render-proxy.py --domain dashboard.example.com --server apache --output dashboard-apache.conf
sudo install -m 644 dashboard-apache.conf /etc/apache2/sites-available/dilib-dashboard.conf
sudo a2ensite dilib-dashboard.conf
sudo apache2ctl configtest
sudo systemctl reload apache2
sudo certbot --apache -d dashboard.example.com
```

Apache mindestens 2.4.47. Nur einen Webserver für dieselbe IP/Port-Kombination verwenden.
DNS/AAAA auf den richtigen Server richten; Ports 80/443 freigeben. API/UI-Ports sind
nur lokal gebunden. Sichere Cookies sind aktiviert: Anmeldung nach TLS-Einrichtung
über `https://dashboard.example.com`. Unverschlüsseltes HTTP dient hier nur dem Setup.

## 4. Überwachte Hosts hinzufügen

Auf dem Zentralserver:

```bash
sudo bash scripts/manage-env.sh register_agent app-01 --segment Produktion --address 10.10.1.20
```

Token privat übernehmen. Auf dem überwachten Host Projekt nach `/opt/dilib-dashboard`
kopieren und ausführen:

```bash
cd /opt/dilib-dashboard
sudo bash scripts/install-agent.sh
sudoedit /etc/dilib-agent/agent.env
sudo systemctl enable --now dilib-agent
```

`AGENT_TOKEN`, `DASHBOARD_URL=https://dashboard.example.com/api/ingest/` und lokale
Dienst-Health-URLs setzen. Ohne Flower dort `AGENT_FLOWER_URL=` leeren.
Je unabhängigem Broker exakt einen Event-Collector einschalten:
`AGENT_COLLECT_EVENTS=1`, Broker-URL und eindeutige Collector-ID setzen.
Alle übrigen Host-Agenten bleiben ohne Event-Collector.

Die überwachten Celery-Projekte benötigen aktivierte Events:

```python
CELERY_WORKER_SEND_TASK_EVENTS = True
CELERY_TASK_SEND_SENT_EVENT = True
CELERY_TASK_TRACK_STARTED = True
```

Diese Namen gelten für Django mit dem Namespace `CELERY`. Worker danach regulär
neu starten. Bei nicht namespaced Celery-Konfiguration die klein geschriebenen Namen nutzen.

## 5. Flower je Cluster einrichten

Auf dem ausgewählten Agent-Host:

```bash
sudo bash scripts/install-flower.sh
sudoedit /etc/dilib-agent/flower.env
sudo systemctl enable --now dilib-flower
```

Broker-URL und `FLOWER_BASIC_AUTH=monitor:LANGES-ZUFAELLIGES-PASSWORT` setzen.
Dieselben Flower-Zugangsdaten in agent.env übernehmen, dann Agent neu starten.
Flower lauscht nur auf localhost:5555. Für direkte Bedienung einen SSH-Tunnel nutzen:

```bash
ssh -L 5555:127.0.0.1:5555 BENUTZER@AGENT-HOST
```

Dann `http://127.0.0.1:5555` öffnen. Existiert bereits Flower, entweder dieses mit
Persistenz konfigurieren oder den neuen Dienst verwenden; keine doppelte Portbelegung.
Flower schreibt seinen Zustand unter `/var/lib/dilib-flower/`; PostgreSQL speichert
parallel die zentrale Ereignishistorie. Das Dashboard rekonstruiert nicht Flowers UI.

## 6. Sicherung und Abnahme

Für die lokale Standarddatenbank ist ein täglicher Backup-Timer vorbereitet:

```bash
sudo systemctl enable --now dilib-backup.timer
sudo systemctl start dilib-backup.service
sudo systemctl list-timers dilib-backup.timer
```

Dumps liegen in `/var/lib/postgresql/dilib-backups`. Der Timer gilt nur für die lokale
DB `dilib_dashboard`, läuft um 02:15 Uhr in der Serverzeitzone mit bis zu 10 Minuten
Zufallsversatz und löscht keine Backups. Externe Kopie, Speicherüberwachung und
Backup-Aufbewahrung betreiberseitig ergänzen. Für externe DB den Backupdienst anpassen.

Danach `docs/OPERATIONS.md` abarbeiten: echte Tasks, Netzunterbrechung, Neustart,
SMTP und Restore prüfen. Rollen: aktive Benutzer lesen, Staff-Benutzer bedienen,
Superuser verwalten. Alle Benutzer sehen alle Segmente; keine Mandantentrennung.