Docker Compose per lo sviluppo locale: orchestrazione multi-container senza fatica

Ti è mai capitato di aprire quattro terminali per avviare il database, il backend, il frontend e Redis ogni volta che inizi a sviluppare? E di ricordare a memoria comandi lunghi con porte, volumi e reti? Questo è il problema che Docker Compose risolve in un colpo solo.

Noi, di Meteora Web, lo usiamo quotidianamente. Coordinate sviluppo locale per clienti con stack anche complessi (PHP + MySQL + Redis + Node, oppure Laravel + PostgreSQL + Mailpit), e Docker Compose ci permette di riprodurre l'ambiente di produzione su ogni macchina in pochi secondi. Niente più "sulla mia macchina funziona".

Cos’è Docker Compose e perché ti serve

Docker Compose è uno strumento per definire e avviare applicazioni multi-container. Scrivi un file docker-compose.yml in YAML, descrivi servizi, reti e volumi, e con un solo comando tutto parte insieme.

Perché conviene rispetto a lanciare container a mano:

• Riproducibilità: tutto è dichiarato in un file versionabile su Git.
• Condivisione: il team usa lo stesso ambiente, zero differenze.
• Isolamento: ogni progetto con le proprie dipendenze, niente conflitti tra versioni PHP, Python, Node, database.
• Velocità: docker compose up e sei operativo.

Il tuo primo docker-compose.yml

Prendiamo un esempio reale: un’applicazione web in PHP (Laravel) con MySQL e Redis per cache. Ecco il file:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
    depends_on:
      - db
      - redis
    environment:
      DB_HOST: db
      REDIS_HOST: redis

  db:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: myapp
      MYSQL_USER: user
      MYSQL_PASSWORD: userpass
    volumes:
      - dbdata:/var/lib/mysql

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"

volumes:
  dbdata:

Spieghiamo le parti chiave:

Servizi

Ogni container che ti serve è un servizio. app è costruito da un Dockerfile, db e redis usano immagini pubbliche. I nomi dei servizi diventano hostname di rete: il tuo PHP si connette a MySQL usando db come host.

Volumi

dbdata è un volume nominato: i dati del database sopravvivono a stop e riavvii dei container. Il bind mount .:/var/www/html sincronizza il codice sorgente: modifichi un file e il server lo vede subito (senza ricostruire).

Dipendenze

depends_on dice a Docker Compose di avviare prima db e redis. Non garantisce che il database sia pronto ad accettare connessioni (per quello servono health check), ma almeno l’ordine di avvio è corretto.

Comandi essenziali per lavorare

Ecco i comandi che usi ogni giorno:

Comando	Cosa fa
docker compose up -d	Avvia tutti i servizi in background (detached).
docker compose down	Ferma e rimuove container, reti, ma non i volumi.
docker compose build	Ricostruisce le immagini (se hai modificato il Dockerfile).
docker compose logs -f	Segui i log di tutti i servizi in tempo reale.
docker compose exec app php artisan migrate	Esegui un comando dentro il container app (ad esempio una migrazione).

Noi usiamo docker compose up -d ogni mattina e docker compose down alla sera. Semplice, veloce, riproducibile.

Variabili d’ambiente e file .env

Hardcodare password nel docker-compose.yml è da evitare. Usa un file .env nella stessa cartella. Docker Compose lo legge automaticamente se presenti variabili con sintassi ${VAR}.

db:
  image: mysql:8.0
  environment:
    MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS}
    MYSQL_DATABASE: ${DB_NAME}

Nel .env scrivi:

DB_ROOT_PASS=supersecret
DB_NAME=myapp

Attenzione: non committare il file .env su Git (aggiungilo a .gitignore). Il team condivide un .env.example.

Override per sviluppo locale

Spesso in produzione usi un docker-compose.yml pulito, ma in locale vuoi montare il codice sorgente, attivare xdebug, esporre più porte. Docker Compose permette file di override:

• docker-compose.yml — base (condiviso con produzione).
• docker-compose.override.yml — aggiunte locali (non versionato, ma può essere versionato se utile).

Esempio di override per sviluppo:

services:
  app:
    volumes:
      - .:/var/www/html
    environment:
      XDEBUG_MODE: debug
      XDEBUG_CONFIG: client_host=host.docker.internal

Avvi con docker compose up -d e l’override viene applicato automaticamente.

Health check e attesa del database

depends_on non aspetta che il database sia pronto. Per applicazioni che muoiono se il DB non risponde, aggiungi health check:

db:
  image: mysql:8.0
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
    interval: 5s
    timeout: 5s
    retries: 5

app:
  depends_on:
    db:
      condition: service_healthy

Così il container app parte solo dopo che MySQL è pronto. Meno rotture di test.

Errori comuni e come evitarli

Porte in conflitto: se hai un MySQL locale sulla porta 3306, mappa il container su una porta diversa (es. 3307) o ferma il servizio locale. Meglio ancora: usa porte interne e collega i container via rete interna.

Permessi dei volumi: su Linux, i file creati dal container hanno utente root. Per usare il tuo utente locale, imposta l’UID nel Dockerfile o usa il parametro user nel servizio. Noi risolviamo con un utente dedicato nel Dockerfile.

Cache e ricostruzioni: se modifichi il Dockerfile, ricordati di docker compose build prima di up. Usa layer cache in modo efficiente (ordina le istruzioni da meno a più frequenti).

Workflow concreto con Laravel

Vediamo come usiamo Docker Compose in un progetto reale:

1. Cloni il repository.
2. Copi .env.example in .env e inserisci le tue variabili.
3. Esegui docker compose up -d.
4. Entra nel container: docker compose exec app bash.
5. Installa dipendenze: composer install.
6. Genera chiave: php artisan key:generate.
7. Esegui migrazioni: php artisan migrate.
8. Apri http://localhost:8080.

Il tutto in meno di 5 minuti, su qualsiasi macchina con Docker installato.

Cosa fare adesso

Se non hai ancora un docker-compose.yml per il tuo progetto, ecco la checklist:

• Identifica i servizi di cui hai bisogno (web, db, cache, queue, ecc.).
• Per ogni servizio, scegli immagine ufficiale o scrivi un Dockerfile.
• Definisci le porte da esporre (solo quelle necessarie in sviluppo).
• Monta il codice sorgente con un bind mount per hot reload.
• Usa un volume nominato per i dati persistenti (database).
• Aggiungi variabili d’ambiente con file .env.
• Testa con docker compose up -d e verifica la connettività tra servizi.

Noi di Meteora Web abbiamo automatizzato questo setup per ogni nuovo progetto. Se vuoi approfondire, dai un’occhiata alla documentazione ufficiale di Docker Compose. È chiara e ben fatta.

Ricorda: un ambiente di sviluppo riproducibile non è un lusso, è un investimento. Ti toglie la zavorra dei problemi di configurazione e ti fa concentrare su ciò che conta: scrivere buon codice.