Docker con Laravel — Ambiente Sviluppo e Produzione che non Si Rompe tra i Due

Il tuo Laravel gira perfettamente in locale. Lo carichi sul server e scoppia tutto: errori di estensione PHP, permessi sbagliati, versione di MySQL diversa. Il problema non è il codice — è l'ambiente. È la differenza tra sviluppo e produzione. Noi, di Meteora Web, abbiamo visto clienti perdere ore intere su discrepanze di configurazione. Docker risolve esattamente questo: un solo ambiente, identico ovunque. E con Laravel, è persino semplice da impostare.

Perché usare Docker con Laravel per sviluppo e produzione?

Partiamo dal problema concreto: hai il sito su un server con PHP 8.1. In locale usi PHP 8.3. Il codice usa una funzione deprecata in 8.1 e in locale funziona, in produzione crasha. Oppure il database locale è MariaDB, il server è MySQL 5.7, una query NON funziona. Docker elimina tutto questo: l'immagine è la stessa in locale e sul server. Noi lo usiamo per tutti i progetti Laravel che sviluppiamo: la configurazione è parte del codice, non una nota mentale.

I vantaggi che vediamo ogni giorno

• Non più "funziona sulla mia macchina" — l'ambiente è replicabile al 100%.
• Onboarding nuovi sviluppatori in minuti — clonano il repo, lanciano docker compose up -d e sono operativi. Niente installazione di PHP, MySQL, Node.
• Produzione identica a sviluppo — lo stesso docker-compose.yml con piccole varianti di ambiente.
• Risparmio di ore di debug — le differenze di ambiente sono la causa numero 1 di bug in produzione.

Da ex ragionieri e contabili, lo traduciamo così: ogni ora di debug su un problema d'ambiente è un costo che non produce fatturato. Docker elimina questo spreco.

Come impostare il docker-compose.yml per Laravel?

Il file docker-compose.yml è il cuore dell'ambiente. Definisce i servizi: app (PHP-FPM), web (Nginx), database (MySQL/Postgres), eventuali altri servizi (Redis, Mailpit). Ecco un esempio funzionante e collaudato che usiamo noi per i progetti Laravel:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: laravel_app
    restart: unless-stopped
    working_dir: /var/www
    volumes:
      - .:/var/www
      - ./storage:/var/www/storage
    networks:
      - laravel

  web:
    image: nginx:alpine
    container_name: laravel_web
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - .:/var/www
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    networks:
      - laravel
    depends_on:
      - app

  db:
    image: mysql:8.0
    container_name: laravel_db
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3307:3306"
    volumes:
      - dbdata:/var/lib/mysql
    networks:
      - laravel

volumes:
  dbdata:

networks:
  laravel:

passaggi pratici per farlo funzionare

1. Crea il Dockerfile per l'immagine PHP. Questo file dice a Docker come costruire l'immagine del servizio app. Ecco un esempio per Laravel:

FROM php:8.3-fpm-alpine

# Installa estensioni necessarie
RUN docker-php-ext-install pdo_mysql bcmath

# Installa Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Imposta directory di lavoro
WORKDIR /var/www

# Copia i file del progetto
COPY . .

# Installa dipendenze
RUN composer install --no-interaction --prefer-dist --optimize-autoloader

2. Configura Nginx. Crea un file nginx.conf nella root del progetto:

server {
    listen 80;
    index index.php;
    server_name localhost;
    root /var/www/public;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

3. Avvia l'ambiente. Nella root del progetto Laravel, esegui:

docker compose up -d

Il sito sarà accessibile su http://localhost:8080.

Come ottimizzare l’immagine Docker per la produzione?

Per la produzione l'immagine deve essere piccola, sicura e pronta per l'esecuzione. Le regole base: non includere Composer, npm, strumenti di sviluppo. Usa un multi-stage build per separare la fase di build da quella di runtime.

Esempio di multi-stage Dockerfile

# Stage 1: Build
FROM php:8.3-cli-alpine AS build

WORKDIR /app
COPY . .

RUN docker-php-ext-install pdo_mysql bcmath
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
RUN composer install --no-dev --optimize-autoloader

# Stage 2: Runtime
FROM php:8.3-fpm-alpine

COPY --from=build /app /var/www

RUN docker-php-ext-install pdo_mysql bcmath opcache

# Configura PHP per produzione
COPY php.ini-production /usr/local/etc/php/php.ini

WORKDIR /var/www

Con multi-stage l'immagine finale pesa molto meno (solo i file necessari, niente codice di build). Noi lo usiamo per tutti i deploy: l'immagine parte da ~200 MB contro oltre 1 GB senza ottimizzazione.

Come gestire le variabili d'ambiente in sviluppo e produzione?

Laravel usa il file .env. Docker lo monta come volume in sviluppo, ma in produzione deve essere nell'immagine o iniettato via variabili d'ambiente del container. Il metodo più pulito: usa un file .env.production separato e, nella pipeline CI/CD, lo copia come .env prima del build.

Schema pratico

• Sviluppo: .env locale montato nel volume. Le credenziali del database puntano a db:3306.
• Produzione: .env generato dalla pipeline CI/CD con variabili reali (es. database remoto, API key). Mai nel repository.
• Differenze chiave: APP_ENV=production, APP_DEBUG=false, DB_HOST diverso.

# Su server di produzione, lancia con:
docker run -d --env-file .env.production my-laravel-app:latest

Come usare Laravel Sail per semplificare lo sviluppo?

Laravel Sail è un wrapper di Docker ufficiale di Laravel. Noi lo consigliamo ai clienti che non vogliono scrivere i file Docker a mano. Sail gestisce automaticamente servizi come MySQL, Redis, Mailhog con un comando semplice: sail up -d. È perfetto per sviluppo, ma per produzione preferiamo il nostro setup custom con multi-stage e ottimizzazioni specifiche per il server.

Perché a volte preferiamo il Dockerfile custom

Con Sail hai meno controllo sull'immagine di produzione. Noi abbiamo costruito una piattaforma proprietaria per la gestione di più siti: per ottimizzare i costi di hosting e le performance, usiamo immagini multi-stage con Nginx incluso. Sail non supporta nativamente multi-stage e richiede Nginx separato. Se il progetto è piccolo, Sail va benissimo. Se prevedi scalabilità, meglio il custom.

Cosa fare adesso

1. Scarica il repository Laravel di prova — se non hai un progetto, creane uno con composer create-project laravel/laravel test-docker.
2. Copia i file docker-compose.yml, Dockerfile e nginx.conf sopra — adattali al tuo progetto.
3. Avvia l'ambiente con docker compose up -d e verifica su localhost:8080.
4. Testa le differenze — cambia una variabile d'ambiente in produzione (es. APP_DEBUG=false) e verifica che la differenza si comporti come previsto.
5. Documenta la configurazione — se lavori in team, aggiungi un README.md con i comandi base. Ridurrai il tempo di onboarding a pochi minuti.

Se vuoi approfondire, leggi la nostra guida madre su Docker e Containerizzazione per PMI italiane. Per la parte di Laravel Laravel, il riferimento ufficiale è la documentazione di Sail.