diff --git a/docs/entire-headless-in-eu-setup.md b/docs/entire-headless-in-eu-setup.md new file mode 100644 index 0000000..39f3445 --- /dev/null +++ b/docs/entire-headless-in-eu-setup.md @@ -0,0 +1,336 @@ +# Entire auf Headless-Server mit EU-Kontext einrichten + +Diese Anleitung beschreibt die Einrichtung von Entire auf einem Headless-Host mit bestehendem Git-Repository auf einem eigenen Gitea-Server und Nutzung des **EU-Kontexts**. + +## Ziel + +- Entire ohne GUI/Browser auf dem Server verwenden +- Login über Device-Code-Flow +- Tokens ohne OS-Keyring in Datei speichern +- EU-Jurisdiktion / EU-Cluster verwenden +- Entire lokal in einem bestehenden Git-Repository aktivieren + +--- + +## Voraussetzungen + +- `entire` CLI ist installiert +- Zugriff per SSH auf den Headless-Server +- funktionierendes lokales Git-Checkout +- `origin`-Remote ist gesetzt +- Browser auf einem **anderen lokalen Rechner** verfügbar + +Beispiel prüfen: + +```bash +git remote -v +``` + +Beispielausgabe: + +```bash +origin git@devel:lifemaps/qt-migration-copilot-demo.git (fetch) +origin git@devel:lifemaps/qt-migration-copilot-demo.git (push) +``` + +--- + +## 1. Token-Speicherung für Headless-Betrieb aktivieren + +Auf Headless-Systemen gibt es oft keinen Linux-Keyring (`org.freedesktop.secrets`). +Deshalb sollten Entire-Tokens in einer Datei gespeichert werden. + +Empfohlene Umgebungsvariablen: + +```bash +export ENTIRE_TOKEN_STORE=file +export ENTIRE_TOKEN_STORE_PATH="$HOME/.config/entire/tokens.json" +export ACCESSIBLE=1 +``` + +Temporär in der aktuellen Shell: + +```bash +export ENTIRE_TOKEN_STORE=file +export ENTIRE_TOKEN_STORE_PATH="$HOME/.config/entire/tokens.json" +export ACCESSIBLE=1 +``` + +Dauerhaft in `~/.bashrc`: + +```bash +echo 'export ENTIRE_TOKEN_STORE=file' >> ~/.bashrc +echo 'export ENTIRE_TOKEN_STORE_PATH="$HOME/.config/entire/tokens.json"' >> ~/.bashrc +echo 'export ACCESSIBLE=1' >> ~/.bashrc +source ~/.bashrc +``` + +--- + +## 2. Im EU-Kontext anmelden + +Für Headless-Systeme den Device-Code-Flow verwenden: + +```bash +entire login --device --server https://eu.auth.entire.io +``` + +Das CLI zeigt dann etwa: + +- einen **Device Code** +- eine **Login-URL** + +Die URL im Browser **auf dem lokalen Rechner** öffnen und die Anmeldung dort bestätigen. + +### Wichtiger Hinweis + +Wenn auf dem Server kein Browser verfügbar ist, ist eine Meldung wie diese normal: + +```text +Warning: failed to open browser: xdg-open not found +``` + +Das ist **nicht** das eigentliche Problem. + +Falls Entire versucht, Tokens im Keyring zu speichern und dabei fehlschlägt, war `ENTIRE_TOKEN_STORE=file` nicht gesetzt. + +--- + +## 3. Login prüfen + +Nach erfolgreicher Anmeldung: + +```bash +entire auth status +``` + +Beispiel: + +```text +Logged in to https://eu.auth.entire.io +Context: eu.auth.entire.io +Token: stored in file /home//.config/entire/tokens.json +``` + +Falls mehrere Kontexte existieren: + +```bash +entire auth contexts +entire auth use --help +``` + +--- + +## 4. Prüfen, ob wirklich EU verwendet wird + +Zusätzlich zum Login-Kontext sollte geprüft werden, auf welchem Cluster die Entire-Repositories liegen. + +Projekt-Repositories anzeigen: + +```bash +entire repo list +``` + +Wenn in der Spalte `CLUSTER` z. B. Folgendes erscheint: + +```text +aws-eu-central-1.entire.io +``` + +dann liegen diese Repositories auf einem **EU-Cluster**. + +### Empfohlener Doppel-Check + +```bash +entire auth status +entire repo list +``` + +EU ist praktisch bestätigt, wenn: + +- `Context: eu.auth.entire.io` aktiv ist +- die Repositories auf `aws-eu-central-1.entire.io` liegen + +--- + +## 5. Entire im lokalen Repository aktivieren + +In das lokale Repository wechseln: + +```bash +cd ~/coplint.d/qt-migration-copilot-demo +``` + +Dann Entire aktivieren: + +```bash +entire enable +``` + +Status prüfen: + +```bash +entire status +``` + +Beispiel: + +```text +● Enabled · branch bugfix/ci-pipeline-commissioning + Agents · Copilot CLI +``` + +--- + +## 6. Agent-Integration prüfen oder ergänzen + +Verfügbare Agenten anzeigen: + +```bash +entire agent list +``` + +Hilfe für das Hinzufügen: + +```bash +entire agent add --help +``` + +Neuen Agenten hinzufügen: + +```bash +entire agent add +``` + +Danach erneut prüfen: + +```bash +entire status +``` + +--- + +## 7. Unterschied zwischen lokalem Git-Repo und Entire-Repo verstehen + +Wichtig: Entire verwendet hier **zwei verschiedene Konzepte**. + +### Lokales Git-Repository +Das echte Code-Repository, z. B.: + +```bash +git@devel:lifemaps/qt-migration-copilot-demo.git +``` + +### Entire-Repository +Ein separates Objekt in Entire, verwaltet über: + +```bash +entire repo list +entire repo get --project +entire repo create --project +``` + +### Konsequenz + +`entire enable` aktiviert das **lokale Git-Repository**, +aber es erzeugt **nicht automatisch** ein neues `entire repo`-Objekt. + +Darum kann es sein, dass: + +- `entire status` = aktiviert +- aber `entire repo list ` dein lokales Repo **nicht** zeigt + +Das ist normales Verhalten. + +--- + +## 8. Optional: Entire-Repo im Projekt anlegen + +Wenn zusätzlich ein eigenes Entire-Repo-Objekt für das lokale Projekt gewünscht ist: + +```bash +entire repo create qt-migration-copilot-demo --project +``` + +Danach prüfen: + +```bash +entire repo list +``` + +### Hinweis + +Nach bisherigem CLI-Verhalten wird dabei nur ein **Entire-internes Repo-Objekt** erzeugt. +Es gibt in der gezeigten Hilfe keinen Hinweis darauf, dass dabei automatisch eine Git-URL aus Gitea importiert oder synchronisiert wird. + +--- + +## 9. Typischer Minimal-Workflow + +```bash +export ENTIRE_TOKEN_STORE=file +export ENTIRE_TOKEN_STORE_PATH="$HOME/.config/entire/tokens.json" +export ACCESSIBLE=1 + +entire login --device --server https://eu.auth.entire.io +entire auth status + +cd ~/coplint.d/qt-migration-copilot-demo +entire enable +entire status +entire agent list +``` + +--- + +## 10. Troubleshooting + +### Kein Browser auf dem Server +Normal auf Headless-Hosts. +Device-Code-URL auf lokalem Rechner öffnen. + +### Login erfolgreich, aber `Not logged in` +Ursache meist fehlender Keyring und keine Datei-Speicherung. + +Lösung: + +```bash +export ENTIRE_TOKEN_STORE=file +entire login --device --server https://eu.auth.entire.io +``` + +### Entire ist aktiviert, aber nicht in `entire repo list` +Das ist erwartbar, weil lokales Git-Repo und Entire-Projektrepo getrennte Objekte sind. + +### Diagnose +Bei Problemen: + +```bash +entire doctor +``` + +--- + +## 11. Empfehlung für dieses Setup + +Für ein Setup mit **Gitea + Jenkins + Entire** gilt: + +- **Gitea** bleibt Source-of-Truth für den Code +- **Jenkins** bleibt CI/CD-System +- **Entire** ergänzt Session-, Agent- und Checkpoint-Tracking im lokalen Repository +- **Entire-Projekte/Repos** sind zusätzliche Verwaltungsobjekte und nicht identisch mit dem Gitea-Remote + +--- + +## 12. Nützliche Befehle + +```bash +entire auth status +entire auth contexts +entire project list +entire repo list +entire enable +entire status +entire agent list +entire doctor +``` \ No newline at end of file