dilib_operations/docs/INSTALLATION.md

# Installation (Detailreferenz)

Für die aktuelle vollständige Reihenfolge zuerst **[START_HERE.md](../START_HERE.md)** verwenden.
Nginx wird nicht automatisch installiert; Apache kann alternativ verwendet werden.

# Installation ohne Docker

Ziel: Ubuntu 24.04 LTS, Python 3.12, PostgreSQL und Redis. Andere Python-/OS-Versionen
vorher prüfen. Anforderungen: DNS-Name, TLS-Zertifikat, SMTP optional, ausgehendes
HTTPS von jedem überwachten Host zum Dashboard. Agent benötigt lokalen Brokerzugriff.

## 1. Zentralserver vorbereiten

Projektinhalt nach `/opt/dilib-dashboard` kopieren. Anschließend:

```bash
cd /opt/dilib-dashboard
sudo bash scripts/install-central.sh
sudo -u postgres createuser --pwprompt dilib
sudo -u postgres createdb --owner=dilib dilib_dashboard
sudoedit /etc/dilib-dashboard/dashboard.env
```

Das Skript installiert Pakete und systemd-Dateien, erzeugt zufällige Secrets und
startet die Anwendung noch nicht. Die Datenbankkommandos nur bei einer neuen
Installation ausführen. Vorhandene Datenbanken nicht löschen.

In `dashboard.env` setzen:
- `DATABASE_URL`: tatsächlicher Datenbankbenutzer und Passwort (Sonderzeichen URL-kodieren).
- `ALLOWED_HOSTS`: Domain plus `127.0.0.1,localhost`.
- `CSRF_TRUSTED_ORIGINS`: `https://Ihre-Domain`.
- `CACHE_URL` und `CELERY_BROKER_URL`: getrennte Redis-DBs; nicht mit produktiven Task-Queues teilen.
- `EMAIL_*` und `ALERT_RECIPIENTS`: SMTP und kommaseparierte Empfänger, falls gewünscht.
- `COOKIE_SECURE=1` im TLS-Betrieb belassen.

```bash
sudo bash scripts/manage-env.sh migrate
sudo bash scripts/manage-env.sh createsuperuser
sudo bash scripts/manage-env.sh collectstatic --noinput
sudo systemctl enable --now dilib-api dilib-ui dilib-worker dilib-beat
```

API lauscht nur auf 127.0.0.1:8000, UI auf 127.0.0.1:8080. PostgreSQL und Redis
nicht öffentlich freigeben. Genau eine Beat-Instanz betreiben.

## 2. HTTPS-Reverse-Proxy

Bei Nginx zuvor `sudo apt-get install nginx` ausführen.

Gültiges Zertifikat für die eigene Domain bereitstellen. `deploy/nginx.conf`
nach `/etc/nginx/sites-available/dilib-dashboard` kopieren, Domain und Zertifikatpfade
ersetzen. Die Datei gehört in den üblichen `http`-Include-Kontext von Nginx.

```bash
sudo ln -s /etc/nginx/sites-available/dilib-dashboard /etc/nginx/sites-enabled/dilib-dashboard
sudo nginx -t
sudo systemctl reload nginx
```

Firewall: 443 für Benutzer und Agenten; 80 nur für Redirect bzw. Zertifikatsvalidierung.
Bestehende Nginx-Konfiguration auf Konflikte prüfen. Anmeldung über die eigene Domain.
Benutzer in `/admin/` anlegen: aktive Benutzer lesen, `is_staff` erlaubt Quittierung,
Wartungsmodus, Einstellungen und KI-Analyse. Superuser verwalten Modelle.

## 3. Host registrieren

Auf dem Zentralserver je Host ausführen:

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

Der Befehl zeigt das Agent-Token einmal an. Privat in die Agentkonfiguration übernehmen.
Für Widerruf/Rotation denselben Befehl mit `--rotate` ausführen und Agent aktualisieren.

## 4. Agent auf jedem überwachten Host

Projekt auch dort nach `/opt/dilib-dashboard` kopieren:

```bash
cd /opt/dilib-dashboard
sudo bash scripts/install-agent.sh
sudoedit /etc/dilib-agent/agent.env
sudo systemctl enable --now dilib-agent
sudo journalctl -u dilib-agent -n 50 --no-pager
```

`DASHBOARD_URL=https://Ihre-Domain/api/ingest/`, `AGENT_TOKEN` sowie lokale
`AGENT_HEALTH_URLS` anpassen. JSON in der env-Datei unverändert als eine Zeile eintragen.
Nicht vorhandene Flower-Instanzen durch leeres `AGENT_FLOWER_URL=` deaktivieren.
Interne Zertifizierungsstelle: PEM-Dateipfad in `AGENT_CA_BUNDLE` für Dashboard-Uploads.
Für lokale HTTPS-Gesundheitsprüfungen muss die CA im Systemvertrauen installiert sein.

Pro unabhängigem Celery-Broker genau auf einem Agenten:

```ini
AGENT_COLLECT_EVENTS=1
AGENT_BROKER_URL=redis://127.0.0.1:6379/0
AGENT_COLLECTOR_ID=dilib-monitor-production
```

Auf allen anderen Agenten `AGENT_COLLECT_EVENTS=0`. Für RabbitMQ ist eine passende
`amqp://`-URL möglich. Zugangsdaten nur lokal speichern. Bei mehreren Brokern eigene
Agentinstanzen mit separaten registrierten Namen, Spool-Dateien und Umgebungen anlegen.

In den überwachten Django/Celery-Projekten (bei Namespace CELERY) konfigurieren:

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

Anschließend dortige Worker regulär neu starten. Alternativ Worker mit `-E` starten.
Der Agent aktiviert Events nicht eigenständig per Remote-Control.

## 5. Flower dauerhaft speichern

Bestehendes Flower mit `deploy/flowerconfig.py` konfigurieren oder den mitgelieferten
Dienst nutzen. Nur eine Flower-Instanz darf dieselbe Zustandsdatei schreiben.

```bash
cd /opt/dilib-dashboard
sudo .venv-agent/bin/pip install 'flower==2.2.0'
sudo install -m 640 -o root -g dilib-agent deploy/flower.env.example /etc/dilib-agent/flower.env
sudoedit /etc/dilib-agent/flower.env
sudo install -m 644 deploy/systemd/dilib-flower.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now dilib-flower
```

Broker und `FLOWER_BASIC_AUTH` setzen. Im Agenten dieselben Flower-Zugangsdaten setzen.
Flower bindet auf 127.0.0.1:5555, speichert alle 10 Sekunden unter
`/var/lib/dilib-flower/flower` und hält maximal 100.000 Tasks im lokalen Zustand.
Diese Dateipersistenz ist unabhängig von der PostgreSQL-Aufbewahrung des Dashboards.
Nach Änderung `sudo systemctl restart dilib-agent` ausführen.

## 6. dilibAI optional

`DILIBAI_BASE_URL` inklusive API-Präfix (z.B. `https://ki.intern/v1`),
`DILIBAI_API_KEY` und `DILIBAI_MODEL` setzen; API-Dienst neu starten.
Der Adapter sendet maximal 30 offene Alarmzusammenfassungen an `/chat/completions`.
Ein proprietärer dilibAI-Endpunkt benötigt eine Anpassung von `monitoring/views.py`.
Es werden keine Task-Argumente oder Ergebnisse übertragen. KI führt keine Aktionen aus.

## Lokaler Entwicklungstest

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest -q
```

Die Tests verwenden SQLite und ersetzen externe Dienste durch Mocks.
Für eine manuelle lokale Demo `.env.example` nach `.env` kopieren, Secrets generieren,
`TEST_SQLITE=1`, `COOKIE_SECURE=0` und `DEBUG=1` ergänzen; `var` anlegen.
Mit `.venv/bin/python manage.py migrate`, `createsuperuser` und `seed_demo` vorbereiten.
In zwei Terminals `manage.py runserver 127.0.0.1:8000` und
`.venv/bin/python -m frontend.main` starten. UI: http://127.0.0.1:8080.
Demo-Daten nie in die produktive Datenbank laden.