Dal repository Git alla produzione: guida al deployment con Dockup

Portare un repository Git in produzione richiede più che collegare un remote e premere deploy. La piattaforma deve conoscere il service target, il branch, il metodo di build, il comando di avvio, la porta in ascolto, l’ambiente, il controllo di salute e il percorso di ripristino. Dockup rende esplicite queste decisioni supportando sia le build automatiche con Nixpacks sia i Dockerfile gestiti nel repository.

Questa guida parte da un repository che non è mai stato sottoposto a deploy e arriva a un URL verificato, alla cronologia dei deployment, ai log e a un comando di rollback testato.

Cosa verificare prima del primo deploy in produzione?

Verifica che il repository sia deployable senza dipendenze da stato locale non documentato. Un clone pulito dovrebbe contenere tutto ciò che serve per installare le dipendenze e avviare l’applicazione, ad eccezione dei secrets.

Usa questa checklist:

Controllo	Risultato atteso
Branch predefinito	Esiste il branch destinato alla produzione
Lockfile delle dipendenze	È versionato per garantire installazioni riproducibili
Processo di avvio	Si associa alla porta configurata e a 0.0.0.0
Endpoint di health	Restituisce un esito positivo senza effetti collaterali esterni
Migrazioni del database	Dispongono di un piano di esecuzione sicuro ed esplicito
Secrets	Sono archiviati al di fuori di Git
File persistenti	Usano un volume, non il filesystem del container
Rollback	Il deployment precedente può essere eseguito di nuovo

Installa la CLI e autentica il tuo account:

npm install -g dockup-cli
export DOCKUP_TOKEN="<TOKEN>"
dockup whoami --json

Elenca i service esistenti prima di crearne uno:

dockup services --json

In questo modo eviti di creare risorse duplicate e confermi la convenzione esatta per workspace e target.

In che modo Dockup create supporta il deployment da Git?

In genere, il comando per il primo deploy crea il service, esegue il deploy, attende il risultato e collega la directory corrente:

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

Il target risultante è production/api. Il link .dockup consente ai comandi successivi di risolvere quel service quando vengono eseguiti all’interno del repository, ma la documentazione di produzione dovrebbe comunque riportare il target completo.

Dopo un tentativo di provisioning interrotto, elenca i service e controlla il target esatto prima di eseguire nuovamente la creazione:

dockup services --json

Se production/api esiste già, continua leggendo il suo stato e la cronologia dei deployment. In questo modo eviti di trasformare un risultato di rete incerto in un service duplicato. Mantieni le credenziali di accesso al repository al di fuori del controllo versione e dell’output dei comandi.

Come sceglie Dockup tra Nixpacks e Dockerfile?

Se il repository contiene un Dockerfile, Dockup lo utilizza. In caso contrario, Nixpacks rileva automaticamente l’applicazione e la compila. Questo ordine rende autorevole la definizione esplicita del container presente nel repository.

Nixpacks è una buona prima scelta quando l’applicazione segue le convenzioni comuni del proprio ecosistema e non richiede personalizzazioni a livello di sistema operativo. Un Dockerfile è utile quando servono una base image specifica, pacchetti di sistema, una build multi-stage, un custom runtime user o confini esatti per le operazioni di copy.

Non è necessario aggiungere un Dockerfile vuoto solo per “dare un’impressione di prontezza alla produzione”. Un Dockerfile errato può essere meno riproducibile di una build automatica convenzionale. Usa il processo decisionale descritto in Nixpacks vs Dockerfile.

Controlla il service dopo la creazione:

dockup info production/api --json

La risposta include l’URL del repository, il branch, il tipo di deployment, la porta, le impostazioni di build e avvio, le chiavi dell’ambiente, i custom domain e i dati dell’ultimo deployment.

Se i comandi rilevati richiedono un override, usa le impostazioni documentate:

dockup set production/api \
  --build "npm ci && npm run build" \
  --start "npm start" \
  --port 3000 \
  --json

Le impostazioni vengono applicate al deployment successivo.

Come si configurano l’ambiente di produzione e il controllo di salute?

Aggiungi separatamente i valori ordinari e i secrets:

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

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

I valori secret vengono mascherati quando si elenca l’ambiente. Possono essere impostati o sostituiti, ma il valore memorizzato non viene restituito.

Le modifiche all’ambiente richiedono un nuovo deployment, perché il processo in esecuzione non può ricevere retroattivamente un nuovo ambiente. L’intero ciclo di vita è descritto in variabili d’ambiente e secrets.

Configura un health gate che rappresenti lo stato di readiness:

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

Dockup utilizza un flusso blue-green senza downtime e invia il traffico al nuovo deployment solo dopo il superamento del controllo di readiness. Se non è configurato alcun percorso HTTP, il gate può ricorrere alla readiness della porta TCP.

Un health route dovrebbe verificare che il processo dell’applicazione sia pronto a gestire le richieste. Evita di eseguire controlli distruttivi o test completi del sistema particolarmente costosi. Controlli approfonditi sulle dipendenze possono generare falsi outage quando un service opzionale è degradato.

Come si eseguono, monitorano e verificano i deployment in produzione?

Avvia il release e attendi uno stato terminale:

dockup deploy production/api --wait --json

Il timeout predefinito è di 900 secondi. Il codice di uscita 0 indica il successo. deploy_failed e deploy_timeout producono risultati diversi da zero, quindi gli shell script e i sistemi CI si arrestano correttamente.

Per monitorare la build in formato NDJSON:

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

Lo stream termina in caso di successo o di errore. Se la build ha esito positivo ma il container va in crash, controlla i runtime log:

dockup logs production/api --json

Dopo un release completato correttamente, verifica lo stato della piattaforma e il comportamento pubblico:

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

Le sonde di uptime vengono eseguite ogni minuto e riportano il tempo di risposta medio e p95. La scansione di sicurezza controlla le CVE dell’immagine e la configurazione. Aggiungi uno smoke test specifico dell’applicazione per l’endpoint effettivamente utilizzato dal business: la readiness della piattaforma è necessaria, ma non sufficiente.

Il metodo dettagliato per i log è disponibile in debug dei log di build e runtime.

Come introdurre deployment automatici e preview?

Esegui il primo release in produzione manualmente, osservando ogni passaggio. Quando build, health gate e percorso di rollback sono verificati, abilita il deployment a ogni push:

dockup auto-deploy production/api --on --json

Il deployment automatico dovrebbe seguire un branch protetto e una policy di code review. Un push è un trigger di produzione, quindi i permessi sul repository diventano permessi sull’infrastruttura.

Le preview di pull request e branch forniscono URL e ambienti isolati:

dockup pr-preview production/api --on --json
dockup preview branch feature/login production/api --json

In un progetto con networking privato, le preview entrano nella rete del progetto. Possono raggiungere lo stesso database di produzione all’indirizzo <slug>.internal, ma Dockup crea automaticamente un database user di sola lettura per la preview. La preview può consultare dati con la stessa struttura di quelli di produzione senza modificarli.

Questo non elimina gli obblighi relativi alla privacy. L’accesso alle preview dovrebbe comunque essere limitato, sottoposto ad audit e utilizzato solo quando è consentito leggere i dati di produzione.

Come si esegue il rollback di un deployment errato?

Conserva le evidenze prima di avviare il ripristino. Leggi i log di build in caso di errore di build e i runtime log in caso di crash. Poi elenca la cronologia dei deployment:

dockup deployments production/api -n 20 --json

Seleziona un deployment ID di cui conosci stato e timestamp, quindi eseguilo nuovamente:

dockup rollback <deploymentId> production/api --json

Un rollback dovrebbe essere un’azione esplicita di incident response. Registra l’ID del deployment fallito, l’ID del recovery selezionato, il motivo e la correzione successiva. Se una migrazione del database non è backward compatible, il solo rollback dell’applicazione potrebbe non ripristinare la compatibilità; la progettazione delle migrazioni deve far parte del piano di release.

La guida al deployment senza downtime spiega il traffic cutover, mentre la reference della Dockup CLI documenta tutti i flag dei comandi.

Registro di completamento del primo deploy

Al termine del workflow dal repository Git alla produzione, registra:

• Target project/service esatto.
• Repository e branch di produzione.
• Metodo di build: Nixpacks o Dockerfile.
• Comandi di build e avvio, se sovrascritti.
• Porta in ascolto e health path.
• Deployment ID e stato terminale.
• URL di produzione e piano per il custom domain.
• Verifica di uptime e sicurezza.
• Deployment ID del rollback o regola di selezione.

Questo registro trasforma il secondo deployment in un’operazione ordinaria, anziché in un’altra attività di esplorazione.

Separa lo stato dell’applicazione dall’immagine del container

Il filesystem scrivibile all’interno del container di un service dovrebbe essere considerato sostituibile. Un nuovo deployment crea una nuova versione e un rollback esegue nuovamente un’immagine precedente; i file scritti solo all’interno del vecchio container non costituiscono una strategia di persistenza dei dati.

Usa database gestiti per lo stato relazionale, documentale o di cache e collega un volume per i file che devono persistere tra i deployment. Verifica i mount path prima del primo release in produzione. Una directory per gli upload del container che non è mai stata montata può sembrare funzionante finché il deployment successivo non elimina i dati.

Consulta volumi persistenti e snapshot prima di spostare i file generati dagli utenti. Per lo stato del database, usa il sistema di backup specifico del database invece di considerare lo snapshot di un volume attivo come un backup coerente a livello transazionale.

Stima il primo mese senza inventare un costo fisso dell’istanza

Dockup misura il consumo di CPU, RAM e disco ogni minuto e sottrae l’utilizzo dal saldo del piano. Il piano Free include un credito iniziale di 10 $ e fino a tre deployment; il piano Pro consigliato costa 20 $ al mese e include 20 $ di credito per l’utilizzo.

Dopo che il service ha iniziato a ricevere traffico reale, controlla il consumo di CPU, RAM e disco in app.dockup.ai. Usa il consumo osservato al minuto, non un massimo ipotizzato, per decidere se il service, il database o il disco persistente richiedono modifiche.

Verifica un secondo deployment pulito

Dopo il primo release, apporta una modifica innocua sottoposta a review ed esegui nuovamente il deploy. In questo modo confermi che il link al repository, le ipotesi sulla build cache, l’health gate, l’ambiente e la cronologia funzionino come processo continuativo, non come risultato di un provisioning eseguito una sola volta.

Mantieni esplicito il target

Registra la stringa project/service finale.

Conserva l’URL del release

Registra l’URL di produzione accanto al deployment ID.

Conferma il trigger successivo

Registra se i release futuri saranno manuali o utilizzeranno l’opzione deploy-on-push. In questo modo mantieni allineate le autorizzazioni del repository, la protezione dei branch e le aspettative sulla produzione dopo il primo deployment.

Inizia con un deployment verificabile

Scegli un repository di piccole dimensioni con un comando di avvio e un health route chiari, quindi documenta il target esatto e il rollback ID dopo il primo release completato correttamente.

Inizia gratis su app.dockup.ai. Il piano Free costa 0 $ al mese, include 10 $ di credito iniziale e supporta un workspace, tre database e tre deployment.

FAQ

Dockup può eseguire il deploy di un repository senza Dockerfile?

Sì. Quando non è presente alcun Dockerfile, Dockup utilizza Nixpacks per rilevare e compilare automaticamente l’applicazione.

Cosa fa dockup create --link?

Scrive un link .dockup nella directory corrente, così i comandi successivi possono risolvere il target project/service associato.

Perché il primo deploy dovrebbe usare --wait?

Mantiene il comando collegato fino a quando il deployment raggiunge lo stato di successo, errore o timeout e restituisce un exit code che rappresenta correttamente il risultato terminale.

Le modifiche alle variabili d’ambiente vengono applicate immediatamente?

No. Vengono applicate a un nuovo container durante il deployment successivo, quindi devi eseguire nuovamente il deploy del service dopo aver modificato la configurazione dell’ambiente.

Come esegue Dockup il rollback di un’applicazione?

Elenca la cronologia dei deployment, identifica un deployment ID precedente noto e usa dockup rollback con quell’ID e il target esatto del service.