Spostare uno stack Docker Compose su un nuovo server

Trasferire un'applicazione distribuita su un nuovo server può generare apprensione: l'obiettivo fondamentale è evitare che la migrazione comporti la perdita di dati, la compromissione delle sessioni di autenticazione o l'inaccessibilità prolungata del servizio.

Versione breve: per migrare uno stack Docker Compose su un nuovo server è necessario trasferire il file di configurazione Compose, le variabili d'ambiente, i dati persistenti e la configurazione del dominio o del reverse proxy che instrada il traffico verso i container corretti. I rischi principali non risiedono nell'infrastruttura Docker Compose in sé, ma nella gestione di volumi trascurati, segreti d'ambiente, porte di rete, certificati HTTPS e stato del database.

Cosa devi davvero spostare?

Un'architettura gestita con Docker Compose può essere paragonata all'organizzazione di una struttura aziendale complessa.

Il file compose.yaml rappresenta il progetto strutturale: definisce i singoli servizi componenti, quali l'applicazione web, la base dati, i sistemi di caching, i worker di background e l'eventuale reverse proxy.

Il file d'ambiente corrisponde alle specifiche operative: contiene variabili critiche come credenziali del database, chiavi di cifratura dell'applicazione, configurazioni per l'invio delle email e token per le API. L'omissione di questi dati consente ai container di avviarsi, ma impedisce al sistema di funzionare correttamente.

I volumi costituiscono l'archivio dei dati persistenti. Un volume Docker è uno storage indipendente dal ciclo di vita del container, garantendo la conservazione dei dati ai riavvii dell'applicazione. È in questa posizione che risiedono i database, i file caricati dagli utenti e lo stato dell'applicazione. Trasferire il solo file Compose senza i volumi equivale a spostare l'infrastruttura privandola dei relativi contenuti.

È infine necessario configurare le componenti di contorno dello stack: record DNS, regole del firewall, certificati HTTPS, task schedulati (cron job), procedure di backup e qualsiasi file del server montato all'interno dei container.

Per approfondire i concetti fondamentali relativi a container e volumi, consulta la nostra guida per principianti: /blog/docker-su-vps-per-principianti-cos-e-quando-ti-serve-e-quando-no.

Cosa si rompe più spesso quando sposti Docker Compose?

L'anomalia più frequente è rappresentata dalla mancata migrazione dei dati persistenti. Sebbene un container destinato al database possa essere ricreato rapidamente, i file effettivi della base dati devono essere trasferiti integralmente. Lo stesso principio si applica ad asset multimediali, caricamenti degli utenti, indici di ricerca e file generati dal sistema.

Una seconda criticità riguarda il disallineamento dei percorsi (path). Se il vecchio server utilizzava la cartella /srv/app/uploads e il nuovo ambiente utilizza un percorso differente, Docker Compose non riconoscerà automaticamente la variazione. Qualora un bind mount punti a una directory inesistente, il container potrebbe essere avviato associando una cartella vuota, rendendo il problema non immediatamente visibile.

Un terzo fattore di rischio è la mancata o errata configurazione delle variabili d'ambiente e delle credenziali. L'assenza di parametri come APP_KEY, SECRET_KEY_BASE, password del database o configurazioni OAuth provoca comportamenti anomali, quali cicli infiniti di autenticazione, invalidazione delle sessioni, fallimento nell'invio di email o schermate d'errore generiche.

Anche l'infrastruttura di rete può presentare ostacoli. Il server di destinazione potrebbe non avere le medesime porte aperte, il firewall potrebbe bloccare il traffico in ingresso o il reverse proxy potrebbe indirizzare le richieste verso una porta interna errata. Inoltre, i record DNS potrebbero continuare a puntare al server di origine. Se l'applicazione risulta raggiungibile ma non risponde correttamente, la nostra guida di risoluzione dei problemi a tre livelli aiuta a isolare anomalie relative a dominio, server e applicazione: /blog/perche-il-mio-sito-non-si-carica.

Infine, occorre prestare attenzione alla configurazione HTTPS. Un certificato non valido o scaduto genera avvisi di sicurezza nei browser degli utenti anche a fronte di un'applicazione perfettamente funzionante. Se il precedente ambiente gestiva l'emissione dei certificati in modo automatico, è necessario accertarsi che la medesima automazione sia attiva sul nuovo server prima di reindirizzare il traffico.

Qual è l’ordine più sicuro per spostare uno stack Docker Compose?

Avvia la procedura eseguendo un inventario dettagliato dell'ambiente. Documenta container, volumi, cartelle montate, file d'ambiente, nomi di dominio, porte impegnate, cron job e percorsi dei backup. Questa mappatura rappresenta la guida di riferimento per l'intero processo.

Successivamente, predisponi il nuovo server mentre l'ambiente di origine rimane pienamente operativo. Installa i prerequisiti software, ricrea la struttura delle directory e posiziona i file compose.yaml e le configurazioni d'ambiente nei relativi percorsi. L'obiettivo è riprodurre un ambiente del tutto equivalente a quello di origine.

Procedi quindi con il trasferimento dei dati. Per i database, la prassi consigliata prevede l'esecuzione di un dump coerente della base dati oppure la copia diretta del volume previa sospensione temporanea del servizio, a seconda dell'architettura e del livello di discontinuità tollerabile. Per i file statici e i contenuti caricati dagli utenti, occorre trasferire l'effettivo contenuto delle directory.

A questo punto, avvia lo stack sul nuovo server senza instradare il traffico pubblico. Analizza i log di sistema, effettua l'autenticazione, carica file di test, verifica l'invio delle email e accertati della corretta comunicazione tra applicazione, database, servizi di cache e worker di background.

Esclusivamente a seguito del completamento dei test, procedi all'aggiornamento dei record DNS. Poiché i tempi di propagazione possono variare, è opportuno ridurre preventivamente il valore di TTL (Time To Live) dei record interessati per velocizzare la diffusione del nuovo indirizzo IP.

Per la gestione dei salvataggi, l'aspetto fondamentale consiste nella verifica della procedura di ripristino. Per approfondire questa metodologia, consulta la guida dedicata: /blog/backup-del-server.

Come eviti downtime e perdita di dati?

I tempi di inattività coincidono con l'intervallo compreso tra la dismissione del vecchio server e la piena operatività della nuova infrastruttura. La riduzione di tale intervallo dipende dal livello di preparazione eseguito prima dello switch finale.

Per applicazioni prevalentemente statiche la procedura è lineare: si trasferiscono i file, si avvia il nuovo stack, si esegue il collaudo e si aggiornano i puntamenti DNS verso la nuova macchina.

Per piattaforme dinamiche con utenti attivi, la sincronizzazione finale dei dati è un passaggio critico. Eventuali transazioni, caricamenti o aggiornamenti di profilo effettuati sul vecchio server durante la migrazione rischiano di non essere riportati nel nuovo ambiente. Per questo motivo si raccomanda una breve finestra di manutenzione per sospendere le operazioni di scrittura, sincronizzare gli ultimi dati, collaudare il sistema e riindirizzare il traffico.

Presta attenzione ai task in background: la simultanea esecuzione di worker di coda o job pianificati sia sul server di origine sia su quello di destinazione può causare la doppia elaborazione dei processi, con conseguente invio duplicato di notifiche o addebiti ripetuti. Durante la transizione deve essere chiaramente definito quale server sia autorizzato all'esecuzione delle attività.

La soluzione semplificata

Server Manager ti aiuta a gestire la migrazione in modo chiaro e strutturato, mantenendo visibile l'intera architettura senza dover ricorrere a note o comandi dispersi. Il risultato è un'infrastruttura ordinata in cui applicazioni, domini, certificati HTTPS e servizi collegati rimangono tracciabili e facilmente consultabili anche nel tempo.

Questo approccio previene le criticità tipiche delle migrazioni con Docker Compose: variabili d'ambiente mancanti, puntamenti DNS errati, certificati SSL non validi, conflitti di risorse tra progetti diversi o l'incertezza sulla mappatura delle porte a distanza di mesi.

Il valore principale consiste nel garantire la leggibilità della configurazione nel tempo. In caso di interventi futuri o manutenzioni, non occorrerà ricostruire i passaggi tecnici a ritroso: la struttura del sistema risulterà chiara, consentendo azioni mirate sui singoli componenti.

FAQ

**È sufficiente copiare il solo file compose.yaml?** No. Il file definisce l'architettura dei servizi ma non contiene i dati. È necessario trasferire anche i volumi, le directory montate, i file delle variabili d'ambiente e le configurazioni relative a domini e proxy.

È preferibile migrare direttamente i volumi Docker o eseguire un export del database? Per i database, l'esportazione tramite dump nativo garantisce una maggiore integrità dei dati. Per i file multimediali e le risorse statiche dell'applicazione, è corretto procedere con la copia diretta dei file dal filesystem.

È necessario arrestare lo stack sul vecchio server prima della migrazione? Non durante le fasi di preparazione e collaudo. Tuttavia, per la sincronizzazione finale dei dati è consigliabile sospendere temporaneamente le operazioni di scrittura per evitare disallineamenti.

Perché l'applicazione si avvia ma i dati risultano assenti o non aggiornati? Questo comportamento indica che il container sta utilizzando un nuovo volume privo di dati, che il percorso di bind mount non è corretto oppure che la stringa di connessione punta a una base dati differente.

In quale momento occorre aggiornare i record DNS? L'aggiornamento va eseguito unicamente dopo aver verificato il corretto avvio dello stack sul nuovo server, la presenza e l'integrità dei dati, il funzionamento dei certificati HTTPS e il superamento dei test funzionali tramite indirizzo IP o dominio di staging.

Com’è fatto uno spostamento pulito?

Una migrazione Docker Compose eseguita correttamente si distingue per la sua regolarità e controllabilità. Il server di destinazione viene predisposto in anticipo, i dati vengono trasferiti e verificati con cura, lo stack viene collaudato prima dell'esposizione pubblica e i record DNS vengono aggiornati solo a seguito del pieno riscontro operativo.

L'operazione si considera conclusa con successo quando l'intera configurazione risulta chiara e documentata: la collocazione dei dati è definita, i parametri d'ambiente sono verificati, l'instradamento del traffico è confermato e le procedure di ripristino risultano operative.