SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Docker Compose: differenza tra build e image su VPS

Scopri cosa fanno build e image in Docker Compose su un VPS, perché compose up ignora le modifiche al Dockerfile e quando usare docker compose build.

Docker Compose: differenza tra build e image, in breve

In un file Docker Compose, image: identifica l'immagine da usare, inclusi un'immagine locale, un tag o un riferimento a un digest, mentre build: indica a Compose come crearne una dal codice sorgente. Imposta solo image: e Compose usa o scarica l'immagine in base a pull_policy. Imposta solo build: e Compose crea l'immagine con il builder configurato, assegnandole un nome derivato dal nome del progetto e da quello del servizio. Imposta entrambi e pull_policy controlla se Compose scarica o crea l'immagine; quando la crea, assegna al risultato il nome indicato in image:. Questo consente di creare un'immagine e pubblicarla con il nome scelto. Il builder può essere eseguito localmente oppure su un Docker host remoto.

Questa è l'intera distinzione. Il resto spiega cosa comporta operativamente su un server. Si presume che Docker Engine e il plugin Compose siano già installati; eseguire Docker su un VPS tratta questo aspetto.

Le tre forme complete

Usa un tag pubblicato, scaricandolo se non è disponibile secondo la policy di pull predefinita. Non viene usato alcun Dockerfile.

services:
  web:
    image: nginx:1.27
    restart: unless-stopped
    ports:
      - "80:80"

Esegui la build a partire da un Dockerfile nella directory del progetto. La build può anche scaricare immagini e dipendenze richieste dal Dockerfile.

services:
  web:
    build: .
    restart: unless-stopped
    ports:
      - "80:80"

Esegui la build e assegna al risultato il tag docker compose build; senza una policy di pull esplicita, up prova a scaricare questa immagine prima di eseguirne la build. docker compose push può quindi inviare esattamente questo tag a un registry.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: registry.example.com/acme/web:1.4.2
    restart: unless-stopped
    ports:
      - "80:80"

context è la directory inviata al builder. dockerfile viene risolto rispetto a quel contesto, quindi context: . con dockerfile: docker/prod.Dockerfile è normale e corretto. Esegui docker compose images per visualizzare il nome dell'immagine e l'ID dell'immagine associati a ogni container del servizio; controlla il file Compose per confermare se il servizio usa image:, build: o entrambi.

Perché docker compose up non ricrea l'immagine dopo una modifica al Dockerfile?

Perché il normale up riutilizza un'immagine esistente, a meno che non si richieda una build o non si configuri un criterio che la imponga.

Quando Compose avvia un servizio che contiene solo una sezione build:, usa l'immagine esistente, se disponibile. Non legge il Dockerfile, non confronta i file sorgente e non controlla alcun timestamp. Se sono presenti image: e build: e non è specificato pull_policy, Compose prova prima a eseguire il pull e avvia una build se l'immagine non è disponibile nel registry o nella cache della piattaforma. La presenza dell'immagine è considerata sufficiente.

Quindi si modifica app.py, si esegue docker compose up -d, si osserva Compose segnalare che il container è in esecuzione e viene servito il codice precedente. Non si è verificato alcun errore, quindi non viene visualizzato alcun avviso. L'indicatore è la parola di stato che Compose stampa accanto al nome del container: un container sostituito da Compose viene indicato come ricreato o avviato, mentre un container che Compose ha deciso di non modificare viene indicato come in esecuzione.

Due controlli sono sufficienti. docker compose images stampa l'ID dell'immagine utilizzata da ciascun container; annotalo prima del deploy e confrontalo dopo. docker image ls include una colonna CREATED, ma le build dalla cache e i timestamp riproducibili fanno sì che questa data, da sola, non dimostri che sia stato compilato il codice sorgente più recente.

Quali flag forzano una nuova build

  • docker compose up -d --build esegue prima la build, quindi ricrea ogni container la cui immagine è cambiata. È il flag che serve nella maggior parte dei casi.
  • docker compose build web esegue la build di un servizio senza avviare nulla. Usalo insieme a docker compose up --no-deps -d web per sostituire soltanto quel container e lasciare in esecuzione il resto dello stack.
  • docker compose build --no-cache web ignora i layer memorizzati nella cache ed esegue nuovamente la build del servizio.
  • docker compose build --pull prova a scaricare una versione più recente dell'immagine di base in FROM. In questo modo un tag mobile come node:22 utilizza il contenuto corrente invece della copia scaricata a marzo.
  • docker compose up -d --force-recreate forza la ricreazione del container anche se la configurazione e l'immagine non sono cambiate. Il flag, da solo, non richiede una build, ma up può comunque eseguirla quando manca un'immagine o quando la pull policy lo richiede. Usarlo quando intendevi --build è un errore comune.

Puoi anche definire questo comportamento nel file. Secondo la specifica Compose, pull_policy: build indica che Compose esegue la build dell'immagine e la ricrea se è già presente. Ogni up comporta quindi una build, scelta appropriata su un laptop ma raramente su un server.

services:
  web:
    build: .
    image: registry.example.com/acme/web:dev
    pull_policy: build

È utile conoscere anche un'altra interazione. docker compose pull prova a eseguire il pull delle immagini anche per i servizi che contengono una sezione build. Se il pull non riesce, indica che l'immagine deve essere compilata. Passa --ignore-buildable per ignorare questi servizi senza visualizzare messaggi.

Come la build cache determina i tempi del deploy

Il builder verifica ogni istruzione del Dockerfile per trovare un risultato memorizzato nella cache che possa essere riutilizzato, quando l'istruzione e i relativi input non sono cambiati. Per COPY, gli input includono il contenuto e i metadati dei file, ma escludono le date di modifica. Quando un layer non corrisponde alla cache, tutti i passaggi successivi che dipendono da quel layer vengono ricreati.

Questa regola determina se il deploy richiede secondi o minuti. Ordina il Dockerfile dagli elementi che cambiano raramente a quelli che cambiano a ogni commit.

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

npm ci si trova sopra COPY . ., quindi la modifica di un file sorgente mantiene nella cache il layer di installazione e la build riprende dal passaggio di copia. Se inverti queste due righe, una modifica di un solo carattere reinstalla tutte le dipendenze, perché COPY . . invalida il layer su cui si basa npm ci. La stessa struttura si applica a pip install -r requirements.txt e a go mod download.

--no-cache è lo strumento corretto quando sospetti che un layer obsoleto nasconda la correzione. Non è una buona impostazione predefinita, perché elimina il riutilizzo che l'ordine del Dockerfile è progettato per ottenere.

C'è un elemento che l'image sets e Compose possono sostituire: CMD del Dockerfile definisce ciò che l'immagine esegue per impostazione predefinita, mentre una chiave command: nel servizio lo sostituisce. Come interagiscono command ed entrypoint è importante in questo caso, perché una sostituzione in Compose può far comportare un'immagine appena creata esattamente come quella precedente.

Contesto di build e .dockerignore

context: . rende disponibile la directory del progetto al builder. Senza esclusioni, include .git e qualsiasi directory di dati che si trovi accanto al codice sorgente, anche se BuildKit ignora i file inutilizzati e trasferisce solo le modifiche incrementali. Se una build rimane bloccata sul passaggio relativo al trasferimento del contesto in un progetto che non è cambiato, significa che il contesto è troppo grande.

Un file .dockerignore nella radice del contesto esclude i percorsi dal trasferimento. La sintassi è simile a quella di .gitignore.

.git
node_modules
*.log
data/
.env

I vantaggi sono due. Il trasferimento si riduce e diminuisce il tempo necessario per inviare quei file. Inoltre, COPY . . non può più copiare .env nell'immagine, dove chiunque scarichi l'immagine può leggerlo.

Il caso di build lente che peggiorano nel tempo riguarda un bind mount. Un volume denominato si trova al di fuori della directory del progetto, mentre un bind mount come ./data:/var/lib/postgresql/data si trova all'interno del contesto di build. Di conseguenza, le build diventano più lente ogni settimana man mano che il database cresce. Una riga in .dockerignore risolve il problema. La sezione Bind mount rispetto ai volumi denominati illustra il compromesso più ampio.

Gli argomenti di build comportano una versione più limitata dello stesso rischio. I valori passati tramite args: possono rimanere nella cronologia dell'immagine o nei metadati di provenienza. Usate quindi un numero di versione e mai un token. Gli argomenti proxy predefiniti sono esclusi dalla cache di build e da docker history per impostazione predefinita, a meno che non vengano referenziati esplicitamente nel Dockerfile. La sezione File env e secret in Compose spiega invece dove inserire le credenziali.

Conviene eseguire la build sul VPS oppure altrove e poi effettuare il pull?

Eseguire la build sul server che gestisce il traffico è l'impostazione predefinita perché è il percorso più breve: git pull, quindi docker compose up -d --build. Va bene su un server piccolo da cui nessuno dipende ancora. Diventa una scelta inadeguata per due motivi misurabili e per un terzo che emerge soltanto nelle giornate peggiori.

Memoria. Una build esegue compilatori e bundler insieme all'applicazione in produzione, e questi sono i componenti che consumano più memoria nella maggior parte degli stack. Un bundler JavaScript o una compilazione Rust può esaurire la memoria disponibile su un VPS da 1 GB. In caso di esaurimento della memoria, il kernel seleziona un processo da terminare usando un punteggio di gravità basato sull'uso della memoria, sul contesto dell'allocazione e su oom_score_adj; non termina semplicemente il processo più grande. La build può interrompersi con Killed e codice di uscita 137, oppure può essere terminato il database e il sito può diventare non disponibile durante un deploy. dmesg -T | grep -i oom cerca i messaggi OOM nel log del kernel; per accedervi è necessaria l'autorizzazione alla lettura del log.

Disco. Le build lasciano sul disco i layer delle immagini e la cache di build. docker system df ne mostra l'uso del disco; la garbage collection periodica di BuildKit recupera la cache in base ai criteri configurati. Recupera spazio con docker image prune per le immagini dangling e con docker builder prune per i layer memorizzati nella cache. Un disco pieno blocca operazioni oltre alla build. Anche il database smette di scrivere, e questo guasto costa molto più di un deploy lento.

Riproducibilità. Se non esegui il push o l'export dell'immagine, un'immagine compilata sul server esiste soltanto su quel server. Se l'immagine precedente non è più disponibile, per eseguire il rollback devi effettuare il checkout del commit precedente e compilare di nuovo. Non è garantito che la nuova build produca lo stesso risultato, perché il tag di base è cambiato e anche i mirror dei pacchetti sono cambiati. Eseguire la build altrove e fare il push di un tag trasforma il rollback in una modifica: imposta image: sul tag precedente ed esegui docker compose up -d.

La configurazione più affidabile è semplice. La continuous integration esegue la build e fa il push di registry.example.com/acme/web:<git-sha>, mentre il file Compose sul VPS contiene image: e non contiene affatto la chiave build:. Il deploy richiede quindi due comandi e quasi nessuna memoria.

docker compose pull
docker compose up -d

Esegui docker login registry.example.com sul server per salvare le credenziali necessarie al pull dei tag privati.

Mantieni la sezione della build per lo sviluppo invece di eliminarla, in un file con il nome che preferisci.

# compose.dev.yaml
services:
  web:
    build:
      context: .
    pull_policy: build
docker compose -f compose.yaml -f compose.dev.yaml up -d --build

Assegna a quel file il nome compose.dev.yaml e non compose.override.yaml. Compose carica automaticamente un file di override quando questo è presente. Un file di override copiato per errore sul server inizierebbe quindi di nuovo a eseguire la build senza segnalazioni. Livelli con più file Compose spiega come viene risolta la fusione di ogni chiave.

La trappola dell’architettura quando si esegue la build altrove

Una singola immagine di piattaforma include l’architettura CPU per cui è stata compilata. Se esegui la build di un’immagine ARM su un laptop Apple Silicon, la pubblichi e poi usi quell’immagine su un VPS x86_64, Docker mostra un avviso durante la creazione del container se utilizza un’immagine memorizzata nella cache con architettura incompatibile e senza una piattaforma esplicita. Senza emulazione, il processo termina con exec format error, un errore che sembra indicare un binario danneggiato, ma non lo è. Esegui esplicitamente la build per la piattaforma di destinazione:

docker buildx build --platform linux/amd64 \
  -t registry.example.com/acme/web:1.4.2 --push .

Lo stesso problema si verifica al contrario se il laptop usa x86 e esegui un VPS ARM invece di uno x86. Se lasci che la build venga eseguita dalla CI sull’architettura di destinazione, elimini il problema. Anche un’immagine multipiattaforma risolve il problema: durante il pull, Docker seleziona la variante corrispondente.

Cosa verificare dopo un deploy

  • docker compose images stampa l’immagine e il tag usati da ogni container in esecuzione. Se l’ID dell’immagine è cambiato, hai la prova che la nuova build è attiva.
  • docker compose config stampa il file risultante dopo la sostituzione delle variabili, così puoi leggere il nome finale dell’immagine che Compose userà prima di eseguire qualsiasi operazione.
  • docker compose logs -f web per il primo mezzo minuto dopo la sostituzione. Un container che si avvia e termina ripetutamente viene riavviato solo se la relativa restart policy lo prevede; controlla i log per individuarne la causa.
  • docker image ls mostra una colonna CREATED. Controlla anche l’output della build e l’ID dell’immagine distribuita, perché il solo timestamp di creazione non dimostra che sia stata eseguita una rebuild.

Se stai ancora assemblando il file su cui eseguire questi controlli, le basi di un file Compose su un VPS descrive le chiavi correlate, mentre il riepilogo dei comandi Compose elenca gli altri subcommand.

FAQ

Posso usare build e image nello stesso servizio?

Sì, ed è la configurazione normale per un progetto che compili autonomamente. Quando Compose esegue la build dalla sezione build:, assegna al risultato il tag con il valore di image:; senza un pull_policy esplicito, up prova prima a eseguire il pull. Questo tag è quello che docker compose push invia a un registry e che un'altra macchina scarica. Senza la chiave image:, Compose esegue comunque la build, ma assegna all'immagine un nome basato sul progetto e sul servizio e avvisa che l'attributo mancante impedisce di eseguire il push dell'immagine.

Perché docker compose up non rileva la modifica al mio Dockerfile?

Perché il normale up riutilizza un'immagine esistente, a meno che non si richieda una build o non si configuri una policy che la renda necessaria. Non confronta quell'immagine con il Dockerfile o con i file sorgente per stabilire se sia necessaria una nuova build. Esegui docker compose up -d --build oppure esegui docker compose build web seguito da docker compose up --no-deps -d web per sostituire un singolo servizio. Impostando pull_policy: build sul servizio, ogni up esegue una nuova build, una configurazione adatta a una macchina di sviluppo.

Qual è la differenza tra --build e --force-recreate?

--build esegue nuovamente la build dell'immagine, quindi ricrea i container la cui immagine è cambiata. --force-recreate forza la ricreazione dei container anche se la configurazione e l'immagine non sono cambiate; da solo non richiede una build. Se la modifica riguarda il sorgente o il Dockerfile, --build è il flag da usare. --force-recreate serve a reimpostare il container stesso, ad esempio per cancellare il relativo livello scrivibile mantenendo la stessa immagine.

Devo eseguire la build delle immagini Docker sul VPS o altrove?

Esegui la build altrove ed esegui il pull del tag quando il server gestisce anche traffico di rete. La build compete con l'applicazione per la memoria e, in caso di esaurimento della memoria, il kernel seleziona un processo da terminare usando un punteggio OOM regolabile; il processo selezionato può essere quello della build o del database. Le build lasciano inoltre la cache sul disco, anche se BuildKit la recupera automaticamente in base alle proprie policy di garbage collection. Eseguire la build sul server resta una soluzione adeguata per un progetto piccolo senza utenti; una migrazione successiva richiede poco lavoro se mantieni la sezione build: in un file Compose destinato esclusivamente allo sviluppo.

Come posso impedire che la cache della build Docker riempia il disco?

Esegui docker system df per vedere quanto spazio occupano rispettivamente le immagini e la cache della build. docker builder prune rimuove i livelli memorizzati nella cache e docker image prune rimuove le immagini dangling lasciate dalle build precedenti. L'aggiunta di -a rimuove tutta la cache della build inutilizzata oppure tutte le immagini non referenziate dai container, rispettivamente; non garantisce che la build successiva parta completamente da zero. Non pianificare docker system prune -af --volumes su un server, perché rimuove i container arrestati e i volumi anonimi inutilizzati, mettendo a rischio i dati del database contenuti in un volume anonimo durante la manutenzione.

Questo articolo ti è stato utile?