Nico/VianoBugAnalysis
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document VPS installation and first setup on repository homepage

Browse Source
This commit is contained in:
Nico committed 2026-10-23 15:36:11 +02:00
1 parent 085a5c4026
commit 9408af5356
1 file changed
+310 -2
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+310 -2
View File
@@ -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).