Deployment

Guida alla configurazione, ottimizzazione e gestione operativa per il deploy di un’applicazione Laravel in produzione

​

Introduzione

Quando esegui il deploy di un’applicazione Laravel in produzione, occorre prepararla per farla girare nel modo più efficiente possibile. Questa guida illustra i punti chiave per un deploy sicuro in produzione.

​

Flusso di deploy

​

Requisiti del server

Il framework Laravel ha i seguenti requisiti di sistema. Sono necessari PHP 8.3 o superiore e le seguenti estensioni PHP.

Estensione	Descrizione
Ctype	Controllo dei tipi di carattere
cURL	Comunicazione HTTP
DOM	Manipolazione DOM di XML/HTML
Fileinfo	Rilevamento del tipo MIME
Filter	Filtraggio dei dati
Hash	Funzioni di hashing
Mbstring	Gestione stringhe multibyte
OpenSSL	Cifratura
PCRE	Espressioni regolari
PDO	Connessione al database
Session	Gestione delle sessioni
Tokenizer	Analisi dei token PHP
XML	Elaborazione XML

​

Configurazione del server

​

Nginx

Se usi Nginx, parti dal seguente file di configurazione come base. È importante inoltrare tutte le richieste a public/index.php. Non spostare index.php nella root del progetto: esporresti file di configurazione riservati all’esterno.

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

​

FrankenPHP

FrankenPHP è un moderno application server PHP scritto in Go. Puoi avviare un’applicazione Laravel con un solo comando.

frankenphp php-server -r public/

Per funzionalità avanzate come HTTP/3, compressione moderna, integrazione con Laravel Octane e binari standalone, consulta la documentazione Laravel di FrankenPHP.

​

Permessi delle directory

Laravel deve scrivere nelle directory bootstrap/cache e storage. Configura i permessi in modo che l’utente proprietario del processo del web server possa scrivere in queste directory.

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

​

Ottimizzazione

Durante il deploy in produzione, effettua la cache di configurazione, eventi, route e viste per migliorare le prestazioni. Con il comando optimize puoi gestire tutta la cache in un’unica esecuzione.

php artisan optimize

Per svuotare le cache usa optimize:clear.

php artisan optimize:clear

​

Singoli comandi di ottimizzazione

optimize esegue in blocco i comandi seguenti. Puoi eseguirli anche singolarmente all’occorrenza.

Comando	Descrizione
php artisan config:cache	Unisce e mette in cache i file di configurazione in un solo file
php artisan event:cache	Mette in cache la mappa evento→listener
php artisan route:cache	Mette in cache le definizioni delle route accelerandone la registrazione
php artisan view:cache	Precompila le viste Blade accelerando le richieste

Dopo aver eseguito config:cache, chiama la funzione env() solo all’interno dei file di configurazione. Dopo la cache il file .env non viene più letto, quindi chiamare env() al di fuori dei file di configurazione restituirà null.

​

Ricaricamento dei servizi

Dopo il deploy di una nuova versione, i servizi di lunga durata come i queue worker, Laravel Reverb e Laravel Octane devono essere riavviati per usare il nuovo codice.

php artisan reload

Questo comando termina i servizi ricaricabili. Configura il process monitor (come Supervisor) in modo che li riavvii automaticamente.

Se usi Laravel Cloud, il ricaricamento graceful di tutti i servizi è gestito automaticamente e il comando reload non è necessario.

​

Modalità debug

L’opzione debug di config/app.php controlla quante informazioni di errore vengono mostrate all’utente. Di default viene usato il valore della variabile d’ambiente APP_DEBUG nel file .env.

In produzione imposta sempre APP_DEBUG a false. Se lasci APP_DEBUG=true in produzione rischi di esporre agli utenti finali informazioni di configurazione sensibili come credenziali del database e chiavi private.

# .env (produzione)
APP_DEBUG=false

​

Route di health check

Laravel include una route di health check integrata per monitorare lo stato dell’applicazione. Puoi integrarla con monitor di uptime, load balancer e sistemi di orchestrazione come Kubernetes.

Di default è disponibile l’endpoint /up che restituisce 200 se l’applicazione è avviata correttamente e 500 se si è verificata un’eccezione all’avvio.

Puoi personalizzare l’URI in bootstrap/app.php.

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // il valore predefinito è /up
)

Alla richiesta di questa route viene emesso l’evento Illuminate\Foundation\Events\DiagnosingHealth, quindi puoi implementare controlli aggiuntivi (database, cache, ecc.) con un listener.

​

Deploy con Laravel Cloud o Forge

​

Laravel Cloud

Se cerchi una piattaforma di deploy completamente gestita e con autoscaling, Laravel Cloud è consigliata. È un PaaS ottimizzato per Laravel che offre compute, database, cache e object storage gestiti.

Viene messa a punto direttamente dal team di sviluppo di Laravel e si integra senza soluzione di continuità con il framework.

​

Laravel Forge

Se vuoi gestire da te i server ma non vuoi perdere tempo a configurare servizi come Nginx e MySQL, Laravel Forge è comodo.

Crea server sui principali cloud provider come DigitalOcean, Linode e AWS e installa e gestisce automaticamente strumenti come Nginx, MySQL, Redis, Memcached e Beanstalk.

​

Prossimi passi

Deployment — Documentazione ufficiale

Puoi consultare i dettagli aggiornati della configurazione di deploy nella documentazione ufficiale.