Hosting e infrastrutture · 17 Novembre 2026

I file YAML di Docker Compose: cosa sono e come funzionano

Un solo file di testo descrive un'intera applicazione: servizi, dati, rete. È il file YAML di Docker Compose. Vediamo come si legge, con un esempio reale.

Di Marco Barbera · 4 min di lettura

Righe di testo stilizzate con rientri diversi che collegano tre blocchi luminosi blu su fondo nero

In breve

Il file YAML di Docker Compose, di norma chiamato compose.yaml o docker-compose.yml, descrive in un unico documento di testo tutti i container di un'applicazione: quali immagini usare, come collegarli, dove salvare i dati e quali porte aprire. Con il comando docker compose up l'intera applicazione si avvia; con docker compose down si ferma. È il modo più semplice per rendere un'installazione ripetibile, documentata e facile da spostare.

Una delle prime cose che chiedo quando prendo in carico un server è: "dov'è il file di configurazione?" Troppo spesso la risposta è che l'applicazione è stata installata a mano, anni fa, da qualcuno che non c'è più.

Con Docker Compose questo problema sparisce. Tutta l'applicazione è descritta in un file di testo, che si legge, si conserva e si ripristina. Se ha letto l'articolo su macchine virtuali e container, questo è il passo successivo.

Cos'è YAML

YAML è un formato di testo pensato per essere letto facilmente sia dalle persone sia dai programmi. Non usa parentesi né tag: la struttura è data dai rientri, cioè dagli spazi all'inizio di ogni riga.

  • chiave: valore assegna un valore.
  • Le righe con più spazi davanti appartengono alla riga sopra.
  • Il trattino - indica un elemento di un elenco.
  • Il simbolo # apre un commento, ignorato dal programma.

Una regola da ricordare: i rientri si fanno con gli spazi, mai con il tabulatore. Un solo spazio fuori posto può cambiare il significato del file.

Cosa descrive il file di Docker Compose

Docker Compose è lo strumento di Docker che gestisce applicazioni fatte di più container. Il file si chiama di norma compose.yaml; il vecchio nome docker-compose.yml è ancora riconosciuto. Le sezioni principali sono tre:

Sezione

Cosa contiene

services

I container dell'applicazione: sito, database, cache

volumes

Gli spazi dove i dati restano salvati anche se il container viene ricreato

networks

Le reti con cui i servizi comunicano tra loro; se non si indicano, Compose ne crea una predefinita

Nei file più vecchi si trova in cima la riga version:. Oggi è superata e si può togliere.

Un esempio reale: WordPress con il suo database

Questo file avvia un sito WordPress con un database MariaDB. Sono circa trenta righe, e descrivono un'installazione completa.

services: db: image: mariadb:11 restart: unless-stopped environment: MARIADB_DATABASE: wordpress MARIADB_USER: wp MARIADB_PASSWORD: ${DB_PASSWORD} MARIADB_RANDOM_ROOT_PASSWORD: "1" volumes: - db_data:/var/lib/mysql wordpress: image: wordpress:latest restart: unless-stopped depends_on: - db ports: - "8080:80" environment: WORDPRESS_DB_HOST: db WORDPRESS_DB_USER: wp WORDPRESS_DB_PASSWORD: ${DB_PASSWORD} WORDPRESS_DB_NAME: wordpress volumes: - wp_data:/var/www/html volumes: db_data: wp_data:

Leggiamolo insieme:

  • image indica quale immagine scaricare: MariaDB versione 11 e WordPress.
  • restart: unless-stopped riavvia il servizio dopo un errore o un riavvio del server.
  • environment passa le impostazioni: nome del database, utente, password.
  • ${DB_PASSWORD} prende la password da un file .env separato, così non resta scritta nel file principale.
  • volumes collega le cartelle dei dati agli spazi persistenti dichiarati in fondo.
  • depends_on avvia il database prima del sito.
  • ports rende il sito raggiungibile sulla porta 8080 del server.

Da notare: WordPress trova il database con il nome db, lo stesso del servizio. Compose crea una rete interna in cui ogni servizio si raggiunge con il proprio nome.

I comandi essenziali

Comando

Cosa fa

docker compose up -d

Scarica le immagini e avvia tutti i servizi in background

docker compose ps

Mostra lo stato dei servizi

docker compose logs -f

Segue i messaggi dei servizi in tempo reale

docker compose pull

Scarica le versioni aggiornate delle immagini

docker compose down

Ferma e rimuove i container; i volumi con i dati restano

Per aggiornare l'applicazione bastano pull e poi di nuovo up -d: Compose ricrea solo i servizi che hanno un'immagine nuova.

Perché conviene anche a chi non scrive codice

Per un'azienda il file Compose ha tre vantaggi concreti.

  1. Documentazione automatica. Il file dice esattamente cosa gira, in quale versione e con quali collegamenti.
  2. Ripristino rapido. Con il file e il backup dei volumi, l'applicazione si ricostruisce su un altro server in pochi minuti.
  3. Indipendenza dal fornitore. Il file si può consegnare a qualsiasi tecnico competente: nessuno resta l'unico a sapere come è stato installato il sistema.

Il consiglio è conservarlo in un sistema di versionamento come Git, con la cronologia delle modifiche. Ogni modifica all'infrastruttura diventa tracciabile, come una modifica a un documento importante. Le password, invece, restano fuori: nel file .env, che non va mai pubblicato.

Domande frequenti

Meglio chiamare il file compose.yaml o docker-compose.yml?

Il nome consigliato oggi è compose.yaml. Il nome docker-compose.yml funziona ancora ed è molto diffuso nei progetti esistenti: non serve rinominarlo.

Le password si possono scrivere nel file YAML?

Tecnicamente sì, ma è sconsigliato. Meglio usare variabili lette da un file .env separato o i secret di Docker, così le credenziali non finiscono nei backup del codice o nei repository.

Cosa succede ai dati se cancello un container?

Se i dati sono in un volume, restano al loro posto e il nuovo container li ritrova. Se non sono in un volume, vengono persi insieme al container.

Docker Compose va bene anche per la produzione?

Sì, per applicazioni che girano su un singolo server è una soluzione diffusa e affidabile. Per più server si usano strumenti di orchestrazione o piattaforme che ne semplificano la gestione.

Se vuole rendere documentate e ripetibili le installazioni della Sua azienda, trova come lavoro nella pagina Hosting e infrastrutture. Per parlarne, mi scriva dalla pagina Contatti.

Scrivimi

Marco Barbera, digital strategist. Si occupa di strategia digitale, web marketing e intelligenza artificiale applicata al business. Chi sono