Torniamo con la rubrica dedicata a Mage-OS, con un nuovo articolo di Samuele Martini e Davide Lunardon, Webito.
Oggi si parla di Webloyer: Deploy zero downtime per Magento.
Ma lasciamo la parola a Samuele e Davide per approfondire questo argomento.
Nel mondo dello sviluppo moderno, la gestione dei deploy è un tema centrale e spesso critico, soprattutto quando si parla di applicazioni PHP complesse e team distribuiti. Webloyer nasce proprio per risolvere molte delle complessità e delle inefficienze tipiche di questi scenari. Si tratta di uno strumento open source che permette di coordinare e automatizzare tutti i processi di deployment in modo centralizzato, tramite una dashboard web intuitiva. Grazie a Webloyer, i team possono integrare le funzionalità avanzate di Deployer, ma con un controllo e una tracciabilità superiori. Il progetto, ideato da Yuta Nagamiya (ngmy), è stato poi portato avanti anche da Davide Lunardon, che nel 2022 lo ha aggiornato alle versioni dell’epoca di Laravel e Deployer, coprendo alcune falle di sicurezza.
Un passo indietro: cos’è Deployer
Per capire il valore aggiunto di Webloyer, è fondamentale prima comprendere cos’è e come funziona Deployer. Si tratta di uno dei tool più diffusi e maturi per l’automazione dei processi di deploy delle applicazioni PHP.
Nato nel 2013 e sviluppato da Anton Medvedev (sito ufficiale – repo GitHub), Deployer si è affermato come punto di riferimento per chi vuole gestire release, rollback e task complessi senza rischiare errori manuali e downtime.
Il funzionamento di Deployer ruota attorno a un file chiamato recipe (deploy.php). Questo file non è altro che uno script PHP in cui vengono descritte, in modo ordinato, tutte le operazioni che compongono il deploy: clonazione della repository, installazione delle dipendenze con Composer, eventuali migrazioni di database, pulizia e refresh delle cache, gestione dei permessi, aggiornamento dei symlink e così via. La recipe può essere costruita su misura per le proprie esigenze o si può partire dalle ricette ufficiali già disponibili per framework e piattaforme note come Laravel, Symfony o Magento.
L’esecuzione del deploy avviene tramite il comando CLI dep deploy, che si collega via SSH al server di destinazione e svolge tutte le operazioni previste nella recipe, passo dopo passo. Un aspetto fondamentale di Deployer è la gestione delle release: il webserver deve essere configurato per puntare al path current che in realtà è un symlink, ogni deploy crea una nuova cartella (es. releases/20250718_142000) in cui vengono riversati tutti i file della release. Solo al termine di tutte le operazioni il symlink current viene aggiornato per puntare alla nuova cartella di release. Questo meccanismo garantisce il cosiddetto zero downtime: l’applicazione resta sempre online e il passaggio alla nuova versione avviene istantaneamente, senza mai lasciare l’utente davanti a errori o schermate di manutenzione.
Se qualcosa dovesse andare storto, Deployer consente di tornare rapidamente alla versione precedente tramite rollback, semplicemente ripuntando il symlink alla release desiderata. Il sistema è molto flessibile: è possibile personalizzare task, eseguire deploy su più server contemporaneamente o distinguere tra ambienti diversi (dev, staging, produzione) tramite apposite configurazioni.
Inoltre, tutta la logica di deploy viene salvata e versionata insieme al codice sorgente, permettendo la massima tracciabilità e ripetibilità del processo. Non servono tool esterni: basta PHP e accesso SSH. Gli sviluppatori lavorano in locale, lanciando i comandi dal proprio PC e usando la propria chiave SSH per accedere ai server.
Vantaggi di Deployer
L’utilizzo di Deployer porta numerosi benefici pratici:
- Automazione totale delle operazioni di deploy
- Zero downtime reale grazie al sistema delle release e dei symlink
- Rollback istantaneo in caso di problemi
- Storico dettagliato delle release e dei log
- Personalizzazione spinta tramite ricette e task custom
- Standardizzazione del processo di deploy all’interno del team
- Nessuna dipendenza da software esterni, solo PHP e SSH
Limite principale: non esiste una regia centralizzata. Ogni sviluppatore deve lanciare il deploy dal proprio PC locale, usando la propria chiave SSH. Se il team è numeroso, questo può generare confusione, sovrapposizioni o deploy non tracciati. Manca una visione unica e condivisa dello stato delle release.
Perché Webloyer al posto di Deployer
Webloyer nasce per portare tutti i vantaggi e la potenza di Deployer ad un livello di astrazione più elevato, introducendo una gestione centralizzata e una UI web accessibile da tutto il team. L’idea originale, sviluppata da Yuta Nagamiya (repo originale), era quella di creare una sorta di “Jenkins semplificato” ma focalizzato esclusivamente sul deployment delle applicazioni PHP tramite Deployer. La svolta arriva nel 2022, quando Davide Lunardon (GitHub) realizza un fork profondamente aggiornato: qui Laravel viene portato alla versione 8 e Deployer alla 7, risolvendo numerosi limiti e problemi di sicurezza dell’implementazione originaria.
Webloyer si presenta come una dashboard centralizzata, tramite cui puoi configurare progetti, ambienti, server, ricette, utenti e permessi, tutto dallo stesso punto. Le recipe di Deployer possono essere caricate, modificate e gestite dal browser, e sono sempre disponibili per ogni membro del team senza doversi preoccupare di sincronizzazioni locali.
Uno dei punti di forza di Webloyer è la possibilità di integrare il deploy con i sistemi di version control più usati: tramite webhook su GitHub, GitLab o Bitbucket, il sistema può avviare in automatico la pipeline di deploy al push su un determinato branch. Così il deploy non dipende più dall’azione manuale di un singolo sviluppatore ma diventa parte integrante e trasparente del flusso di sviluppo.
Tutte le operazioni di deploy e rollback si possono eseguire con un semplice click, direttamente dal pannello web, e vengono registrate con log dettagliati, notifiche email e tracciamento completo di chi ha fatto cosa, quando e su quale ambiente. Il sistema di gestione utenti e permessi permette di definire ruoli granulari e proteggere sia le azioni più critiche che le informazioni riservate.
Webloyer supporta inoltre la gestione di più progetti e di più server per ciascun progetto: questo lo rende ideale per agenzie e realtà che gestiscono decine di applicativi diversi.
Dal punto di vista della sicurezza, è importante sottolineare che i deploy vengono eseguiti sempre dal server centrale dove è installato Webloyer: le chiavi SSH restano lì, non circolano mai sulle macchine degli sviluppatori, riducendo la superficie d’attacco e aumentando il controllo.
Vantaggi di Webloyer rispetto alla CLI di Deployer
Webloyer introduce una serie di vantaggi fondamentali rispetto all’uso diretto di Deployer in modalità CLI:
- Tutto il processo di deploy viene centralizzato in un unico punto di accesso, garantendo maggiore sicurezza, ordine e controllo.
- Grazie ai webhook, i deploy possono essere automatizzati e agganciati direttamente alla pipeline di sviluppo: ad esempio, è possibile eseguire un deploy automatico al push sul branch master, eliminando completamente l’intervento manuale.
- Il rischio di errori e sovrapposizioni viene drasticamente ridotto: non esistono più “deploy contemporanei” o versioni saltate per sbaglio.
- Ogni azione viene tracciata e registrata in uno storico consultabile, utilissimo per audit, troubleshooting o semplice accountability.
- La gestione utenti permette di differenziare ruoli e privilegi, facilitando la collaborazione anche in team numerosi o eterogenei.
- L’esperienza utente è notevolmente migliorata: anche chi non ha familiarità con la CLI o con gli strumenti da terminale può eseguire deploy, rollback o consultare i log tramite una semplice interfaccia web.
Link utili:
Differenza chiave tra Deployer e Webloyer
Il vero salto di qualità tra i due strumenti sta nella gestione del workflow di team. Usando Deployer in modalità CLI, ogni sviluppatore è responsabile dei propri deploy: ognuno lancia i comandi dal proprio PC, con la propria configurazione e la propria chiave SSH. In ambienti piccoli questo può andare bene, ma appena i progetti o il numero di sviluppatori aumentano, il rischio di errori, deploy sovrapposti o mancata tracciabilità cresce in modo esponenziale.
Webloyer risolve questo problema centralizzando tutto: la recipe viene caricata una sola volta nel tool, i deploy partono sempre dallo stesso server e tutti gli sviluppatori utilizzano la stessa interfaccia. Ancora meglio, grazie ai webhook, è possibile eliminare il passaggio manuale e avviare il deploy automaticamente al push sul repository, evitando completamente il rischio di sovrapposizioni o errori umani.
Questa differenza, spesso sottovalutata, è cruciale nei team strutturati e nelle agenzie che gestiscono più progetti contemporaneamente. Si passa dal rischio di caos e confusione a un sistema ordinato, sicuro e facilmente monitorabile.
Perché Webloyer è utile con Magento
Chiunque abbia esperienza con Magento sa quanto possa essere delicato il momento del deploy. Magento, infatti, impone la messa in modalità manutenzione per poter aggiornare i contenuti statici o rigenerare la dependency injection. Queste operazioni, se fatte manualmente, causano inevitabilmente downtime per l’utente finale, con possibili perdite di conversioni o malumori tra i clienti e rendendo del tutto inapplicabili metodologie di lavoro basate su Continuous Deployment / Continuous Delivery
Integrando Webloyer nel workflow di deploy di Magento, è possibile implementare un processo realmente zero downtime. La logica è semplice: tutte le operazioni “pericolose” o lente (composer install, generazione degli static content, compilazione DI, cache) vengono fatte in una directory separata rispetto a quella online. Solo alla fine di tutto, tramite il cambio del symlink current, la nuova versione viene pubblicata istantaneamente. Il downtime reale si riduce così a pochi millisecondi o addirittura a zero, con evidenti benefici per utenti, team e business. Inoltre è possibile pubblicare le modifiche direttamente sull’applicativo, senza dover concordare un momento per la release con il cliente e senza dover interrompere le operazione di store management.
Attenzione: il problema del symlink e PHP-FPM (realpath cache e opcache)
Non è tutto oro quel che luccica e la gestione dei progetti con Webloyer o Deployer non è esente da problemi: una delle insidie più frequenti nel deploy zero downtime con symlink riguarda la cache di risoluzione dei percorsi dei symlink gestita da PHP-FPM, in particolare con opcache. Dopo il cambio di symlink, può succedere che PHP-FPM continui a puntare ai vecchi file, mostrando comportamenti inattesi o ignorando completamente la nuova release. Questo perché PHP memorizza il percorso risolto dei symlink e non si accorge del cambio.
Per risolvere, spesso si ricorre al riavvio di PHP-FPM, che svuota la cache e forza la rilettura dei percorsi. Tuttavia, in ambienti condivisi (ad esempio hosting agency con molti progetti sullo stesso pool FPM), il riavvio può causare downtime per tutti i siti collegati, anche se il deploy riguarda solo uno di essi. Se i progetti sono molti e i deploy frequenti, si rischia di moltiplicare inutilmente i downtime.
Soluzione con Nginx e realpath
Una soluzione più elegante e robusta consiste nel configurare Nginx come webserver al posto di Apache, il quale ha la possibilità di risolvere i symlink lato webserver, sfruttando la direttiva realpath_root (e in alcuni casi anche disable_symlinks). In questo modo, il webserver risolve il percorso reale dei symlink prima di passarli a PHP: il risultato è che PHP vede sempre e solo il path già risolto, senza doverlo memorizzare in cache. Questo elimina la necessità di riavviare FPM ad ogni deploy, garantendo zero downtime reale anche in ambienti multi-progetto e multi-deploy.
Per approfondimenti su come funziona questa soluzione:
Questa configurazione è caldamente consigliata in ambienti agency, hosting multi-client o ovunque si voglia evitare micro-downtime continui e garantire un’esperienza utente perfetta.