Come utilizzare Docker Compose

Docker Compose, ora alla versione V5, è uno degli strumenti più adottati nell’ecosistema della containerizzazione e, ormai, una competenza di base per chiunque gestisca infrastrutture IT moderne. Rilasciato inizialmente come plugin della CLI Docker nel 2021 con l’etichetta V2, è stato rinominato V5 nel 2025 per evitare confusione con le versioni legacy del formato Compose file (2.x e 3.x), ma funzionalmente 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 abbreviando i tempi di intervento sui siti dei clienti. 

In questo aggiornamento 2026 vediamo cos’è Docker Compose, come installare la versione attuale e quali comandi ogni professionista IT dovrebbe tenere nel proprio toolkit quotidiano. 

Cos’è Docker Compose?

Docker Compose è uno strumento ufficiale Docker che consente di definire e avviare applicazioni multi-container basandosi sui container Docker standard a partire da un singolo file di configurazione YAML. In un’architettura a microservizi — dove ogni componente (autenticazione, database, frontend, reverse proxy, coda messaggi, ecc.) viene eseguito nel proprio container – Compose centralizza la definizione di servizi, reti, volumi, secret e config 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 ambienti.
• Velocità di delivery e supporto: avviare, fermare o ricreare un’intera applicazione richiede un singolo comando, il che semplifica deployment, manutenzione e troubleshooting su flotte eterogenee di clienti. 

Installazione di Docker Compose

Docker Compose V1, il binario Python originale invocato come docker-compose (con il trattino), è stato deprecato nel 2022. Il supporto, incluse le patch di sicurezza, è terminato a metà 2023, e il binario standalone è stato definitivamente rimosso da Docker Desktop e dalle immagini dei CI runner (come GitHub Actions) nell’aprile 2025. Se nei tuoi script o pipeline vedi ancora docker-compose con il trattino, sono già non funzionanti o stanno per esserlo. Lo standard attuale è Docker Compose V5 (ancora comunemente indicato come V2 in molti articoli e tutorial), riscritto in Go e distribuito come plugin della CLI Docker, che si invoca come docker compose (senza trattino, con uno spazio). 

Docker Desktop (Windows e macOS)

Su Windows e macOS non è necessaria un’installazione separata: Docker Compose è incluso in Docker Desktop ed è immediatamente disponibile non appena il client è installato. Le istruzioni ufficiali aggiornate sono disponibili nella documentazione Docker.

Linux (Ubuntu, Debian e derivate)

Sui sistemi Linux, l’approccio raccomandato è installare il pacchetto docker-compose-plugin dal repository ufficiale Docker (vedi la lista completa delle distribuzioni supportate), in modo che gli aggiornamenti seguano il normale ciclo di patch del sistema operativo:

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

Sulle distribuzioni basate su RPM (RHEL, CentOS Stream, Fedora, Rocky Linux) il comando equivalente è:

sudo dnf install docker-compose-plugin

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

docker compose version

L’output dovrebbe mostrare una release v5.x (ad esempio, v5.1.4 o successiva). Se vedi una versione v2.x, il pacchetto della tua distribuzione potrebbe essere obsoleto: verifica di star scaricando dal repository ufficiale Docker. 

L’installazione del binario standalone legacy (docker-compose) non è più supportata: il binario V1 è stato rimosso da tutti i canali di distribuzione ufficiali dall’aprile 2025. Dovrebbe essere preso in considerazione solo in scenari eccezionali di retrocompatibilità su sistemi legacy che non possono essere aggiornati, e anche in quel caso non riceverà più alcun aggiornamento o patch di sicurezza. 

Il file compose.yaml

Il file di configurazione è il cuore di Docker Compose: contiene la definizione dichiarativa di tutti i servizi, reti, volumi, secret e config 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, networking, storage e tutto il resto). 

Una nota sulla nomenclatura che spesso genera confusione nei progetti di diversa età: il nome canonico raccomandato dalla Compose Specification è ora 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 frequente fonte di confusione: la chiave top-level version (ad es. version: “3.8”) che compare in molti tutorial più vecchi e nei progetti esistenti è ora obsoleta e ignorata da Compose. I file Compose moderni dovrebbero iniziare direttamente con services (nessuna dichiarazione di versione necessaria). Se la incontri in stack legacy, può essere rimossa in sicurezza; mantenerla attiverà avvisi di deprecazione nelle release attuali di Docker Desktop. 

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 in 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 una serie di funzionalità che vale la pena conoscere fin da subito:

• Profiles: abilitano servizi opzionali (ad es. monitoraggio, debug, job batch) solo in ambienti selezionati, evitando la necessità di mantenere file separati per ogni scenario.
• Override files: oltre a compose.yaml, un secondo file compose.override.yaml viene automaticamente unito, permettendo di tenere separata la configurazione base dagli override locali o di staging.
• Direttiva include: consente di comporre un progetto da più file Compose indipendenti (include: – path: ./monitoring/compose.yaml), facilitando il mantenimento 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 applicative) possono essere dichiarati sotto la chiave top-level configs e montati nei container, mantenendo la configurazione separata dalle immagini e dalle variabili d’ambiente.
• Secrets: i dati sensibili come password e chiavi API vengono montati come file in /run/secrets/<name> all’interno del container, evitandone l’esposizione tramite variabili d’ambiente o l’inclusione nelle immagini.
• Health check con la condizione service_healthy: consentono a un servizio di avviarsi solo dopo che le sue dipendenze sono effettivamente operative, non semplicemente in esecuzione – un dettaglio che fa la differenza in produzione. 

Nota di sicurezza: nel 2025 è stata identificata una vulnerabilità ad alta gravità (CVE-2025-62725, CVSS 8.9) nella gestione degli artefatti OCI remoti da parte di Docker Compose. Il problema riguarda le versioni comprese tra la 2.34.0 e la 2.40.2 (esclusa) e può portare alla sovrascrittura di file arbitrari sul sistema anche eseguendo comandi apparentemente di sola lettura, come docker compose ps o docker compose config. È corretta a partire dalla versione 2.40.2. Se gestisci stack Compose che risolvono file remoti (ad esempio tramite la direttiva include o registri OCI), assicurati di essere su una versione aggiornata di Docker Compose V5 ed evita di risolvere artefatti Compose provenienti da fonti non verificate.

Comandi di Docker Compose

Il riferimento completo dei comandi è disponibile nella documentazione della CLI Docker. Tutti i comandi devono essere eseguiti dalla directory che contiene il file compose.yaml. Quelli elencati di seguito costituiscono il flusso operativo quotidiano per chiunque gestisca infrastruttura containerizzata.

docker compose up Costruisce le immagini (se necessario), crea reti e volumi e avvia i container definiti come servizi. Aggiungendo il flag -d (docker compose up -d) si avvia lo stack in modalità detached, che è 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 gli altri intatti.

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

docker compose stop Arresta in modo graceful i servizi in esecuzione, mantenendo container, reti, volumi e immagini al loro posto. È il comando preferito quando si desidera sospendere temporaneamente uno stack preservandone lo stato. 

docker compose down Arresta i servizi e rimuove i container e le reti creati da Compose. Per impostazione predefinita, i volumi nominati e le immagini vengono lasciati sul sistema: questo evita la perdita accidentale di dati persistenti, una salvaguardia preziosa in ambienti di produzione. 

• docker compose down --volumes rimuove anche i volumi nominati associati allo stack (operazione distruttiva: usala solo quando vuoi effettivamente ripartire da zero). 

• docker compose down --rmi all rimuove tutte le immagini utilizzate dai servizi. 

Alcuni comandi aggiuntivi sono essenziali per le operazioni quotidiane:

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

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

docker compose pull Aggiorna localmente le immagini dichiarate, in preparazione di un successivo up per rilasciare nuove release in produzione in modo controllato.

docker compose config Renderizza 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 all’interno di 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 diagnostica rapida. È solitamente il percorso più veloce per il troubleshooting di un servizio malfunzionante.

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, fornisce 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 un riavvio del processo (ad esempio, dopo l’aggiornamento di un config Nginx montato come volume). 

Dal setup alla produzione

Padroneggiare Docker Compose non richiede una conoscenza approfondita di Docker, ma per sysadmin e MSP è un investimento ad alto rendimento: standardizza i deployment, riduce i tempi di onboarding per nuovi clienti, semplifica la documentazione operativa degli stack e riduce il margine di errore nelle attività ripetitive. Lo stesso compose.yaml può essere utilizzato da runtime alternativi come Podman Compose, offrendo flessibilità nel caso si debba abbandonare Docker Engine. 

Il consiglio pratico è partire da uno scenario reale – ad esempio un’applicazione web con un database e un reverse proxy – scrivere il proprio compose.yaml, fare commit su Git e iterare aggiungendo progressivamente health check, secret e profile. In pochi cicli si arriva a una baseline riutilizzabile da distribuire su tutti i clienti, con un netto guadagno in affidabilità e tempi di risposta.

Se gestisci infrastruttura containerizzata per più clienti, abbinare Docker Compose a una solida strategia di backup e a un workflow affidabile di supporto remoto fa la differenza tra un’operatività fluida e una stressante. Uranium Backup supporta il backup di macchine virtuali, database e dei dati che alimentano le tue applicazioni containerizzate.