diff --git a/README.md b/README.md index ee6d32e..f8bd734 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,313 @@ # VianoBugAnalysis +BugAnalysis untersucht gemeldete Softwarefehler anhand von Diagnosepaketen, +Sourcecode und lesenden Datenbankabfragen. Ein dauerhaft laufender Worker erstellt +Diagnosen und Aufträge für Codingagenten beziehungsweise menschliche Entwickler. +Die Weboberfläche bietet Benutzeranmeldung, Betriebsübersicht, Testerantworten, +API-Schlüssel und Paketdownloads. Das aktuelle Projektprofil ist für WoW/Vcore +ausgelegt. BugAnalysis installiert selbst keine Bugfixes auf dem Spielserver. + +## Installation auf einem Linux-VPS + +Diese Anleitung ist direkt auf der Repository-Startseite lesbar. Sie setzt einen +Linux-Server mit systemd und einen SSH-Zugang mit sudo-Rechten voraus. Die +Paketbefehle unten gelten für Debian/Ubuntu; auf anderen Distributionen die +entsprechenden Pakete installieren. **Python 3.11 oder neuer ist erforderlich.** + +### 1. Voraussetzungen installieren + +```sh +sudo apt-get update +sudo apt-get install python3 python3-venv python3-pip git nginx ca-certificates curl +python3 --version +``` + +Ist die Python-Version älter als 3.11, zuerst eine unterstützte Python-Version +bereitstellen und diese für den Installer verwenden. Datenbankserver und +World-Daten werden vom Installer nicht eingerichtet oder importiert. Ein +erreichbarer MariaDB-Datenbestand für die Recherche muss separat vorhanden +sein, beispielsweise eine isolierte Testdatenbank aus einem Backup. + +### 2. Repository in das vorgesehene Verzeichnis klonen + +**Der Installer und die systemd-Units erwarten derzeit genau +`/opt/viano-bug-analysis`.** Nicht einen beliebigen Ordnernamen verwenden. +Git legt den Zielordner an; er muss dafür noch nicht existieren oder leer sein. + +```sh +sudo git clone https://gitea.viano-software.de/Nico/VianoBugAnalysis /opt/viano-bug-analysis +cd /opt/viano-bug-analysis +``` + +Das Klonen mit sudo erzeugt einen root-eigenen Checkout. Der Installer verlangt, +dass Programmdateien root gehören und weder für Gruppe noch andere Benutzer +schreibbar sind. Bei einem privaten Repository die Git-Anmeldung interaktiv +durchführen; keine Zugangsdaten in die URL schreiben. + +### 3. Installationsplan prüfen und installieren + +```sh +python3 deploy/install.py --dry-run +sudo python3 deploy/install.py +``` + +Der erste Befehl zeigt nur den Plan. Der zweite erstellt den Dienstbenutzer +`buganalysis`, die virtuelle Python-Umgebung, Konfigurationsvorlagen und beide +systemd-Units. Er startet oder aktiviert noch keinen Dienst und sendet keine +LLM-Anfrage. Vorhandene Konfigurationsdateien und Units werden nicht überschrieben. + +| Verzeichnis | Inhalt | +| --- | --- | +| `/opt/viano-bug-analysis` | Programmcode und `.venv`; root-verwaltet | +| `/etc/viano-bug-analysis` | Konfiguration, geschützte Environment-Dateien und Webnutzerdatei | +| `/var/lib/viano-bug-analysis` | Fallakten, Inbox, Outbox, Review und Laufzeitdaten | +| `/srv/viano-bug-analysis/viano-core` | Separater Source-Checkout des untersuchten Vcore-Projekts | + +Der Linux-Dienstbenutzer ist kein Webkonto. Webkonten werden in Schritt 6 +gesondert angelegt. Ein Programm zur automatischen Erfassung benötigt später +einen Integrationsschlüssel, ebenfalls kein Webpasswort oder Cloud-API-Key. + +### 4. Vcore-Sourcecode und lesenden Datenbankzugang bereitstellen + +BugAnalysis benötigt zusätzlich zu seinem eigenen Repository den Sourcecode des +untersuchten Projekts. Für Vcore beispielsweise: + +```sh +sudo git clone --branch master --single-branch https://gitea.viano-software.de/Nico/Viano-Core /srv/viano-bug-analysis/viano-core +sudo git -C /srv/viano-bug-analysis/viano-core rev-parse HEAD +``` + +Die Ausgabe des zweiten Befehls ist der vollständige Commit. Der für die Analyse +gewünschte Stand muss lokal vorhanden sein und wird in `project.toml` festgelegt. +Der aktuelle Branchkopf ist nur dann passend, wenn genau dieser Stand untersucht +werden soll. Der Worker klont oder aktualisiert den Sourcecode nicht automatisch. + +Ein DB-Administrator richtet einen Benutzer mit ausschließlich passenden +SELECT-Rechten auf die World-Daten ein. Keine Schreibrechte und keinen +allgemeinen Administrationszugang verwenden. Für entfernte Datenbanken einen +geschützten Netzwerkweg bereitstellen; der aktuelle DB-Provider richtet selbst +kein TLS ein. Die vollständige Tabellenfreigabe steht in der Projektvorlage. + +### 5. Konfigurationen und Zugangsdaten eintragen + +Die Konfiguration liegt außerhalb des Git-Checkouts. Beispiele öffnen: + +```sh +sudoedit /etc/viano-bug-analysis/api.toml +sudoedit /etc/viano-bug-analysis/project.toml +sudoedit /etc/viano-bug-analysis/llm.toml +sudoedit /etc/viano-bug-analysis/worker.env +``` + +| Datei | Beim ersten Einrichten prüfen | +| --- | --- | +| `api.toml` | Projekt-ID, Profilzuordnung und Konfigurationspfade; HTTP-Bindung auf `127.0.0.1:8080` lassen | +| `project.toml` | Sourcepfad und vollständigen Commit, DB-Host/Port/Name/Benutzer, Snapshotkennung und Tabellenfreigaben | +| `llm.toml` | Anbieter, tatsächlich verfügbares Modell, Cache- und Timeout-Einstellungen; verwendete Schlüssel-Umgebungsvariable | +| `worker.env` | Cloud-API-Key und DB-Passwort | +| `worker.toml` | Verweis auf `api.toml`, Polling und Speicherreserve; Vorgaben zunächst übernehmen | +| `investigation.bounded.toml`, `budget.human-tests.toml` | Untersuchungs- und Budgetregeln; Vorgaben zunächst übernehmen | +| `telemetry.toml` | Betriebsbeobachtung; Vorgaben zunächst übernehmen | + +In `project.toml` die Null-Commit- und `CONFIGURE_ME`-Platzhalter ersetzen. Die +vollständige Vorlage mit Relations-, Enrichment- und Werkzeugregeln beibehalten; +die Projektdatei nicht auf DB-Adresse und Sourcepfad zusammenkürzen. + +Bei Verwendung der gelieferten Gemini-/DB-Vorlagen enthält `worker.env`: + +```text +GEMINI_API_KEY="HIER_DEN_CLOUD_API_KEY_EINTRAGEN" +VIANO_DB_PASSWORD="HIER_DAS_DB_PASSWORT_EINTRAGEN" +``` + +Das sind Platzhalter, keine gültigen Zugangsdaten. Keine `export`-Anweisungen +verwenden. Die Datei wird durch systemd geladen und bleibt root-geschützt mit +Modus 0600. Secrets nicht ins Repository oder in Shell-Befehlsargumente schreiben. + +**Wenn Integrationsschlüssel über die Weboberfläche verwaltet werden sollen:** +Den ausgelieferten `[[clients]]`-Beispielblock für `wow-capture-worker` vollständig +aus `api.toml` entfernen. Dazu gehören seine `id`-, `token_env`- und `projects`- +Zeilen. Die `[[projects]]`-Projektdefinition bleibt bestehen. `api.env` darf dann +zunächst nur Kommentare enthalten; ein `VBA_INTAKE_TOKEN` ist auf der +BugAnalysis-Seite nicht erforderlich. Andernfalls erwartet die Startprüfung für +den vorhandenen Beispielclient einen manuell konfigurierten Token in `api.env`. + +Details: [Projektkonfiguration](docs/project-configuration.md), +[Modell-/Cachekonfiguration](docs/llm-context-caching.md) und +[Linux-Betrieb](docs/linux-deployment.md). + +### 6. Persönliches Webkonto anlegen + +`meinname` durch den gewünschten Benutzernamen ersetzen. Das Passwort wird +verdeckt abgefragt; es gehört nicht in die Befehlszeile. + +```sh +sudo /opt/viano-bug-analysis/.venv/bin/python -m viano_bug_analysis.api create_user meinname --config /etc/viano-bug-analysis/api.toml --service-group buganalysis +``` + +Alle Webnutzer besitzen dieselben Bedienrechte. Nutzer werden ausschließlich per +privilegierter Konsole angelegt, geändert oder gelöscht; es gibt keine öffentliche +Registrierung. Weitere Befehle: [Benutzerkonten](docs/user-accounts.md). + +### 7. Bereitschaft ohne Modellanfrage prüfen + +Die Prüfungen laufen mit den Rechten und Environment-Dateien der späteren Dienste: + +```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 wird jeweils `READY` mit `model_requests: 0`. Geprüft werden unter +anderem Speicher, Schreib-/Leserechte, Webnutzer, Konfiguration, Git-Stand und +DB-Schemata. Die Prüfung sendet keine kostenpflichtige Modellanfrage; sie bestätigt +deshalb nicht die Gültigkeit des Cloud-Keys oder die Modellverfügbarkeit. +Bei `NOT_READY` zunächst den gemeldeten Fehler beheben. + +### 8. API starten und HTTPS einrichten + +```sh +sudo systemd-analyze verify /etc/systemd/system/viano-bug-analysis-api.service /etc/systemd/system/viano-bug-analysis-worker.service +sudo systemctl enable --now viano-bug-analysis-api.service +curl --fail http://127.0.0.1:8080/healthz +``` + +Der Health-Aufruf auf dem VPS sollte `{"status":"OK"}` liefern. Die API bleibt +an Loopback gebunden. Für die öffentliche Webadresse eine Domain mit passendem +DNS-Eintrag und gültigem TLS-Zertifikat bereitstellen. Zertifikatsbeschaffung +und Firewallfreigaben an die vorhandene VPS-/Nginx-Einrichtung anpassen. + +Auf Debian/Ubuntu kann eine eigene Nginx-Site aus der Vorlage angelegt werden: + +```sh +sudo cp /etc/viano-bug-analysis/nginx.conf.example /etc/nginx/sites-available/viano-bug-analysis +sudoedit /etc/nginx/sites-available/viano-bug-analysis +sudo ln -s /etc/nginx/sites-available/viano-bug-analysis /etc/nginx/sites-enabled/viano-bug-analysis +sudo nginx -t +sudo systemctl enable --now nginx +sudo systemctl reload nginx +``` + +**Vor `nginx -t` alle Beispieldomains und Zertifikatpfade ersetzen; die Zertifikate +müssen bereits vorhanden sein.** Bei bereits vorhandener Site keinen zweiten +Symlink anlegen, sondern die bestehende Einrichtung prüfen. Andere VPS-Sites +nicht entfernen. Erst über die fertige HTTPS-Adresse öffentlich anmelden. + +Für einen ersten lokalen Zugriff ohne fertige Domain ist ein SSH-Tunnel möglich. +Auf deinem eigenen Rechner ausführen, mit deinem SSH-Benutzer und VPS-Host: + +```sh +ssh -L 8080:127.0.0.1:8080 benutzer@vps-host +``` + +Danach lokal `http://127.0.0.1:8080/` öffnen, während der Tunnel läuft. Der Port auf +dem eigenen Rechner muss frei sein. Für den regulären externen Erfassungsworker +weiterhin die öffentliche HTTPS-Adresse einrichten. + +### 9. Erfassungsworker verbinden und Analysebetrieb einschalten + +Auf der Weboberfläche mit deinem Konto anmelden. Unter **API-Schlüssel** einen +Schlüssel für den Erfassungsworker und das Projekt `viano-core` erstellen. +Den Schlüssel im Environment des **wowdiag-Workers** als `VBA_INTAKE_TOKEN` +hinterlegen. Dessen `[buganalysis]`-Abschnitt mit URL, Projekt und Profil einrichten +und bewusst aktivieren. Anleitung und Vorlagen: +[Erfassungsworker v0.4](deploy/capture-worker/README.md). + +Der Erfassungsworker ist ein eigener Dienst auf dem Erfassungssystem. Er wird +nicht durch den BugAnalysis-Installer installiert oder gestartet. Die Datenbank- +Zugänge dieser beiden Programme sind ebenfalls voneinander unabhängig. + +Anschließend den Analyseworker aktivieren: + +```sh +sudo systemctl enable --now viano-bug-analysis-worker.service +sudo systemctl status viano-bug-analysis-api.service viano-bug-analysis-worker.service +``` + +**Ab diesem Zeitpunkt können vorhandene und neue Inbox-Aufträge kostenpflichtige +Modellaufrufe auslösen.** Mit einem kontrollierten echten Auftrag beginnen. In der +Weboberfläche Annahme und Fortschritt verfolgen, gegebenenfalls Testanfragen +beantworten und unter **Bearbeitete Fälle** das Ergebnis herunterladen. +Ergebnisse gehen in die Outbox, gescheiterte Analysen ins Review; blockierte Fälle +bleiben zur Fortsetzung erhalten. Ein Download bestätigt keine fachliche Übergabe. + +### 10. Betrieb, Sicherung und Updates + +```sh +sudo journalctl -u viano-bug-analysis-api -u viano-bug-analysis-worker -f +sudo systemctl stop viano-bug-analysis-worker.service +``` + +Der Worker beendet beim Stoppen den aktuellen Dispatch kontrolliert. Das kann +während einer laufenden Anfrage dauern. Vor Code-/Profiländerungen anhalten; +Konfigurationsbindungen laufender Fälle nicht beiläufig ändern. + +Mindestens `/etc/viano-bug-analysis` und `/var/lib/viano-bug-analysis` gesichert +aufbewahren. Dazu zählen die Nutzer-SQLite sowie Integrationsschlüssel-SQLite und +deren separate Serverschlüsseldatei unter `runtime/integration-secrets`. Dieses +Verzeichnis ist kein beliebig löschbarer Cache. Für eine einfache konsistente +Dateisicherung beide Dienste anhalten. Zugriffe auf Backups mit Secrets schützen. + +Für ein bewusstes Codeupdate im root-eigenen Checkout beispielsweise: + +```sh +sudo systemctl stop viano-bug-analysis-worker.service viano-bug-analysis-api.service +cd /opt/viano-bug-analysis +sudo git pull --ff-only +sudo .venv/bin/python -m pip install '.[api,research]' +sudo systemctl start viano-bug-analysis-api.service viano-bug-analysis-worker.service +``` + +Releasehinweise und geänderte Konfigurations-/Unit-Vorlagen vorher prüfen. +Das Updatebeispiel ersetzt keine gezielte Übernahme geänderter systemd-Units +mit anschließendem `systemctl daemon-reload`. Vorlagen werden vom Installer +absichtlich nicht über bestehende Konfigurationen kopiert. + +Die Einrichtung ist abgeschlossen, wenn Anmeldung, automatischer Auftragseingang, +Analyse, Ergebnisdownload, menschliche Rückfrage und Wiederanlauf nach einem +Dienst-/Serverneustart geprüft wurden. Die native Linux-/HTTPS-Prüfung erfolgt auf +deinem Zielserver; lokale Windows-Entwicklungstests ersetzen sie nicht. + +### Häufige Probleme bei der Ersteinrichtung + +| Meldung / Verhalten | Zuerst prüfen | +| --- | --- | +| Installer verlangt root-eigenen Checkout | Pfad `/opt/viano-bug-analysis`, Eigentümer und Schreibrechte des Codes | +| `DEPLOY_MACHINE_CREDENTIALS` | Unbenutzten `[[clients]]`-Beispielblock entfernen oder dessen env-Token korrekt einrichten | +| `LLM_CREDENTIALS` | `worker.env`, Name der Schlüsselvariable in `llm.toml` und Laden der Datei durch systemd | +| `PROJECT_DATABASE_UNAVAILABLE` | DB-Adresse/Port, Netzwerkweg, Passwort und DB-Benutzer | +| Sourceprüfung schlägt fehl | Lokaler Checkout, tatsächlicher Commit, Leserechte und `/etc/viano-bug-analysis/gitconfig` | +| `nginx -t` meldet fehlendes Zertifikat | Zertifikat bereitstellen und die Beispielpfade im Site-Block ersetzen | +| Anmeldung funktioniert, aber kein Fall wird analysiert | Analyseworker läuft, Projektbindung stimmt, Auftrag ist tatsächlich angenommen | + +Dienstfehler über `journalctl` prüfen. Ein fehlgeschlagener Start wird durch +systemd erneut versucht; nach einer Korrektur lässt sich der betreffende Dienst +mit `sudo systemctl restart DIENSTNAME` gezielt neu starten. Dabei den echten +Namen `viano-bug-analysis-api.service` beziehungsweise +`viano-bug-analysis-worker.service` einsetzen. + +## Weiterführende Anleitungen + +- [Verwendung und Funktionsweise](docs/user-guide.md) – auch im Webreiter Benutzeranleitung. +- [Projekt-, Source-, DB- und Modellkonfiguration](docs/project-configuration.md). +- [Übergabe-API und Rückgaben](docs/intake-api.md). +- [Analyseworker](docs/analysis-worker.md). +- [Benutzerkonten](docs/user-accounts.md). +- [Integrationsschlüssel](docs/integration-keys.md). +- [Linux-Betrieb im Detail](docs/linux-deployment.md). + +## Entwicklung und technische Dokumentation + Project-independent foundations for reading, validating and extending ZIP case packages. The authoritative design is [docs/architecture.md](docs/architecture.md). The implemented v1 contract is documented in @@ -75,8 +383,8 @@ Durable investigation budget accounting, configurable costs/rewards and stopping rules: [budget-manager-v1.md](docs/budget-manager-v1.md), with [budget configuration](config/budget.example.toml). Case-local asynchronous test requests, confirmed feedback and budget-preserving -event-driven resume: [async-tests-v1.md](docs/async-tests-v1.md). Web UI and external -bot/client adapters are future integrations. +event-driven resume: [async-tests-v1.md](docs/async-tests-v1.md). Human test requests +can be answered through the web console; external bot adapters are separate integrations. Read-only packaged source/database queries and the strict tool allowlist: [investigation-tools-v1.md](docs/investigation-tools-v1.md).