Come utilizzare Docker Compose

Docker Compose, oggi alla versione V5, è uno degli strumenti più diffusi nell’ecosistema della containerizzazione e ormai una competenza di base per chiunque gestisca un’infrastruttura IT moderna. Annunciato come Compose V2 nel 2020 e disponibile in versione stabile (GA) da aprile 2022 come plugin della CLI di Docker, nel 2025 è stato rinominato V5 per evitare confusione con le versioni legacy del formato dei file Compose (2.x e 3.x), ma dal punto di vista funzionale non è cambiato nulla.

Per sysadmin e Managed Service Provider (MSP), padroneggiarlo significa orchestrare ambienti multi-container in modo dichiarativo, riproducibile e versionabile, riducendo gli errori manuali e accorciando i tempi di intervento presso i siti dei clienti.

In questo aggiornamento 2026 vediamo cos’è Docker Compose, come installare la versione corrente e quali comandi ogni professionista IT dovrebbe avere nella cassetta degli attrezzi di tutti i giorni.

Cos’è Docker Compose?

Docker Compose è uno strumento ufficiale di Docker che ti permette di definire ed eseguire applicazioni multi-container basate su container Docker standard a partire da un unico file di configurazione YAML. In un’architettura a microservizi – dove ogni componente (autenticazione, database, frontend, reverse proxy, message queue, ecc.) gira nel proprio container – Compose centralizza la definizione di servizi, reti, volumi, secrets e configs in un unico file dichiarativo, eliminando la necessità di gestire decine di singoli comandi docker run.

Per un sysadmin o un MSP questo si traduce in tre vantaggi operativi concreti:

• Riproducibilità: lo stesso file compose.yaml produce ambienti identici su laptop degli sviluppatori, server di staging e siti di produzione dei clienti.
• Versionabilità: la configurazione dell’intero stack vive in Git insieme al codice o alla documentazione operativa, eliminando il drift tra gli ambienti.
• Velocità di rilascio e di supporto: avviare, fermare o ricreare un’intera applicazione richiede un solo comando, e questo semplifica deployment, manutenzione e troubleshooting su parchi clienti eterogenei.

Installare Docker Compose

Docker Compose V1, il binario Python originale invocato come docker-compose (con il trattino), ha raggiunto la fine del supporto (end of life) a giugno 2023. È stato rimosso da Docker Desktop a partire dalla versione 4.23.0 e dalle runner image di GitHub Actions a luglio 2024. Se trovi ancora docker-compose con il trattino in script o pipeline, verifica a cosa corrisponde: su Docker Desktop ora punta al binario di Compose V2, ma sulle runner ospitate da GitHub il vecchio comando V1 non funziona più, e qualsiasi installazione V1 rimasta non è supportata e non riceve patch. Lo standard attuale è Docker Compose V5 (in molti articoli e tutorial ancora chiamato V2), riscritto in Go e distribuito come plugin della CLI di Docker, che si invoca come docker compose (senza trattino, con uno spazio).

Docker Desktop (Windows e macOS)

Su Windows e macOS non serve alcuna installazione separata: Docker Compose è incluso in Docker Desktop ed è disponibile subito dopo aver installato il client. Le istruzioni ufficiali aggiornate sono nella documentazione di Docker.

Linux (Ubuntu, Debian e derivate)

Sui sistemi Linux l’approccio consigliato è installare il pacchetto docker-compose-plugin dal repository ufficiale di Docker (consulta l’elenco completo delle distribuzioni supportate), in modo che gli aggiornamenti seguano il normale ciclo di patch del sistema operativo. Per prima cosa va configurato il repository: segui le istruzioni per configurare il repository della tua distribuzione, poi esegui:

sudo apt-get update
sudo apt-get install docker-compose-plugin

Sulle distribuzioni basate su RPM (RHEL e derivate compatibili, CentOS Stream, Fedora) il comando equivalente è:

sudo dnf install docker-compose-plugin

Una volta installato, è buona prassi verificare subito versione e disponibilità:

docker compose version

L’output dovrebbe mostrare una release v5.x (ad esempio v5.6.0). Docker supporta ancora anche la linea v2.x, ma se vedi una release più vecchia verifica di scaricare i pacchetti dal repository ufficiale di Docker, così ricevi gli ultimi aggiornamenti.

L’installazione di Compose V1 (il docker-compose in Python) non è supportata: ha raggiunto la fine del supporto a giugno 2023 e non riceve patch di sicurezza. Docker documenta ancora un’installazione standalone del binario V2, ma è etichettata come legacy e il plugin resta il metodo consigliato.

Il file compose.yaml

Il file di configurazione è il cuore di Docker Compose: contiene la definizione dichiarativa di tutti i servizi, le reti, i volumi, i secrets e le configs che compongono l’applicazione. In altre parole, un Dockerfile descrive come costruire una singola immagine container, mentre il file Compose descrive come eseguire un’intera applicazione multi-container (servizi, rete, storage e tutto il resto).

Una nota sui nomi che spesso crea confusione nei progetti di epoche diverse: il nome canonico raccomandato dalla Compose Specification è ormai compose.yaml, ma Compose riconosce ancora automaticamente docker-compose.yml, docker-compose.yaml e compose.yml per garantire la compatibilità con i file esistenti. Per i nuovi progetti ha senso adottare il nome canonico.

Un’altra fonte frequente di confusione: la chiave di primo livello version (ad esempio version: “3.8”), presente in molti tutorial datati e progetti esistenti, è ormai obsoleta e ignorata da Compose. I file Compose moderni dovrebbero iniziare direttamente con services (nessuna dichiarazione di versione necessaria). Se la trovi in stack legacy, puoi rimuoverla senza problemi: Compose la ignora e mostra un avviso che segnala che l’attributo è obsoleto.

Di seguito un esempio minimale che mostra il layout tipico di uno stack web a tre livelli (reverse proxy, applicazione, database) con health check e dipendenze condizionali – un pattern molto comune nei contesti MSP:

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - db_data:/var/lib/postgresql/data
    secrets:
      - db_password
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

  app:
    image: registry.example.com/myapp:1.4.0
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend

  proxy:
    image: nginx:1.30-alpine
    restart: unless-stopped
    ports:
      - "443:443"
    depends_on:
      - app
    networks:
      - backend

volumes:
  db_data:

networks:
  backend:

secrets:
  db_password:
    file: ./secrets/db_password.txt

Per gli scenari più complessi, tipici degli ambienti enterprise e MSP, la specifica Compose include diverse funzionalità che vale la pena conoscere fin dall’inizio:

• Profiles: abilitano servizi opzionali (ad esempio monitoring, debug, batch job) solo in determinati ambienti, evitando di mantenere file separati per ogni scenario.
• Override files: oltre a compose.yaml, un secondo file compose.override.yaml viene unito automaticamente, così puoi tenere separata la configurazione di base dagli override locali o di staging.
• Direttiva include: permette di comporre un progetto a partire da più file Compose indipendenti (include: – path: ./monitoring/compose.yaml), facilitando la manutenzione di blocchi riutilizzabili tra gli stack dei clienti.
• Configs: i dati di configurazione non sensibili (ad esempio un file di virtual host Nginx o un file di impostazioni dell’applicazione) possono essere dichiarati sotto la chiave di primo livello configs e montati nei container, mantenendo la configurazione separata da immagini e variabili d’ambiente.
• Secrets: i dati sensibili come password e chiavi API vengono montati come file in /run/secrets/<name> all’interno del container, evitando di esporli tramite variabili d’ambiente o di includerli nelle immagini.
• Health check con la condizione service_healthy: fanno partire un servizio solo quando le sue dipendenze sono realmente operative, non semplicemente in esecuzione – un dettaglio che in produzione fa la differenza.

Nota di sicurezza: nel 2025 è stata individuata una vulnerabilità ad alta gravità (CVE-2025-62725, punteggio CVSS v4 8.9) nel modo in cui Docker Compose gestisce gli artefatti OCI remoti. Il problema riguarda le versioni dalla 2.34.0 fino alla 2.40.2 esclusa e può portare alla sovrascrittura di file arbitrari sull’host, anche eseguendo comandi apparentemente di sola lettura come docker compose ps o docker compose config. È stato corretto a partire dalla versione 2.40.2, quindi tutte le release di Compose V5 non sono interessate. Se gestisci stack Compose che risolvono file remoti (ad esempio tramite la direttiva include o registry OCI) su host che usano ancora una release 2.x, aggiorna all’ultima versione ed evita di risolvere artefatti Compose da fonti non verificate.

Comandi di Docker Compose

Il riferimento completo dei comandi è disponibile nella documentazione della CLI di Docker. Tutti i comandi vanno eseguiti dalla directory che contiene il file compose.yaml. Quelli qui sotto compongono il flusso operativo quotidiano di chiunque gestisca infrastrutture containerizzate.

docker compose up Esegue la build delle immagini (se necessario), crea reti e volumi e avvia i container definiti come servizi. Aggiungendo il flag -d (docker compose up -d) lo stack parte in modalità detached, l’approccio standard sui server di produzione. Se i container sono già in esecuzione e la configurazione è cambiata, Compose ricrea automaticamente solo quelli interessati dalle modifiche, lasciando intatti gli altri.

docker compose start Avvia i container che esistono già, senza ricostruire le immagini né ricreare le risorse. Utile dopo uno stop pianificato o il riavvio di un nodo.

docker compose stop Ferma in modo ordinato i servizi in esecuzione mantenendo al loro posto container, reti, volumi e immagini. È il comando da preferire quando vuoi sospendere temporaneamente uno stack preservandone lo stato.

docker compose down Ferma i servizi e rimuove i container e le reti creati da Compose. Per impostazione predefinita i volumi con nome e le immagini restano sul sistema: in questo modo eviti la perdita accidentale di dati persistenti, una tutela preziosa negli ambienti di produzione.

• docker compose down --volumes rimuove anche i volumi con nome associati allo stack (operazione distruttiva: usalo solo quando vuoi davvero ripartire da zero).
• docker compose down --rmi all rimuove tutte le immagini usate dai servizi.

Alcuni comandi aggiuntivi sono essenziali per le operazioni di tutti i giorni:

docker compose ps Elenca lo stato dei container dello stack corrente, inclusi i risultati degli health check. È il primo comando da lanciare per un controllo rapido dello stato.

docker compose logs -f Mostra in tempo reale i log aggregati di tutti i servizi (o di un singolo servizio, indicandone il nome). È il punto di partenza per qualsiasi attività di troubleshooting.

docker compose pull Scarica in locale le immagini dichiarate, in preparazione di un successivo up per distribuire in produzione le nuove release in modo controllato.

docker compose config Mostra la configurazione completamente risolta, utile per validare la sintassi e verificare l’unione di eventuali file di override prima di applicarli.

docker compose exec Apre una sessione interattiva o esegue un comando una tantum dentro un container in esecuzione, senza avviarne uno nuovo. Ad esempio, docker compose exec db psql -U postgres ti porta direttamente in una shell PostgreSQL per una diagnosi rapida. Di solito è la via più veloce per fare troubleshooting di un servizio che non si comporta come dovrebbe.

docker compose ls Elenca tutti i progetti Compose attivi sull’host, indipendentemente dalla directory in cui ti trovi. Per gli MSP che gestiscono più stack su un singolo server, offre una panoramica immediata di cosa è in esecuzione e dove.

docker compose restart Riavvia uno o più servizi senza distruggere e ricreare i container. Utile per applicare modifiche di configurazione che richiedono solo il riavvio del processo (ad esempio dopo aver aggiornato una configurazione Nginx montata come volume).

Dal setup alla produzione

Padroneggiare Docker Compose non richiede una conoscenza profonda di Docker, ma per sysadmin e MSP è un investimento ad alto ritorno: standardizza i deployment, riduce i tempi di onboarding dei nuovi clienti, semplifica la documentazione operativa degli stack e restringe il margine di errore nelle attività ripetitive. Poiché Compose è una specifica aperta, lo stesso compose.yaml può essere utilizzato anche da runtime alternativi come Podman Compose, e questo ti dà flessibilità se un giorno dovessi abbandonare Docker Engine.

Il consiglio pratico è partire da uno scenario reale – per esempio un’applicazione web con un database e un reverse proxy – scrivere il tuo compose.yaml, fare il commit su Git e iterare aggiungendo progressivamente health check, secrets e profiles. In pochi cicli ottieni una baseline riutilizzabile da distribuire su tutti i tuoi clienti, con un netto guadagno in affidabilità e tempi di risposta. Quando un singolo host non basta più e ti servono scalabilità o alta disponibilità su più nodi, è il momento di guardare agli orchestratori: leggi Docker vs Kubernetes per capire come differiscono i due livelli.

Se gestisci infrastrutture containerizzate per più clienti, abbinare Docker Compose a una solida strategia di backup e a un affidabile flusso di assistenza remota fa la differenza tra un’operatività fluida e una stressante. Uranium Backup protegge file e cartelle, database (SQL Server, MySQL, MariaDB) e macchine virtuali (VMware, Hyper-V), compresi i dati degli host su cui girano le tue applicazioni containerizzate.