Wdrażanie Claude Code: przewodnik produkcyjny

Wdrażanie Claude Code jest niezawodne tylko wtedy, gdy agent potrafi odróżnić komunikat „żądanie zaakceptowane” od informacji „produkcja działa poprawnie”. Dockup udostępnia warstwę wdrażania za pośrednictwem CLI zaprojektowanego z myślą o wywołaniach maszynowych: ustrukturyzowany JSON, rzeczywiste kody wyjścia procesów oraz tryb --wait, który pozostaje aktywny do momentu, aż wdrożenie osiągnie stan końcowy.

W tym przewodniku repozytorium przechodzi od lokalnych prac do zweryfikowanego wydania produkcyjnego. Określamy również uprawnienia, które powinien otrzymać Claude Code, informacje, które powinien zwrócić, oraz moment, w którym człowiek musi zatwierdzić destrukcyjną operację.

Czego Claude Code potrzebuje przed wdrożeniem na produkcję?

Agent kodujący nie powinien zaczynać od zgadywania nazwy usługi ani przeklikiwania panelu. Zapewnij mu precyzyjny kontrakt działania: zidentyfikowanie właściwego celu, wykonanie jednej zamierzonej zmiany, oczekiwanie na wynik oraz przekazanie ustrukturyzowanych, czytelnych dla maszyn dowodów.

Podstawowe wymagania są proste:

Wymaganie	Dlaczego ma znaczenie	Weryfikacja
Node.js 18 lub nowszy	Wymagany przez pakiet Dockup CLI	node --version
Konto Dockup	Jest właścicielem workspace’ów, usług i baz danych	Zaloguj się na app.dockup.ai
Repozytorium Git	Źródło do zbudowania usługi	Sprawdź zdalny URL i branch
Token API	Uwierzytelnianie bez interakcji	dockup whoami --json
Endpoint health check lub nasłuchujący port	Kontroluje przełączenie blue-green	dockup health ... --json

Zdefiniuj granicę produkcji, zanim agent zacznie działać. Claude Code może utworzyć usługę, ustawić niesekretną konfigurację, uruchomić wdrożenie, sprawdzić logi i zaproponować rollback. Nie powinien usuwać usługi, usuwać bazy danych ani czyścić konfiguracji bez wyraźnej zgody człowieka.

Dockup wzmacnia tę granicę. Destrukcyjne polecenia odmawiają wykonania bez --yes i zwracają ustrukturyzowany błąd needs_confirm, zamiast traktować brak potwierdzenia jako zachętę do improwizacji. Szersze zasady znajdziesz w artykule production guardrails for AI agents.

Jak zainstalować skill Claude Code i bezpiecznie się uwierzytelnić?

Zainstaluj CLI, zainstaluj dołączony skill i sprawdź, czy skill odpowiada zainstalowanemu plikowi binarnemu:

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

Instalator zapisuje kanoniczny skill w ~/.agents/skills/dockup/ i tworzy do niego dowiązanie w katalogu skillów Claude Code. Ponieważ skill jest dostarczany w tym samym pakiecie npm co CLI, dockup update aktualizuje oba elementy. Claude Code nie musi polegać na skopiowanej referencji poleceń, która może opisywać flagi nieobsługiwane przez jego lokalny plik binarny.

W sesjach autonomicznych używaj tokenu ze zmiennej środowiskowej:

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

Pomyślna odpowiedź identyfikuje konto i podaje tokenSource jako env. Nie wklejaj tokenu do promptu, nie zapisuj go w repozytorium ani nie wypisuj w logu CI. Wartości sekretów przechowywanych w Dockup są maskowane podczas odczytu konfiguracji.

Pełna dokumentacja Dockup CLI jest źródłem informacji o aktualnym interfejsie poleceń. Przy 135 poleceniach Claude Code powinien korzystać z bieżącej dokumentacji i dołączonego skilla, zamiast polegać na zapamiętanych flagach.

Ponieważ skill jest dostarczany wewnątrz pakietu CLI, dockup update aktualizuje jednocześnie plik wykonywalny i jego instrukcje. Takie dopasowanie wersji jest bezpieczniejsze niż kopiowanie listy poleceń do długo używanego promptu.

Jak Dockup CLI tworzy usługę z Git?

Najpierw poproś agenta o zidentyfikowanie workspace’u i nie pozwól mu konstruować slugów na podstawie nazw wyświetlanych użytkownikowi. Istniejące cele zwrócisz za pomocą:

dockup services --json

W przypadku repozytorium, które nigdy wcześniej nie było wdrażane, jedna transakcja może utworzyć usługę, wdrożyć ją, poczekać na zakończenie i połączyć z bieżącym katalogiem:

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

Gdy repozytorium zawiera Dockerfile, Dockup go wykorzystuje. W przeciwnym razie Dockup korzysta z Nixpacks do automatycznego wykrywania sposobu budowania. Wyjaśnienie tego wyboru, w tym sytuacje, w których jawne instrukcje budowania uzasadniają dodatkowy koszt utrzymania, znajdziesz w artykule Nixpacks vs Dockerfile.

Zanim ponowisz tworzenie po przerwanej sesji, ponownie uruchom dockup services --json i sprawdź dokładny cel. Jeśli usługa już istnieje, kontynuuj na podstawie jej statusu zamiast wysyłać kolejne żądanie utworzenia.

Po połączeniu polecenia wykonywane w tym repozytorium mogą rozpoznawać cel na podstawie .dockup, ale runbooki produkcyjne nadal powinny zapisywać pełną wartość project/service. Rozpoznanie celu stanowi bezpieczną granicę między niepewnym poprzednim działaniem a nową mutacją w środowisku produkcyjnym.

Jak przygotować zmienne środowiskowe, bazy danych i health checki?

Zwykłą konfigurację trzymaj oddzielnie od sekretów. Claude Code może ustawić publiczną wartość uruchomieniową i zamaskowany sekret, a później odczytać konfigurację bez wypisywania zapisanych wartości sekretów:

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

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

Zmiany zmiennych środowiskowych zostaną zastosowane przy następnym wdrożeniu. To zamierzone zachowanie: działający kontener zachowuje bieżące środowisko procesu do czasu zastąpienia go nowym. Kompletny sposób pracy opisano w artykule zmienne środowiskowe i sekrety.

Jeśli aplikacja potrzebuje zarządzanej bazy PostgreSQL, utwórz ją w wybranym workspace’ie i odczytaj jej dane za pomocą udokumentowanych poleceń baz danych:

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

Prywatna sieć może później zapewnić usługom i bazom danych stabilne nazwy hostów <slug>.internal wewnątrz jednego projektu. Nie pozwalaj agentowi wymyślać adresu URL bazy danych — użyj informacji o połączeniu zwróconych przez Dockup i zapisz je jako sekret.

Skonfiguruj bramkę gotowości przed pierwszym istotnym wydaniem produkcyjnym:

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

Dockup wykonuje wdrożenie blue-green bez przestoju i kieruje ruch do nowej wersji dopiero po pomyślnym przejściu bramki health check. Architektura została omówiona w artykule wdrożenia bez przestoju.

Jak Claude Code wdraża aplikację i potwierdza powodzenie?

Używaj --wait; nie pozwalaj agentowi interpretować komunikatu „wdrożenie dodane do kolejki” jako „aplikacja działa”:

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

Domyślny timeout oczekiwania wynosi 900 sekund. Po pomyślnym zakończeniu polecenie kończy się kodem 0 i zwraca status końcowy, czas trwania, identyfikator wdrożenia oraz URL. Jeśli budowanie się nie powiedzie, polecenie kończy się kodem różnym od zera i zwraca code:"deploy_failed". Jeśli operacja nadal trwa po upływie limitu czasu, polecenie kończy się kodem różnym od zera i zwraca code:"deploy_timeout".

Przydatna instrukcja dla Claude Code brzmi: „Traktuj kod wyjścia procesu jako podstawowy wynik, a następnie podsumuj pola JSON”. Zapobiega to optymistycznym komunikatom, gdy platforma zwróciła już błąd.

Po pomyślnym zakończeniu zbierz trzy niezależne sygnały:

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

status potwierdza stan usługi i najnowszego wdrożenia. uptime zwraca statystyki monitorowania minuta po minucie, w tym średni czas odpowiedzi i p95. security pokazuje najnowsze CVE obrazu oraz wyniki skanowania konfiguracji. Kontrole te uzupełniają praktyki bezpieczeństwa na poziomie aplikacji, ale nie zastępują testów aplikacji.

Co Claude Code powinien zrobić, gdy produkcja przestanie działać?

Oddziel awarię budowania od awarii środowiska uruchomieniowego. W przypadku nieudanego budowania potrzebujesz najnowszego logu budowania:

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

Kontener, który został zbudowany, ale ulega awarii po uruchomieniu, wymaga logu środowiska uruchomieniowego:

dockup logs production/my-api --json

Aby obserwować budowanie przy zachowaniu czytelnych maszynowo partii danych, użyj trybu śledzenia NDJSON:

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

Polecenie zatrzymuje się, gdy wdrożenie osiągnie stan końcowy, i kończy się kodem różnym od zera, jeśli wdrożenie się nie powiedzie. Claude Code może przesyłać postęp bez tworzenia własnej pętli odpytywania.

Jeśli bieżące wydanie jest niezdrowe i należy ponownie uruchomić znane wcześniejsze wdrożenie, wyświetl historię i użyj jego dokładnego identyfikatora:

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

Agent powinien podać wybrany identyfikator wdrożenia oraz uzasadnienie wyboru. Rollback jest decyzją operacyjną, a nie substytutem zrozumienia przyczyny awarii. Zachowaj log budowania, log środowiska uruchomieniowego, kod wyjścia i zapis audytowy, aby można było odtworzyć przebieg incydentu.

Gotowy raport z wdrożenia Claude Code powinien zawierać cel, commit lub branch, identyfikator wdrożenia, status końcowy, URL, czas trwania, wynik health checka oraz wszelkie ryzyka wymagające dalszych działań. Takie informacje zamieniają autonomiczne działanie w możliwą do przejrzenia zmianę produkcyjną.

Zdefiniuj kontrakt ukończenia wdrożenia produkcyjnego

Przed rozpoczęciem umieść w zadaniu oczekiwany kontrakt ukończenia. Przydatne polecenie może brzmieć: wdróż połączone repozytorium do production/my-api; poczekaj na wynik końcowy; nie usuwaj, nie czyść ani nie przenoś żadnych zasobów; w przypadku niepowodzenia zwróć kod błędu i 60 ostatnich istotnych wierszy logu budowania; po sukcesie zwróć status, URL, identyfikator wdrożenia, czas trwania i informacje potwierdzające stan health checka.

Takie sformułowanie daje Claude Code jasno ograniczony cel i schemat raportowania. Zapobiega również „pomocniczym” zmianom niezwiązanej infrastruktury, gdy wydanie się nie powiedzie. Agent może zaproponować osobną poprawkę, ale działanie produkcyjne pozostaje przypisane do jednego żądania.

W przypadku powtarzających się wydań przechowuj niewielki rejestr wydań w repozytorium lub systemie zarządzania zmianami. Zapisuj cel, branch źródłowy, oczekiwaną ścieżkę health checka, standardowy timeout i zatwierdzoną czynność naprawczą. Wdrażanie Claude Code jest bezpieczniejsze, gdy kolejna sesja nie musi odtwarzać tych informacji z historii czatu.

Zweryfikuj granicę konta przed pierwszym zapisem

Workspace’y wyznaczają granice własności i rozliczeń. Poproś Claude Code o wyświetlenie whoami, listy usług oraz wskazanie wybranego workspace’u, zanim agent zmodyfikuje jakiekolwiek zasoby. Plan Pro kosztuje 20 USD miesięcznie i obejmuje 20 USD kredytu na użycie; jest to zalecany plan płatny. Wszystkie płatne plany pozwalają na nieograniczoną liczbę workspace’ów, baz danych i wdrożeń, natomiast zużycie CPU, pamięci RAM i dysku jest mierzone co minutę i rozliczane z salda planu.

Ten model cenowy nie zmienia zasady bezpieczeństwa: agent powinien sprawdzić zużycie i zakres celu przed skalowaniem lub tworzeniem dodatkowych zasobów. Raport produkcyjny powinien rozróżniać plan subskrypcji od rzeczywistego zużycia mierzonego.

Przenieś ten proces na produkcję

Zainstaluj skill w tym samym środowisku, w którym będzie działać Claude Code, zweryfikuj uwierzytelnianie i rozpocznij od usługi o niskim ryzyku, której endpoint health checka jest już znany.

npm install -g dockup-cli
dockup skill install

Pierwsze polecenie instaluje CLI. Drugie instaluje pasujący skill Dockup dla Claude Code i Codex. Zacznij bezpłatnie na app.dockup.ai.

FAQ

Czy Claude Code może wdrażać bezpośrednio na produkcję za pomocą Dockup?

Tak. Zainstaluj skill Dockup, przekaż ograniczony zakresem DOCKUP_TOKEN, rozpoznaj dokładny cel w formacie projekt/usługa i uruchom polecenie wdrożenia z --wait oraz --json.

Dlaczego Claude Code powinien używać --wait?

Bez --wait pomyślna odpowiedź oznacza tylko, że wdrożenie zostało dodane do kolejki. Z --wait Dockup kończy się kodem 0 dopiero po pomyślnym zakończeniu i w przeciwnym razie zwraca ustrukturyzowane błędy deploy_failed lub deploy_timeout.

Czy Claude Code widzi zapisane wartości sekretów?

Dockup maskuje wartości sekretów w danych wyjściowych. Agent może ustawić lub zastąpić sekret, ale odczyt konfiguracji środowiska nie zwraca zapisanej wartości sekretu.

Co się dzieje, gdy repozytorium nie zawiera Dockerfile?

Dockup używa Nixpacks do automatycznego wykrycia i zbudowania aplikacji. Dockerfile znajdujący się w repozytorium ma pierwszeństwo, jeśli jest obecny.

Jak Claude Code może odzyskać działanie po nieudanym wydaniu?

Powinien sprawdzić logi budowania i środowiska uruchomieniowego, wyświetlić historię wdrożeń oraz ponownie uruchomić znane wcześniejsze wdrożenie za pomocą dockup rollback, używając dokładnego identyfikatora wdrożenia.