Deployment di Claude Code: guida alla produzione

Il deployment di Claude Code diventa affidabile solo quando l’agente sa distinguere tra “richiesta accettata” e “produzione operativa”. Dockup fornisce questo livello di deployment tramite una CLI progettata per i client automatici: JSON strutturato, codici di uscita reali del processo e una modalità --wait che rimane collegata finché un deployment non raggiunge uno stato terminale.

Questa guida accompagna un repository dal lavoro locale a una release verificata in produzione. Definisce inoltre le autorizzazioni che Claude Code dovrebbe ricevere, le prove che dovrebbe restituire e il punto in cui è necessaria l’approvazione di una persona per un’azione distruttiva.

Di cosa ha bisogno il deployment di Claude Code prima di arrivare in produzione?

Un coding agent non dovrebbe iniziare indovinando il nome di un servizio o navigando in una dashboard. Forniscigli un contratto operativo circoscritto: individuare il target esatto, apportare una sola modifica prevista, attendere il risultato e restituire prove leggibili dalle macchine.

I prerequisiti di base sono semplici:

Requisito	Perché è importante	Verifica
Node.js 18 o versione successiva	Richiesto dal pacchetto Dockup CLI	node --version
Account Dockup	Gestisce workspace, servizi e database	Accedi a app.dockup.ai
Repository Git	Sorgente per la build del servizio	Verifica l’URL remoto e il branch
Token API	Autenticazione non interattiva	dockup whoami --json
Health endpoint o porta in ascolto	Determina il passaggio blue-green	dockup health ... --json

Definisci il perimetro della produzione prima che l’agente agisca. Claude Code può creare un servizio, impostare configurazioni non segrete, avviare un deployment, esaminare i log e proporre un rollback. Non dovrebbe eliminare un servizio, rimuovere un database o eliminare configurazioni senza l’approvazione esplicita di una persona.

Dockup rafforza questo limite. I comandi distruttivi rifiutano di procedere senza --yes e restituiscono un errore strutturato needs_confirm, invece di interpretare la conferma mancante come un invito a improvvisare. Per una policy più ampia, consulta le protezioni per la produzione degli agenti AI.

Come si installa la skill di Claude Code e si esegue l’autenticazione in sicurezza?

Installa la CLI, installa la skill inclusa e verifica che la skill corrisponda al binary installato:

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

L’installer scrive la skill canonica in ~/.agents/skills/dockup/ e la collega alla directory delle skill di Claude Code. Poiché la skill viene distribuita nello stesso pacchetto npm della CLI, dockup update aggiorna entrambi. Claude Code non deve affidarsi a un riferimento ai comandi copiato in precedenza che potrebbe descrivere flag non supportati dal binary locale.

Usa un token in una variabile d’ambiente per le sessioni autonome:

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

Una risposta corretta identifica l’account e indica tokenSource come env. Non incollare il token in un prompt, non eseguirne il commit nel repository e non visualizzarlo in un log CI. I valori segreti memorizzati in Dockup vengono mascherati quando la configurazione viene riletta.

La documentazione completa di riferimento di Dockup CLI è la fonte autorevole per i comandi disponibili. Con 135 comandi, Claude Code dovrebbe consultare il riferimento aggiornato e la skill inclusa nel pacchetto, invece di affidarsi a flag ricordati a memoria.

Poiché la skill è inclusa nel pacchetto CLI, dockup update aggiorna insieme l’eseguibile e le relative istruzioni. Questo allineamento delle versioni è più sicuro che copiare un elenco di comandi in un prompt destinato a rimanere in uso a lungo.

In che modo Dockup CLI crea un servizio da Git?

Chiedi innanzitutto all’agente di identificare il workspace ed evita di costruire gli slug a partire dai nomi visualizzati. I target esistenti vengono restituiti da:

dockup services --json

Per un repository che non è mai stato sottoposto a deployment, una singola transazione può creare il servizio, eseguire il deployment, attenderne il completamento e collegare la directory corrente:

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

Quando il repository contiene un Dockerfile, Dockup lo utilizza. In sua assenza, Dockup ricorre a Nixpacks per il rilevamento automatico della build. La scelta è spiegata nell’articolo Nixpacks o Dockerfile, che illustra anche quando istruzioni di build esplicite giustificano il costo di manutenzione.

Prima di ritentare la creazione dopo una sessione interrotta, esegui di nuovo dockup services --json e controlla il target esatto. Se il servizio esiste già, riparti dal suo stato invece di inviare un’altra richiesta di creazione.

Una volta collegato, i comandi eseguiti in quel repository possono risolvere il target da .dockup, ma i runbook di produzione dovrebbero comunque registrare il valore completo project/service. La fase di discovery rappresenta il confine sicuro tra un’azione precedente dal risultato incerto e una nuova modifica in produzione.

Come si preparano variabili d’ambiente, database e health check?

Mantieni separati la configurazione ordinaria e i segreti. Claude Code può impostare un valore runtime pubblico e un segreto mascherato senza stampare in seguito i valori segreti memorizzati:

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

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

Le modifiche all’ambiente vengono applicate al deployment successivo. È una scelta intenzionale: un container in esecuzione conserva l’ambiente del processo corrente finché non viene sostituito. Il workflow operativo completo è descritto nell’articolo variabili d’ambiente e segreti.

Se l’applicazione necessita di un database PostgreSQL gestito, crealo nel workspace selezionato e leggine i dettagli tramite i comandi documentati per i database:

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

In seguito, il networking privato può fornire ai servizi e ai database hostname stabili <slug>.internal all’interno dello stesso progetto. Non chiedere all’agente di inventare un URL del database; usa le informazioni di connessione restituite da Dockup e memorizzale come segreto.

Configura un readiness gate prima della prima release importante in produzione:

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

Dockup esegue deployment blue-green senza downtime e inoltra il traffico alla nuova versione solo dopo il superamento dell’health gate. L’architettura è approfondita nell’articolo sui deployment senza downtime.

Come esegue Claude Code il deployment e dimostra che è riuscito?

Usa --wait; non lasciare che l’agente interpreti “deployment accodato” come “applicazione in esecuzione”:

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

Il timeout predefinito di attesa è di 900 secondi. In caso di successo, il comando termina con codice 0 e restituisce lo stato terminale, la durata, l’ID del deployment e l’URL. Se la build non riesce, termina con un codice diverso da zero e code:"deploy_failed". Se l’operazione è ancora in corso allo scadere del timeout, termina con un codice diverso da zero e code:"deploy_timeout".

Un’istruzione utile per Claude Code è: “Considera il codice di uscita del processo il risultato principale, quindi riepiloga i campi JSON”. In questo modo si evita un linguaggio eccessivamente ottimistico quando la piattaforma ha già restituito un errore.

Dopo il successo, raccogli tre segnali indipendenti:

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

status conferma lo stato del servizio e dell’ultimo deployment. uptime restituisce statistiche di monitoraggio minuto per minuto, inclusi il tempo medio di risposta e il p95. security mostra l’ultima scansione delle CVE dell’immagine e della configurazione. Questi controlli completano le pratiche di sicurezza a livello applicativo, ma non sostituiscono i test dell’applicazione.

Cosa dovrebbe fare Claude Code quando la produzione non funziona?

Distingui un errore di build da un errore runtime. Una build non riuscita richiede l’ultimo log di build:

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

Un container che ha completato la build ma va in crash dopo l’avvio richiede l’output runtime:

dockup logs production/my-api --json

Per osservare una build mantenendo batch leggibili dalle macchine, usa la modalità di follow NDJSON:

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

Il comando si arresta quando il deployment raggiunge uno stato terminale e termina con un codice diverso da zero se il deployment non è riuscito. Claude Code può trasmettere l’avanzamento senza inventare un ciclo di polling.

Se la release corrente non è sana e deve essere rieseguito un deployment precedente noto, elenca la cronologia e usa il relativo ID esatto:

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

L’agente dovrebbe indicare quale ID di deployment ha selezionato e perché. Il rollback è una decisione operativa, non un sostituto della comprensione del problema. Conserva il log di build, il log runtime, il codice di uscita e il record di audit, in modo che l’incidente possa essere ricostruito.

Un report completo del deployment di Claude Code dovrebbe includere il target, il commit o il branch, l’ID del deployment, lo stato terminale, l’URL, il tempo trascorso, il risultato dell’health check e gli eventuali rischi residui. Queste prove trasformano un’azione autonoma in una modifica alla produzione verificabile.

Definisci un contratto di completamento per la produzione

Prima di iniziare, inserisci nel task il contratto di completamento previsto. Una richiesta utile è: esegui il deployment del repository collegato su production/my-api; attendi un risultato terminale; non eliminare, rimuovere o trasferire nulla; in caso di errore, restituisci il codice dell’errore e le ultime 60 righe rilevanti del log di build; in caso di successo, restituisci stato, URL, ID del deployment, durata e prove dell’health check.

Questa formulazione assegna a Claude Code un obiettivo circoscritto e uno schema di report. Impedisce inoltre all’agente di modificare “utilmente” infrastrutture non correlate quando la release non riesce. L’agente può proporre una correzione separata, ma l’azione in produzione resta riconducibile a una singola richiesta.

Per le release ripetute, conserva un breve record della release nel repository o nel sistema di change management. Registra il target, il branch sorgente, il percorso previsto per l’health check, il timeout normale e l’azione di recovery approvata. Un deployment di Claude Code è più sicuro quando la sessione successiva non deve ricostruire questi dati dalla cronologia della chat.

Verifica il perimetro dell’account prima della prima scrittura

I workspace definiscono i confini di proprietà e fatturazione. Chiedi a Claude Code di mostrare whoami, elencare i servizi e indicare il workspace selezionato prima di modificare qualsiasi elemento. Il piano Pro costa 20 $ al mese e include 20 $ di credito per l’utilizzo; è il piano a pagamento consigliato. Tutti i piani a pagamento consentono workspace, database e deployment illimitati, mentre l’utilizzo di CPU, RAM e disco viene misurato al minuto e scalato dal saldo del piano.

Questo modello di prezzi non cambia la regola di sicurezza: un agente dovrebbe controllare l’utilizzo e l’ambito del target prima di aumentare le risorse o crearne di aggiuntive. Il report di produzione dovrebbe distinguere il piano di abbonamento dal consumo effettivo misurato.

Porta il workflow in produzione

Installa la skill nello stesso ambiente in cui verrà eseguito Claude Code, verifica l’autenticazione e inizia con un servizio a basso rischio il cui health endpoint sia già noto.

npm install -g dockup-cli
dockup skill install

Il primo comando installa la CLI. Il secondo installa la skill Dockup compatibile con Claude Code e Codex. Inizia gratuitamente su app.dockup.ai.

FAQ

Claude Code può eseguire direttamente il deployment in produzione con Dockup?

Sì. Installa la skill Dockup, fornisci un DOCKUP_TOKEN con ambito limitato, risolvi il target esatto project/service ed esegui il comando di deployment con --wait e --json.

Perché Claude Code dovrebbe usare --wait?

Senza --wait, una risposta corretta indica soltanto che il deployment è stato accodato. Con --wait, Dockup termina con codice 0 solo dopo il successo e restituisce altrimenti gli errori strutturati deploy_failed o deploy_timeout.

Claude Code può visualizzare i valori dei segreti memorizzati?

Dockup maschera i valori segreti nell’output. L’agente può impostare o sostituire un segreto, ma la lettura della configurazione dell’ambiente non restituisce il valore segreto memorizzato.

Cosa succede quando un repository non contiene un Dockerfile?

Dockup usa Nixpacks per rilevare e compilare automaticamente l’applicazione. Se presente, il Dockerfile del repository ha la precedenza.

Come può Claude Code riprendersi da una release problematica?

Dovrebbe esaminare i log di build e runtime, elencare la cronologia dei deployment e rieseguire un deployment precedente noto con dockup rollback, usando l’ID esatto del deployment.