Claude-Code-Deployment: Leitfaden für den Produktivbetrieb

Claude-Code-Deployment wird erst dann zuverlässig, wenn der Agent zwischen „Anfrage angenommen“ und „Produktivsystem ist gesund“ unterscheiden kann. Dockup stellt diese Deployment-Ebene über eine CLI bereit, die für maschinelle Aufrufer konzipiert ist: strukturiertes JSON, echte Prozess-Exit-Codes und einen --wait-Modus, der verbunden bleibt, bis ein Deployment einen terminalen Status erreicht.

Dieser Leitfaden führt ein Repository von der lokalen Entwicklung bis zu einem verifizierten Produktiv-Release. Außerdem legt er fest, welche Berechtigungen Claude Code erhalten sollte, welche Nachweise es zurückgeben muss und an welcher Stelle ein Mensch eine destruktive Aktion freigeben muss.

Was benötigt Claude Code vor dem Deployment in den Produktivbetrieb?

Ein Coding-Agent sollte nicht damit beginnen, einen Servicenamen zu erraten oder sich durch ein Dashboard zu klicken. Gib ihm einen klar begrenzten Handlungsrahmen: das exakte Ziel ermitteln, eine beabsichtigte Änderung ausführen, auf das Ergebnis warten und maschinenlesbare Nachweise zurückgeben.

Die grundlegenden Voraussetzungen sind überschaubar:

Voraussetzung	Warum sie wichtig ist	Überprüfung
Node.js 18 oder neuer	Wird vom Dockup-CLI-Paket benötigt	node --version
Dockup-Konto	Verwaltet Workspaces, Services und Datenbanken	Bei app.dockup.ai anmelden
Git-Repository	Quelle für den Service-Build	Remote-URL und Branch bestätigen
API-Token	Authentifizierung ohne Interaktion	dockup whoami --json
Health-Endpoint oder lauschender Port	Gibt den Blue-Green-Cutover frei	dockup health ... --json

Lege die Grenze für den Produktivbetrieb fest, bevor der Agent aktiv wird. Claude Code darf einen Service erstellen, unkritische Konfiguration setzen, ein Deployment auslösen, Logs prüfen und einen Rollback vorschlagen. Es sollte jedoch keinen Service löschen, keine Datenbank entfernen und keine Konfiguration bereinigen, ohne dass ein Mensch dies ausdrücklich freigegeben hat.

Dockup unterstützt diese Grenze. Destruktive Befehle werden ohne --yes nicht ausgeführt und liefern stattdessen einen strukturierten needs_confirm-Fehler zurück, anstatt die fehlende Bestätigung als Aufforderung zum Improvisieren zu behandeln. Eine umfassendere Richtlinie findest du unter Leitplanken für KI-Agenten im Produktivbetrieb.

Wie installierst du den Claude-Code-Skill und authentifizierst dich sicher?

Installiere die CLI, installiere den enthaltenen Skill und überprüfe, ob der Skill zur installierten Binary passt:

npm install -g dockup-cli
dockup skill install
dockup skill status --json

Das Installationsprogramm schreibt den kanonischen Skill nach ~/.agents/skills/dockup/ und verknüpft ihn mit dem Skill-Verzeichnis von Claude Code. Da der Skill im selben npm-Paket wie die CLI ausgeliefert wird, aktualisiert dockup update beide Komponenten. Claude Code muss sich daher nicht auf eine kopierte Befehlsreferenz verlassen, die möglicherweise Flags beschreibt, die die lokale Binary nicht unterstützt.

Verwende für autonome Sitzungen ein Token aus einer Umgebungsvariable:

export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Eine erfolgreiche Antwort identifiziert das Konto und gibt tokenSource mit dem Wert env zurück. Füge das Token nicht in einen Prompt ein, committe es nicht in das Repository und gib es nicht in einem CI-Log aus. In Dockup gespeicherte Secret-Werte werden maskiert, wenn die Konfiguration erneut ausgelesen wird.

Die vollständige Dockup-CLI-Referenz ist die maßgebliche Befehlsreferenz. Bei 135 Befehlen sollte Claude Code die aktuelle Referenz und den paketierten Skill konsultieren, statt sich auf gemerkte Flags zu verlassen.

Da der Skill im CLI-Paket enthalten ist, aktualisiert dockup update die ausführbare Datei und die zugehörigen Anweisungen gemeinsam. Diese Versionsabstimmung ist sicherer, als eine Befehlsliste in einen langlebigen Prompt zu kopieren.

Wie erstellt die Dockup CLI einen Service aus Git?

Bitte den Agenten zunächst, den Workspace zu identifizieren, und vermeide es, Slugs aus Anzeigenamen zu bilden. Vorhandene Ziele werden mit folgendem Befehl zurückgegeben:

dockup services --json

Für ein Repository, das noch nie deployed wurde, kann eine Transaktion den Service erstellen, ihn deployen, auf den Abschluss warten und das aktuelle Verzeichnis verknüpfen:

dockup create my-api \
  --repo https://github.com/acme/my-api \
  --project production \
  --deploy \
  --wait \
  --link \
  --json

Wenn das Repository ein Dockerfile enthält, verwendet Dockup dieses. Ist kein Dockerfile vorhanden, greift Dockup für die automatische Build-Erkennung auf Nixpacks zurück. Die Auswahl wird unter Nixpacks vs. Dockerfile erläutert, einschließlich der Frage, wann sich der Wartungsaufwand expliziter Build-Anweisungen lohnt.

Bevor du nach einer unterbrochenen Sitzung die Erstellung wiederholst, führe erneut dockup services --json aus und überprüfe das exakte Ziel. Wenn der Service bereits existiert, fahre mit seinem Status fort, statt eine weitere Create-Anfrage zu senden.

Nach dem Verknüpfen können Befehle in diesem Repository das Ziel aus .dockup ermitteln. Runbooks für den Produktivbetrieb sollten jedoch weiterhin den vollständigen Wert project/service dokumentieren. Die Ermittlung des Ziels bildet die sichere Grenze zwischen einer unsicheren vorherigen Aktion und einer neuen Änderung am Produktivsystem.

Wie sollten Umgebungsvariablen, Datenbanken und Health-Checks vorbereitet werden?

Halte normale Konfiguration und Secrets getrennt. Claude Code kann einen öffentlichen Laufzeitwert und ein maskiertes Secret setzen, ohne gespeicherte Secret-Werte später auszugeben:

dockup env set NODE_ENV=production \
  -s production/my-api \
  --json

dockup env set API_KEY="$API_KEY" \
  --secret \
  -s production/my-api \
  --json

Änderungen an der Umgebung werden beim nächsten Deployment wirksam. Das ist beabsichtigt: Ein laufender Container behält seine aktuelle Prozessumgebung, bis er ersetzt wird. Das vollständige Vorgehen wird unter Umgebungsvariablen und Secrets beschrieben.

Wenn die Anwendung eine verwaltete PostgreSQL-Datenbank benötigt, erstelle sie im ausgewählten Workspace und rufe ihre Details über die dokumentierten Datenbankbefehle ab:

dockup db create --name main-db --type postgresql --json
dockup db list --json

Über private Netzwerke können Services und Datenbanken später innerhalb eines Projekts stabile <slug>.internal-Hostnamen erhalten. Der Agent sollte keine Datenbank-URL erfinden. Verwende stattdessen die von Dockup zurückgegebenen Verbindungsinformationen und speichere sie als Secret.

Richte vor dem ersten wichtigen Produktions-Release ein Readiness-Gate ein:

dockup health production/my-api \
  --path /healthz \
  --interval 5 \
  --retries 5 \
  --json

Dockup führt ein Blue-Green-Deployment ohne Ausfallzeit durch und leitet den Traffic erst dann auf die neue Version um, wenn das Health-Gate erfolgreich passiert wurde. Die Architektur wird unter Deployments ohne Ausfallzeit näher erläutert.

Wie führt Claude Code ein Deployment durch und weist den Erfolg nach?

Verwende --wait; der Agent sollte „Deployment eingereiht“ nicht als „Anwendung läuft“ interpretieren:

dockup deploy production/my-api --wait --json

Das Standard-Timeout für das Warten beträgt 900 Sekunden. Bei Erfolg beendet sich der Befehl mit 0 und liefert den terminalen Status, die Dauer, die Deployment-ID und die URL zurück. Wenn der Build fehlschlägt, endet der Befehl mit einem von null verschiedenen Exit-Code und code:"deploy_failed". Läuft der Vorgang beim Erreichen des Timeouts noch, endet er ebenfalls mit einem von null verschiedenen Exit-Code und code:"deploy_timeout".

Eine hilfreiche Anweisung für Claude Code lautet: „Behandle den Prozess-Exit-Code als primäres Ergebnis und fasse anschließend die JSON-Felder zusammen.“ Dadurch vermeidet der Agent optimistische Formulierungen, wenn die Plattform bereits einen Fehler zurückgegeben hat.

Sammle nach dem Erfolg drei unabhängige Signale:

dockup status production/my-api --json
dockup uptime production/my-api --hours 24 --json
dockup security production/my-api --json

status bestätigt den Status des Services und des letzten Deployments. uptime liefert minutengenaue Monitoring-Statistiken, einschließlich der durchschnittlichen Antwortzeit und des p95-Werts. security zeigt die neuesten CVE- und Konfigurations-Scans des Images. Diese Prüfungen ergänzen Sicherheitsmaßnahmen auf Anwendungsebene, ersetzen jedoch keine Anwendungstests.

Was sollte Claude Code tun, wenn das Produktivsystem fehlschlägt?

Unterscheide zwischen Build- und Laufzeitfehlern. Bei einem fehlgeschlagenen Build wird das neueste Build-Log benötigt:

dockup logs production/my-api --build --json

Bei einem Container, der erfolgreich gebaut wurde, aber nach dem Start abstürzt, werden die Laufzeitmeldungen benötigt:

dockup logs production/my-api --json

Um einen Build zu verfolgen und dabei maschinenlesbare Batches beizubehalten, verwende den NDJSON-Follow-Modus:

dockup logs production/my-api --build -f --json

Der Befehl endet, sobald das Deployment einen terminalen Status erreicht, und beendet sich bei einem Fehlschlag mit einem von null verschiedenen Exit-Code. Claude Code kann den Fortschritt streamen, ohne eine eigene Polling-Schleife zu erfinden.

Wenn das aktuelle Release fehlerhaft ist und ein bekanntes vorheriges Deployment erneut ausgeführt werden soll, liste die Historie auf und verwende dessen exakte ID:

dockup deployments production/my-api -n 20 --json
dockup rollback <deploymentId> production/my-api --json

Der Agent sollte angeben, welche Deployment-ID er ausgewählt hat und warum. Ein Rollback ist eine operative Entscheidung und kein Ersatz dafür, die Ursache des Fehlers zu verstehen. Bewahre Build-Log, Laufzeit-Log, Exit-Code und Audit-Aufzeichnung auf, damit der Vorfall nachvollziehbar bleibt.

Ein abgeschlossener Claude-Code-Deployment-Bericht sollte Ziel, Commit oder Branch, Deployment-ID, terminalen Status, URL, verstrichene Zeit, Health-Ergebnis und alle noch offenen Risiken enthalten. Diese Nachweise machen aus einer autonomen Aktion eine überprüfbare Änderung am Produktivsystem.

Einen Completion Contract für den Produktivbetrieb definieren

Formuliere den erwarteten Abschluss bereits im Auftrag, bevor du beginnst. Eine hilfreiche Anweisung lautet: Deploye das verknüpfte Repository nach production/my-api; warte auf ein terminales Ergebnis; lösche, bereinige oder übertrage nichts; gib bei einem Fehler den Fehlercode und die letzten 60 relevanten Zeilen des Build-Logs zurück; gib bei Erfolg Status, URL, Deployment-ID, Dauer und Health-Nachweis zurück.

Diese Formulierung gibt Claude Code ein klar begrenztes Ziel und ein festgelegtes Berichtsschema. Außerdem verhindert sie, dass der Agent bei einem fehlgeschlagenen Release „hilfreicherweise“ eine unabhängige Infrastrukturänderung vornimmt. Der Agent kann eine separate Fehlerbehebung vorschlagen, die Produktionsaktion bleibt jedoch eindeutig einem Auftrag zugeordnet.

Für wiederholte Releases solltest du im Repository oder im Change-Management-System einen kurzen Release-Eintrag führen. Dokumentiere Ziel, Quell-Branch, erwarteten Health-Pfad, normales Timeout und die genehmigte Wiederherstellungsaktion. Ein Claude-Code-Deployment ist sicherer, wenn die nächste Sitzung diese Fakten nicht erst aus dem Chatverlauf rekonstruieren muss.

Die Kontogrenze vor dem ersten Schreibzugriff überprüfen

Workspaces bilden Eigentums- und Abrechnungsgrenzen. Bitte Claude Code, whoami auszugeben, Services aufzulisten und den ausgewählten Workspace zu nennen, bevor Änderungen vorgenommen werden. Der Pro-Plan kostet 20 $ pro Monat und enthält ein Nutzungsguthaben von 20 $. Er ist der empfohlene kostenpflichtige Plan. Alle kostenpflichtigen Pläne erlauben unbegrenzt viele Workspaces, Datenbanken und Deployments; die Nutzung von CPU, RAM und Speicherplatz wird pro Minute gegen das Guthaben des Plans verrechnet.

Dieses Preismodell ändert nichts an der Sicherheitsregel: Ein Agent sollte Nutzung und Zielbereich prüfen, bevor er Ressourcen skaliert oder zusätzliche Ressourcen anlegt. Im Produktionsbericht sollten Abonnementplan und tatsächlich gemessene Nutzung getrennt ausgewiesen werden.

Den Workflow in den Produktivbetrieb bringen

Installiere den Skill in derselben Umgebung, in der Claude Code ausgeführt wird, überprüfe die Authentifizierung und beginne mit einem risikoarmen Service, dessen Health-Endpoint bereits bekannt ist.

npm install -g dockup-cli
dockup skill install

Der erste Befehl installiert die CLI. Der zweite installiert den passenden Dockup-Skill für Claude Code und Codex. Starte kostenlos auf app.dockup.ai.

FAQ

Kann Claude Code mit Dockup direkt in den Produktivbetrieb deployen?

Ja. Installiere den Dockup-Skill, stelle ein eingeschränktes DOCKUP_TOKEN bereit, ermittle das exakte Ziel für Projekt und Service und führe den Deploy-Befehl mit --wait und --json aus.

Warum sollte Claude Code --wait verwenden?

Ohne --wait bedeutet eine erfolgreiche Antwort lediglich, dass das Deployment eingereiht wurde. Mit --wait beendet sich Dockup erst nach einem erfolgreichen Abschluss mit Exit-Code 0. Andernfalls werden strukturierte Fehler wie deploy_failed oder deploy_timeout zurückgegeben.

Kann Claude Code gespeicherte Secret-Werte sehen?

Dockup maskiert Secret-Werte in der Ausgabe. Der Agent kann ein Secret setzen oder ersetzen, aber beim Auslesen der Umgebungskonfiguration wird der gespeicherte Secret-Wert nicht zurückgegeben.

Was passiert, wenn ein Repository kein Dockerfile enthält?

Dockup verwendet Nixpacks, um die Anwendung automatisch zu erkennen und zu bauen. Ein Dockerfile im Repository hat Vorrang, sofern es vorhanden ist.

Wie kann Claude Code ein fehlerhaftes Release wiederherstellen?

Der Agent sollte Build- und Laufzeit-Logs prüfen, die Deployment-Historie auflisten und mit dockup rollback ein bekanntes vorheriges Deployment anhand der exakten Deployment-ID erneut ausführen.