Deploymentcenter/docs/README.md

Deploymentcenter — Entwickler- und Agenten-Dokumentation

Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur- Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.

---

Zuerst lesen

Dokument	Wofür
ROADMAP.md	Der eine Ort für alles Geplante, Zurückgestellte und bewusst Verworfene. Ab 2.7.0 gilt die Arbeitsteilung: Zustand im Deploymentcenter (WebUI → Roadmap, dc_roadmap), Begründung hier.
ROADMAP_MIGRATION.md	Eine vorhandene ROADMAP.md oder TODO.md ins Deploymentcenter überführen. Einmalig je Projekt, sechs Schritte. Für die Agenten der angebundenen Projekte.
UPGRADE.md	Ablaufplan für die Umstellung auf 2.0. Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron.
Änderungen	Was sich je Fassung geändert hat und was zu tun ist. Öffentlich unter /docs/changelog.php, maschinenlesbar über GET /api/updateservice/v1/changelog?since=X
Release-Anleitung für Agenten	Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern
Linux-Testumgebung	Die geteilte Test-VM. Wie ein Agent dort selbständig testet: DEV-Lizenz holen, Auslieferung prüfen, Befunde melden — mit dc-testkit
Testinstanz & automatisierter Testlauf	dc-dev.mhdf.de — die zweite Installation zum Kaputtmachen. 128 Fälle gegen API, Rechte, Migrationen und Zugangssperre (tests/e2e/run.py). scripts/deploy.py führt sie vor jedem Produktiv-Upload aus und bricht bei Fehlschlägen ab (--ohne-test umgeht das)
Agent-Prompt-Vorlage	Textbaustein für CLAUDE.md / AGENTS.md eines Projekts
Agenten-Handbuch	Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter /docs/

Modul-Handbücher

• Lizenzsystem (Hardware-ID v2) — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
• Watchdog (Heartbeat & Telemetrie) — Überwachung von Anwendungen, Diensten und Infrastruktur
• UpdateService — Release-Verteilung und Update-Prüfung
• Erstinstallation — setup.json, Installationskonto, update-agent --action install
• Bugtracker — Anbindung aus Anwendungen heraus
• Supervisor — Befunde: was ist ungewöhnlich? Läuft serverseitig auf ohnehin eingehenden Daten, ohne Einbau in die Anwendungen. Enthält auch den Rückbau begonnener Vorbereitungen
• MCP-Adapter — Claude Code und Claude Desktop an Bugtracker, Roadmap und Supervisor anschließen — 15 Werkzeuge, 4 Ressourcen, 4 Prompts

Hintergrund zu Supervisor und MCP, inklusive der Frage, warum der Client keinen Quelltext sieht: archiv/SUPERVISOR_MCP_DESIGN.md — archiviert, die Herleitung gilt weiter, der Stand steht in der Roadmap.

---

Modulübersicht

Modul	Aufgabe	Endpunkte	Authentifizierung
Bugtracker	Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease	/api/bugtracker/v1/report /api/bugtracker/v1/projects /api/bugtracker/v1/manage	Token mit bugtracker:*
UpdateService	Release-Verteilung, semantischer Versionsvergleich	/api/updateservice/v1/check /api/updateservice/v1/publish	Lesen offen, Publish braucht updateservice:publish
Watchdog	Heartbeat-Monitoring, Zustandsbewertung, Alarmierung	/api/watchdog/v1/ping /api/watchdog/v1/evaluate	Token mit watchdog:ping
Supervisor	Befunde: was ist ungewöhnlich? Fünf Detektoren laufen serverseitig im Tick und brauchen keine Client-Änderung	/api/supervisor/v1/observe /api/supervisor/v1/findings /api/supervisor/v1/catalog	Melden supervisor:report, Lesen supervisor:read, Einstufen supervisor:manage
Lizenzen	Lizenzprüfung, Hardware-ID v2, Offline-Cache, befristete DEV-Schlüssel zur Selbstbedienung	/api/license/v1/validate /api/license/v1/deactivate /api/license/v1/dev-key	Validierung offen, Deaktivierung authentifiziert, DEV-Schlüssel license:dev
Tokens	Selbst-Provisionierung von Sub-Tokens	/api/tokens/v1/provision	Master-Token
Setup	Erstinstallation: Anmeldung, Katalog, Anwendungstoken	/api/setup/v1/login /api/setup/v1/catalog /api/setup/v1/token	Login offen, Rest setup:*
System	Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung	/api/health /api/openapi.json	Health optional, OpenAPI offen

---

Schnittstelle maschinenlesbar

GET https://dc.mhdf.de/api/openapi.json

Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI hinterlegte Textblock entfällt damit.

---

Drosselung

Je IP und Minute. Wird die Grenze überschritten, antwortet der Endpunkt mit 429 rate_limited — dann das Intervall verdoppeln und später erneut versuchen, nicht sofort wiederholen.

Endpunkt	Grenze	Einstellbar über
/api/errors/v1/report	300	bugtracker.error_rate
/api/bugtracker/v1/report	60	bugtracker.report_rate
/api/supervisor/v1/observe	120	supervisor.observe_rate
/api/license/v1/*	120	fest
/api/license/v1/dev-key	10	fest — ein Schlüssel je Testlauf, nicht je Sekunde
/api/updateservice/v1/*	240	fest
/api/setup/v1/login	10	fest — dort werden Passwörter geprüft
/api/tokens/v1/provision	20	fest

---

Antwortformat

Alle JSON-Endpunkte antworten einheitlich:

{ "status": "success", "…": "…" }

{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }

Der code ist stabil und für Programme gedacht; die message richtet sich an Menschen und kann sich ändern.

---

Betrieb

Aufgabe	Befehl
Deployment	python scripts/deploy.py
Migration	php public/install_db.php oder WebUI → System → DB-Migration
Evaluator (Cron, minütlich)	curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate
Zustand prüfen	curl https://dc.mhdf.de/api/health
Logs	var/log/dc-<datum>.log auf dem Server

Aufbau

config/    Zugangsdaten (nicht versioniert), Vorlage in config.example.php
src/       Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
  Core/      Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator,
             ProjectLinks (welches Projekt nutzt welches, in welcher Fassung)
  Modules/   Bugtracker, License, Supervisor, UpdateService, Watchdog, Notify
public/    Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation,
           testkit/dc-testkit.sh (das Werkzeug für die Linux-Test-VM)
sql/       Schema und Migrationen (fortlaufend nummeriert)
var/log/   Laufzeitprotokolle
scripts/   Deployment
mcp/       MCP-Adapter für Claude Code — eine Datei, keine Abhängigkeiten
client-dotnet/ Client-SDK: Lizenz, Update, Setup

Der Supervisor läuft ausschließlich hier — an den Detektoren in Modules/Supervisor/ServerDetectors.php im minütlichen Tick mit (gedrosselt auf zehn Minuten). Er arbeitet auf Daten, die ohnehin hereinkommen — Fehlerberichte, Heartbeats, Kennzahlen — und braucht dafür keine Änderung an den Anwendungen.

Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad entsprechen — eine require-Zeile ist nicht mehr nötig.