Richter-und-Zech/electric-horses-infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electric-horses-infra/Agent.md
Benjamin Weinlich 20025814e8 chore(agent): update briefings to reflect M7.3 doc mirror 
Root Agent.md and stacks/forgejo/Agent.md had stale references to
"docs live in iCloud, will be mirrored in M7.3". Now M7.3 is done,
so the briefings point to docs/adr/ and docs/runbooks/ directly
with relative links that render as clickable in the Forgejo web UI.

The iCloud folder stays around for loose notes and credentials
that cannot go into a public repo, but the primary source of truth
for ADRs / runbooks / guides is now this repo.

Refs OP#1118
2026-04-11 22:26:24 +02:00

4.6 KiB
Raw Blame History

Agent Briefing — electric-horses-infra

Du bist ein AI-Agent der an der Infrastructure-as-Code-Ablage von Electric Horses / Richter & Zech arbeitet.

Was ist dieses Repo?

Die versionierte Beschreibung unserer Hetzner-Cloud-Infrastruktur. Alles was wir auf Servern laufen lassen (docker-compose-Stacks, Configs, Scripts) ist hier abgebildet — ohne Secrets. Das Repo ist kein Deploy-Mechanismus (wir ziehen nicht automatisch aus Git auf die Server), sondern die Wahrheit-von-gestern: was aktuell läuft.

Wenn Server A und dieses Repo unterschiedliche Inhalte zeigen, ist entweder ein Commit noch offen ODER die AI hat manuell am Server gearbeitet und das Repo nicht nachgezogen — letzteres ist ein Bug und muss nachgeholt werden.

Vor jeder Aktion

  1. Lies README.md — die aktuellen Regeln
  2. Lies Agent.md im betroffenen Stack-Ordner (z.B. stacks/forgejo/Agent.md) falls vorhanden
  3. Verstehe den aktuellen Zustand — git log --oneline -20 zeigt die letzten Aktionen

Konventionen

Commit-Messages

  • Auf Deutsch ODER Englisch, konsistent pro Commit
  • Konventioneller Prefix (feat / fix / docs / refactor / chore)
  • Referenz auf OpenProject wenn anwendbar: Refs OP#1234
  • Kurz und konkret, Detail in Commit-Body

Beispiele:

feat(forgejo): add backup cron script

Refs OP#1119

fix(eh-search): tighten substring match to 3+ chars

Fixes the "ze" noise issue where 2-char queries matched
in unrelated words. Brand-prefix matches still work.

Refs OP#1112

Secrets — NIEMALS committen

  • .env immer gitignored
  • .env.example mit Platzhaltern ist OK
  • Wenn du echte Credentials brauchst: sie leben auf dem Server in /opt/<stack>/.env
  • API-Tokens, Passwörter, Zertifikate: nie ins Repo, auch nicht in Comments

Docker-Compose-Files

  • Spiegeln 1:1 den Stand auf dem Server
  • Image-Tags sind gepinnt (nicht :latest) für Reproduzierbarkeit
  • Environment-Variablen immer via env_file oder environment: mit ${VAR} Syntax — nie hardcoded

Docs

  • Architektur-Beschreibungen in docs/architecture/
  • ADRs in docs/adr/<NNNN>-<slug>.md mit fortlaufender Nummer
  • Runbooks in docs/runbooks/<topic>.md
  • Markdown-Diagramme mit Mermaid (rendert im Forgejo-Web-UI)

Verbindung zur realen Infrastruktur

Stack Server Pfad auf Server Dieses Repo
forgejo ai-apps (10.0.0.8) /opt/ai-apps/forgejo/ stacks/forgejo/
eh-search ai-apps (10.0.0.8) /opt/ai-apps/eh-search/ stacks/eh-search/
(weitere kommen in folgenden Commits)

Workflow bei Änderungen:

  1. AI macht Änderung auf dem Server (docker-compose.yml anpassen, restart)
  2. AI committet die identische Änderung in dieses Repo
  3. User reviewt den Commit im Forgejo Web-UI
  4. Bei Problemen: Rollback via git revert + manuelles Neudeployen auf dem Server

Zugang zu Servern während der Arbeit

  • ssh ai-apps — Hetzner cx22, Private 10.0.0.8, Public 91.98.226.44
  • ssh pegasus — Hetzner cx33, Private 10.0.0.10 (kein Public IPv4)
  • ssh webmin-kronos — Hetzner cx32 mit sudo, DNS + Apache Proxy
  • ssh authentik-sso — Hetzner, Private 10.0.0.7, SSO

Lokale Doku mit Credentials: /Users/benjaminweinlich/Library/Mobile Documents/com~apple~CloudDocs/AI/IT & Infrastruktur/ (nicht in diesem Repo — das Repo ist public!)

Dieses Repo ist PUBLIC

Das bedeutet:

  • Nichts was schützenswert wäre commiten (keine Passwörter, interne Kundendaten, Fahrzeug-VINs außer öffentlich dokumentierten Musterdaten)
  • Die README + ADRs können gern "Marketing-tauglich" sein — sie zeigen nach außen wie wir denken und bauen
  • Für sensiblere Details ein privates Repo nutzen (evtl. zukünftig electric-horses-infra-private)

OpenProject

  • Projekt: www.electric-horses.de Relaunch (ID 33)
  • Relevante Phasen:
    • M6: Site Search (abgeschlossen)
    • M7: Operations & Documentation Foundation
      • M7.1: Forgejo Deployment (#1119) — abgeschlossen
      • M7.2: Erstes Infra-Repo (dieses Repo!)
      • M7.3: ADRs/Runbooks/Guides gespiegelt (dieser Commit)
      • M7.4+: Mirror zu GitHub, rclone backup, weitere Apps

Related Docs (im Repo)

Ab M7.3 lebt die Doku primär in diesem Repo:

Der lokale iCloud-Ordner AI/IT & Infrastruktur/ ist ab jetzt sekundär — dort leben nur noch Credentials-Hinweise und Lose-Notizen, die nicht in ein public Repo gehören.