# Linux-Betrieb

API und Analyseworker laufen als getrennte systemd-Dienste. Ein Auftragseingang
weckt keinen neuen Prozess: Der dauerhaft laufende Worker übernimmt Inbox-Aufträge.
Die Weboberfläche ist eine alternative Bedienung desselben Arbeitsablaufs.
Die Installation startet keine Dienste und führt keine Modellanfrage aus.

## Voraussetzungen und Verzeichnisse

Linux mit systemd, Python 3.11 oder neuer inklusive venv/pip, Git und Nginx.
Diese Programme über die Paketverwaltung des Servers installieren. Die aktuelle
Projektvorlage ist für WoW/Vcore eingerichtet; sie ist kein allgemeiner Adapter.

| Pfad | Zweck und Rechte |
| --- | --- |
| `/opt/viano-bug-analysis` | Root-eigener Checkout und virtuelle Python-Umgebung; Dienst darf nur lesen |
| `/etc/viano-bug-analysis` | Root-eigene Konfiguration, Gruppe `buganalysis`, Verzeichnis 0750, Dateien 0640 |
| `/etc/viano-bug-analysis/*.env` | Zugangsdaten, root:buganalysis 0600; systemd liest sie vor dem Benutzerwechsel |
| `/etc/viano-bug-analysis/auth/users.sqlite3` | Root-verwaltete Nutzer, Gruppe `buganalysis` darf lesen |
| `/var/lib/viano-bug-analysis` | Dienst-eigene Fallakten, Laufzeitdaten und Websessions |
| `/srv/viano-bug-analysis/viano-core` | Root-eigener Source-Checkout, Dienst hat Leserechte |

Die env-Dateien sind durch Betriebssystemrechte geschützte Klartextdateien, kein
verschlüsselter Tresor. Sie gehören nicht ins Repository oder in Diagnosepakete.
API und Worker erhalten unterschiedliche Dateien: Nur der Worker erhält Cloud-
und DB-Zugangsdaten. Die Diensthärtung und EnvironmentFile-Nutzung folgen der
[systemd-Dokumentation](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html).

Die [Webverwaltung für Integrationsschlüssel](integration-keys.md) ergänzt die
env-basierte Maschinenanmeldung. Ihre SQLite und separate Schlüsseldatei müssen
ebenfalls gesichert werden; beide liegen standardmäßig unter der Fallablage.

## Installation

Den vertrauenswürdigen BugAnalysis-Checkout als root unter
`/opt/viano-bug-analysis` ablegen. Code und Unterverzeichnisse dürfen nicht für
andere Benutzer schreibbar sein. Dann:

```sh
cd /opt/viano-bug-analysis
python3 deploy/install.py --dry-run
sudo python3 deploy/install.py
```

Der Installer legt den Dienstbenutzer `buganalysis`, Konfigurationen, venv und
Units an. Er installiert die Python-Abhängigkeiten und lädt systemd neu.
Bestehende Zielkonfigurationen und Units werden erhalten. Updates an bereits
installierten Units daher bewusst mit den versionierten Vorlagen abgleichen.
Bei Installationsfehlern bleiben vorhandene Dateien erhalten; erneutes Ausführen
setzt die Einrichtung fort. Der Installer verändert keine bestehende Datenbank.

## Einmalige Konfiguration

Mit `sudoedit` die Dateien unter `/etc/viano-bug-analysis` bearbeiten:

1. `project.toml`: DB-Adresse/Port, Datenbank und nur lesenden Benutzer einstellen,
   tatsächliche Snapshotkennung und vollständigen Source-Commit eintragen.
   Die ausgelieferten Null-Commit- und `CONFIGURE_ME`-Werte sind Platzhalter.
2. Den Vcore-Checkout als root unter `/srv/viano-bug-analysis/viano-core` anlegen;
   der konfigurierte Commit muss lokal vorhanden und für `buganalysis` lesbar sein.
   Der Dienst lädt keine Commits nach. `gitconfig` vertraut ausschließlich diesem
   konkreten Root-Checkout, nicht beliebigen Repositories.
3. `worker.env`: `GEMINI_API_KEY=...` und `VIANO_DB_PASSWORD=...` eintragen.
   Keine `export`-Anweisungen verwenden. Für Sonderzeichen gelten die
   EnvironmentFile-Quotingregeln von systemd. Werte nicht als Shellargumente übergeben.
4. `api.env`: `VBA_INTAKE_TOKEN=...` für den Erfassungsworker setzen
   (32–256 Zeichen aus Buchstaben, Ziffern, `_` und `-`). Dies ist ein separater
   Integrationsschlüssel, kein Gemini-Key. Wird keine externe API-Integration
   benötigt, den zugehörigen `[[clients]]`-Block aus `api.toml` entfernen.
5. `llm.toml`: gewünschtes Modell, Anbieter und Cacheeinstellungen kontrollieren.
   Investigation-, Budget- und Telemetrie-Dateien sind separat konfigurierbar.

Die DB-Verbindung benötigt einen Benutzer mit ausschließlich passenden
SELECT-Rechten auf die freigegebenen World-Tabellen. Diese Rechte legt der
DB-Administrator an; BugAnalysis vergibt keine Grants. Der Readiness-Test belegt
Lesbarkeit, nicht die Abwesenheit zusätzlicher Schreibrechte. Für entfernte DBs
einen geschützten Netzwerkweg verwenden: Der aktuelle DB-Provider konfiguriert
selbst kein TLS. Zugang zu Produktionsdaten ist für die lokale Entwicklung
weiterhin nicht erforderlich.

Webnutzer anlegen; das Passwort wird verdeckt abgefragt:

```sh
sudo /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.api create_user NAME --config /etc/viano-bug-analysis/api.toml --service-group buganalysis
```

Nutzerverwaltung bleibt root vorbehalten. Siehe [Nutzerverwaltung](user-accounts.md).
Keine Nutzer werden automatisch angelegt. Nach der Installation besitzen die
env-Dateien Modus 0600; diese Rechte nach manuellen Änderungen erhalten.

## Kostenfreie Bereitschaftsprüfung

Die Prüfung unter der tatsächlichen Dienstidentität samt env-Datei ausführen:

```sh
sudo systemd-run --wait --pipe --collect --property=User=buganalysis --property=Group=buganalysis --property=EnvironmentFile=/etc/viano-bug-analysis/api.env /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check --role api --config /etc/viano-bug-analysis/api.toml
sudo systemd-run --wait --pipe --collect --property=User=buganalysis --property=Group=buganalysis --property=EnvironmentFile=/etc/viano-bug-analysis/worker.env --setenv=GIT_CONFIG_GLOBAL=/etc/viano-bug-analysis/gitconfig /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.deployment check --role worker --config /etc/viano-bug-analysis/worker.toml
```

Erwartet: `READY`, `model_requests: 0`. Geprüft werden Konfiguration,
Zugangsdaten-Präsenz, Speicherreserve, Schreibbarkeit der Laufzeitablage,
Webnutzer/Sessions beziehungsweise Git-Objekte und die freigegebenen DB-Schemata.
Cloud-Key-Gültigkeit und Modellverfügbarkeit sind damit noch nicht getestet.
`--offline` überspringt Git-/DB-Zugriffe und meldet nur `CONFIG_READY`.
Fehlerausgaben enthalten kontrollierte Fehlercodes statt Zugangsdaten.

## HTTPS und Start

Die API bleibt auf `127.0.0.1:8080`. `nginx.conf.example` enthält eine
Reverse-Proxy-Vorlage: Domain und Zertifikatpfade anpassen, gültiges Zertifikat
bereitstellen und als Nginx-Site installieren. Die Vorlage übernimmt die
Forwarded-Header kontrolliert; die API vertraut ihnen ausschließlich vom
Loopback-Proxy. So verwenden Anmeldung und Cookies das öffentliche HTTPS-Schema.
Die Proxyparameter sind in der
[Nginx-Dokumentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) beschrieben.

Vor dem ersten Start auf dem Linux-Zielsystem prüfen:

```sh
sudo systemd-analyze verify /etc/systemd/system/viano-bug-analysis-api.service /etc/systemd/system/viano-bug-analysis-worker.service
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl enable --now viano-bug-analysis-api.service viano-bug-analysis-worker.service
sudo systemctl status viano-bug-analysis-api.service viano-bug-analysis-worker.service
```

Sobald der Worker aktiviert ist, kann er vorhandene Aufträge verarbeiten und
kostenpflichtige Modellaufrufe senden. Erst mit leerem Eingang starten, dann einen
kontrollierten Feldtest über die Übergabe-API oder Weboberfläche übergeben.
Anmeldung, Auftragsannahme, Fortschritt, menschliche Testanfrage und Outbox dabei
gemeinsam prüfen. Die automatisierte Einrichtung ersetzt diesen Feldtest nicht.

## Laufender Betrieb

Die Dienste starten beim Booten und nach unerwartetem Prozessende erneut.
Fehlende Startvoraussetzungen werden nach zehn Sekunden erneut geprüft.
Externe DB und Sourcebereitstellung werden nicht von diesen Units installiert.
API und Worker können unabhängig voneinander laufen.

```sh
sudo journalctl -u viano-bug-analysis-api -u viano-bug-analysis-worker -f
sudo systemctl stop viano-bug-analysis-worker
```

Der Worker beendet beim Stoppen den aktuellen Dispatch kontrolliert; seine Unit
setzt dafür kein hartes Stop-Zeitlimit. Ein Stop kann daher während einer
langlaufenden Anfrage dauern. Für Code-/Profiländerungen den Worker zuerst
anhalten. Profilbindungen laufender Fälle nicht beiläufig ändern: Unterschiede
werden als Aufmerksamkeit erfordernder Zustand behandelt, Budgets nicht erneuert.
Codeänderungen danach in die root-eigene venv installieren und Dienste neu starten.

Backups umfassen die Fallablage, Konfiguration einschließlich geschützter Secrets
und Nutzer-SQLite. Für eine einfache konsistente Dateisicherung beide Dienste
anhalten. Sessions sind keine dauerhaft nötigen Fachdaten. Produktive Fallaufbewahrung
separat festlegen; das 20-GB-Entwicklungslimit ist kein Produktionslimit.

Unter Windows bleibt die vorhandene PowerShell-Umgebungsvariable für Entwicklung
unterstützt. Dort installiert dieser Installer keine Dienste; `--dry-run` ist möglich.