Orchestrator/docs/SETUP.md

SETUP – Was du (manuell) tun musst

Code/Config sind vorbereitet. Diese Schritte brauchen Zugaenge/Rechte, die nur du hast.

Warum kein Deps-Image? (PyPI ueber Artifactory-Mirror)

Die GitLab-Runner-Pods erreichen pypi.org nicht, aber den Artifactory-PyPI-Mirror auf bahnhub. Deshalb setzt die CI PIP_INDEX_URL auf den Mirror – dann funktioniert pip install direkt im Job, ohne eigenes Image:

PIP_INDEX_URL = https://bahnhub.tech.rz.db.de/artifactory/api/pypi/pypi-remote/simple

Ist bereits in .gitlab-ci.yml gesetzt. Falls der Repo-Name im Konzern abweicht, dort anpassen (beim DXP-/pipeship-Team erfragen). lint/pages brauchen kein pip.

---

Checkliste

1. PyPI-Mirror pruefen

• Ersten Pipeline-Lauf ansehen: test-Job muss pip install ueber den Mirror schaffen. Falls 403/404: PIP_INDEX_URL (Repo-Name) in .gitlab-ci.yml anpassen.

2. CI/CD-Variablen anlegen (Settings → CI/CD → Variables, Masked & Protected)

• [ x] CONFLUENCE_URL = https://arija-confluence.jaas.service.deutschebahn.com
• [x ] CONFLUENCE_TOKEN = dein Confluence-PAT (neuen erzeugen, alten rotieren!)
• [x ] GIT_PUSH_TOKEN = Project Access Token mit Scope write_repository
• (optional) GITLAB_TOKEN = Read-Token, falls gitlab_md-Quellen aus PRIVATEN GitLab-Repos geladen werden (oeffentliche brauchen keinen Token)
• (DEPS_IMAGE entfaellt – pip laeuft ueber PIP_INDEX_URL, siehe oben)

3. Schedule (CI/CD → Schedules)

• Schedule angelegt: Cron 0 8-17 * * 1-5 (stuendlich Mo–Fr 8–17 Uhr), Target Branch main. Der knowledge-etl-Job laeuft nur bei schedule/web.

3b. Netzzugang des Runners (WICHTIG fuer den ETL-Lauf)

Der Runner muss die Quellen erreichen, sonst kommen 0 Dokumente (Timeouts):

• intern: arija-confluence...deutschebahn.com (Confluence)
• oeffentlich: www.dbinfrago.com (Kundeninfos, INB, Regelwerk)

Der knowledge-etl-Job ist bereits auf den DB-Web-Proxy konfiguriert (http://webproxy.comp.db.de:8080) mit NO_PROXY fuer interne Hosts (.tech.rz.db.de, .deutschebahn.com).

• Pruefen, ob Proxy-Host/Port stimmen (ggf. in .gitlab-ci.yml anpassen) und ob der Proxy keine Authentifizierung verlangt. Beim naechsten Lauf im Log sehen: laufen Confluence + dbinfrago jetzt durch?

4. Protected Branch + Freigabe (Settings → Repository → Protected Branches)

• [x ] main schuetzen: „Allowed to push" = niemand (nur via MR); „Allowed to merge" = Maintainer.
• Settings → Merge requests: „Require approval from Code Owners" aktivieren. das ignroerien wir erst mal
• In CODEOWNERS die Platzhalter durch echte GitLab-Gruppen/Handles ersetzen (@einfachbahn-lab/wissensdatenbank-maintainer -> reale Gruppe).

  das auch

• Hinweis: Der automatische Bot-Push auf main braucht dann eine Ausnahme (Token-User als „Allowed to push" zulassen) ODER der Bot pusht auf einen Branch knowledge-data (in .gitlab-ci.yml TARGET_BRANCH umstellen) + Auto-MR. -> braucht es das dann noch? ANTWORT: Ja. Da main „push = niemand" ist, wuerde der automatische ETL-Push scheitern. Einfachste Loesung: den GIT_PUSH_TOKEN-User unter „Allowed to push" fuer main zulassen. (CODEOWNERS-Approval ignorieren wir ja erst mal, also kein MR-Zwang.)

5. GitLab Pages aktivieren (Deploy → Pages)

• [ x] Nach erstem erfolgreichen pages-Job ist die URL unter Deploy → Pages sichtbar. (Job laeuft auf main; nutzt nur stdlib, kein Deps-Image noetig.)

das hier verstehe ich noch nicht:

6. Issue → MR Automatisierung (optional, fuer Self-Service)

Ziel: Ein Fachbereich meldet neues Wissen per GitLab-Issue (Vorlage „Neues Wissen"), ohne yaml/Git zu koennen. Daraus wird automatisch ein Eintrag in config/tools.yaml

• ein Merge Request mit Vorschau. So laeuft es:

1. Person legt ein Issue mit der Vorlage an (Tool, Link(s), Scope, Ansprechpartner) und Label neues-wissen.
2. Aus dem Issue wird ein tools.yaml-Eintrag erzeugt (scripts/issue_to_source.py) und ein MR geoeffnet (scripts/issue_to_mr.sh <ISSUE_ID>), inkl. Markdown-Vorschau.
3. Reviewer schaut die Vorschau an und merged = Freigabe.

Du musst nur entscheiden, WIE Schritt 2 ausgeloest wird:

• Manuell (einfachste Variante): Reviewer fuehrt scripts/issue_to_mr.sh <ISSUE_ID> lokal aus (braucht glab eingeloggt + aktive venv + CONFLUENCE_*). Fuer den Anfang reicht das.

• Automatisch (spaeter): GitLab-Webhook auf „Issues events" an einen kleinen Dienst, der das Skript ausfuehrt – ODER ein scheduled CI-Job, der offene neues-wissen-Issues abarbeitet.

• Label neues-wissen anlegen (fuer beide Varianten).

• Fuer den Start: Variante „manuell" nutzen. Automatik ist optional/spaeter.

8. Reviews

• [ passt erst mal] GitLab Pages (Uebersicht) pruefen.
• [passt erst mal ] pending freigeben: URL oder hash:<content_hash> in config/approvals.yaml unter approved: eintragen.

---

ETL-Bot - was genau noch zu tun ist

Der knowledge-etl-Job laeuft per Schedule (stuendlich Mo–Fr 8–17 Uhr), baut das Wissen und pusht das Ergebnis zurueck. Dafuer:

1. GIT_PUSH_TOKEN anlegen: Settings → Access Tokens → Project Access Token, Rolle Maintainer, Scope write_repository. Wert als CI/CD-Variable GIT_PUSH_TOKEN (Masked & Protected) speichern.
2. Push auf main erlauben (weil main „push = niemand" ist): Settings → Repository → Protected Branches → main → unter „Allowed to push" den Token-User hinzufuegen (heisst typ. project_<id>_bot).
   • Alternative (main bleibt strikt): in .gitlab-ci.yml TARGET_BRANCH: knowledge-data setzen; der Bot pusht dann auf einen Datenbranch (kein Push auf main noetig).
3. Schedule angelegt (CI/CD → Schedules, Cron 0 8-17 * * 1-5, Target main). ✔

Mehr ist fuer den Bot nicht noetig – pip laeuft ueber den PyPI-Mirror.

Quellen-Typen: GitLab / Datei im Repo / public

• GitLab (gitlab_md): ✅ Markdown-Dateien aus einem Repo, mit Ordner (path) und Tiefe (max_depth). Privat-Repos brauchen GITLAB_TOKEN.
• Datei im Repo (file): ✅ Handbuch/Doku einfach nach files/<tool>/ pushen und per strategy: file einbinden (PDF wird zu Text, .md direkt). Alles versioniert.
• PDF-Handbuecher via Link (pdf): ✅ direkter PDF-Link oder Seite mit PDF-Links.
• Public Links (crawler/pdf/sitemap): ✅.