Come eseguire il backup e il ripristino in modo sicuro dei file di configurazione di Collabora CODE

Collabora Online Development Edition (CODE) 26.04.4.2 è stato rilasciato il 24 settembre 2026. Questo è importante per la pianificazione dei backup perché la versione 26.04 ha modificato anche alcune parti della gestione consigliata del percorso del reverse proxy per i nuovi URL WebSocket. Se ti stai preparando per un aggiornamento, una migrazione o un ripristino di emergenza, il backup di un solo file XML potrebbe non essere sufficiente a riprodurre un'implementazione funzionante.

Il nucleo verificato è semplice: il file di configurazione principale del server di Collabora è /etc/coolwsd/coolwsd.xml, incluso all'interno del container ufficiale CODE. La documentazione ufficiale di Docker supporta anche la copia di questo file fuori da un container, la sua ricopia al suo interno o il suo montaggio tramite bind mount dall'host. Le parti che variano sono tutte quelle che lo circondano: variabili d'ambiente Docker, bind mount, chiavi di prova WOPI, terminazione TLS e configurazione del reverse proxy.

Questa guida illustra una procedura di backup e ripristino prudente sia per le installazioni di pacchetti nativi che per le implementazioni Docker. Separa intenzionalmente ciò che è confermato dalla documentazione di Collabora da ciò che dipende dalla propria implementazione.

Cosa dovrebbe includere un backup di Collabora CODE?

Verificato: /etc/coolwsd/coolwsd.xml è il file di configurazione principale di Collabora Online. Collabora documenta direttamente questo percorso e descrive il file come autoesplicativo per le opzioni del server disponibili. Consultare il manuale ufficiale dell'SDK di Collabora Online .

Dipendenza dalla distribuzione: un ripristino completo potrebbe richiedere anche la configurazione utilizzata per avviare il servizio. Per Docker, ciò può includere Compose YAML, variabili d'ambiente, bind mount, segreti e file montati dall'host. Per un'installazione nativa, può includere un host virtuale proxy inverso e i certificati, se gestiti sullo stesso server.

Azione: prima di creare un archivio, annota se la tua istanza è un'installazione nativa del pacchetto o una distribuzione Docker/Compose. Non dare per scontato che la stessa procedura di ripristino si applichi a entrambe.

Errori comuni da chiarire prima di iniziare

Il backup del file coolwsd.xml non include i documenti utente.

CODE è normalmente connesso a una piattaforma di archiviazione tramite WOPI. I documenti rimangono sotto il controllo di tale piattaforma di archiviazione, come Nextcloud o un altro host WOPI. Il ripristino della configurazione di CODE, pertanto, non comporta il ripristino dei documenti stessi.

Azione: eseguire il backup dell'host WOPI e del relativo archivio dati utilizzando la procedura di backup specifica del prodotto. Considerare questo backup del codice come un backup della configurazione del servizio.

Un container Docker non è il backup

Un container può essere ricreato a partire da un'immagine. La configurazione passata tramite variabili d'ambiente o bind mount può risiedere all'esterno del container, mentre le modifiche apportate solo all'interno del container possono andare perse quando il container viene sostituito.

Azione: salvare la definizione di distribuzione e i file montati sull'host, non solo il filesystem del container.

Sovrascrivere un vecchio file coolwsd.xml a una versione più recente non è sempre il metodo di ripristino più sicuro.

Le opzioni di configurazione possono variare tra le diverse versioni di CODE. Le note di rilascio di Collabora indicano continui cambiamenti relativi al server e al proxy nella serie 26.04, inclusi aggiornamenti alle raccomandazioni sul proxy per l'URL WebSocket compatto. Consultare le note di rilascio ufficiali di CODE 26.04 .

Azione: registrare la versione del CODICE con ogni backup. Quando si ripristina una versione diversa, confrontare il file salvato con quello predefinito del nuovo pacchetto prima di sostituirlo completamente.

Passaggio 1: Registrare la versione installata e il tipo di distribuzione

Iniziate raccogliendo informazioni sufficienti per riprodurre l'ambiente. Nel caso di una distribuzione in container, esaminate il container in esecuzione e la sua immagine:

docker ps --filter name=collabora
docker inspect collabora --format '{{.Config.Image}}'
docker inspect collabora --format '{{json .Mounts}}'

Se il tuo container utilizza un nome diverso, sostituiscilo collaboradi conseguenza. L'immagine ufficiale è pubblicata come collabora/code; Docker Hub attualmente identifica l'immagine 26.04.4.2 nell'ultima versione. Consulta l' immagine ufficiale di Collabora CODE su Docker Hub .

Per l'installazione di un pacchetto nativo, annota la versione del pacchetto utilizzando il gestore di pacchetti che stai effettivamente usando. Su Debian o Ubuntu, ad esempio:

dpkg-query -W 'coolwsd*' 'collaboraoffice*' 2>/dev/null

Azione: salvare l'output della versione nella stessa directory di backup protetta dell'archivio di configurazione.

Passaggio 2: Eseguire il backup della configurazione principale e dei metadati di distribuzione

Installazione del pacchetto nativo

Crea una directory di backup contenente solo la directory principale e archivia l'intera /etc/coolwsddirectory anziché selezionare solo il file XML principale. In questo modo verranno conservati tutti i file aggiuntivi che il pacchetto installato o le personalizzazioni locali hanno inserito al suo interno.

sudo install -d -m 700 /var/backups/collabora
sudo tar -C /etc -czpf \
  /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  coolwsd

Questo comando modifica intenzionalmente il percorso /etcprima dell'archiviazione, in modo che l'archivio contenga un coolwsd/percorso relativo anziché un percorso assoluto del file system.

Docker o Docker Compose

La documentazione di Collabora afferma che l'immagine ufficiale contiene /etc/coolwsd/coolwsd.xmle che gli amministratori possono copiarla, modificarla, ricopiarla o montarla dall'esterno del contenitore.

Se il file non è già montato tramite bind mount dall'host, copialo:

sudo install -d -m 700 /var/backups/collabora
docker cp collabora:/etc/coolwsd/coolwsd.xml \
  /var/backups/collabora/coolwsd.xml

Successivamente, cattura la configurazione del container:

docker inspect collabora --format '{{json .Config.Env}}' \
  > /var/backups/collabora/container-env.json

docker inspect collabora --format '{{json .Mounts}}' \
  > /var/backups/collabora/container-mounts.json

Importante: l'output relativo all'ambiente può contenere password, credenziali della console di amministrazione, nomi host o altri segreti. Assicurati che questi file siano leggibili solo dall'utente root e che le copie salvate al di fuori dell'host siano crittografate o protette in altro modo.

Se utilizzi Docker Compose, copia il file Compose e tutti i file di ambiente o segreti a cui fa riferimento dall'host. La loro posizione è specifica per la tua implementazione, quindi non esiste un percorso universale che si possa presumere affidabile.

Azione: verificare che il backup includa la fonte di verità. Se coolwsd.xmlè montato tramite bind, eseguire il backup del file host. Se la configurazione viene fornita tramite variabili d'ambiente, conservare la configurazione di Compose/run che definisce tali variabili.

Passaggio 3: includere chiavi di prova, configurazione proxy e TLS solo quando necessario.

Questi componenti sono importanti proprio perché non sono identici in ogni installazione.

Chiave di prova WOPI: Collabora documenta che le installazioni RPM e DEB generano automaticamente la coppia di chiavi di prova WOPI. Per Docker, la coppia di chiavi non è inclusa nell'immagine pubblica; quando viene utilizzata, deve essere generata e fornita al container, in genere tramite un volume. Il manuale documenta coolconfig generate-proof-keyla generazione della chiave. Poiché la chiave Docker risiede al di fuori dell'immagine immutabile, la perdita della chiave montata sul lato host può modificare l'identità utilizzata per la firma di prova WOPI.

Azione: utilizzare l'elenco di montaggio del container per identificare la posizione host di qualsiasi mount di chiave di prova ed eseguire un backup sicuro di quel file o directory lato host. Non creare un percorso se la distribuzione non ne utilizza uno.

Proxy inverso: Apache, Nginx, HAProxy, Traefik o un altro proxy possono gestire il nome host pubblico, la terminazione TLS, il routing WebSocket e le regole di inoltro delle richieste. Nella versione CODE 26.04, Collabora ha aggiornato le linee guida sui proxy per il nuovo URL WebSocket compatto, mantenendo in alcuni casi un fallback legacy.

Azione: esegui il backup della configurazione proxy esatta che gestisce il tuo hostname Collabora. Il suo percorso nel file system dipende dal sistema operativo e dal proxy in uso, quindi identificalo dalla configurazione proxy attiva anziché copiare un percorso generico da un tutorial.

Certificati TLS: esegui il backup solo se sono effettivamente di proprietà di questo host. Se la connessione TLS viene terminata su un bilanciatore di carico, un controller di ingresso, una CDN o un proxy inverso separato, il backup del certificato deve essere eseguito su tale server.

Passaggio 4: Verifica il backup prima di averne bisogno

Un tarcomando eseguito correttamente non è sufficiente. Verifica che l'archivio possa essere elencato e che il file di configurazione principale previsto sia presente.

sudo tar -tzf /var/backups/collabora/coolwsd-etc-$(date +%F).tar.gz \
  | grep 'coolwsd/coolwsd.xml'

Crea un checksum per la verifica off-host:

cd /var/backups/collabora
sha256sum * > SHA256SUMS

Successivamente, copia il backup in una seconda posizione protetta utilizzando il tuo normale sistema di backup. Non lasciare l'unica copia sullo stesso host che stai proteggendo.

Azione: prova almeno una volta a estrarre il backup in una directory temporanea. Un backup che non hai mai aperto è solo un'ipotesi.

Passaggio 5: Ripristinare in modo conservativo, quindi convalidare il servizio in esecuzione.

Ripristinare un'installazione nativa

È preferibile installare prima la stessa versione di CODE. Interrompere il servizio, estrarre l'archivio in una directory temporanea e confrontare la configurazione salvata con quella predefinita appena installata:

sudo systemctl stop coolwsd
sudo mkdir -p /root/collabora-restore
sudo tar -xzf /var/backups/collabora/coolwsd-etc-YYYY-MM-DD.tar.gz \
  -C /root/collabora-restore

sudo diff -u \
  /etc/coolwsd/coolwsd.xml \
  /root/collabora-restore/coolwsd/coolwsd.xml

Se le versioni corrispondono e si intende eseguire una sostituzione completa, conservare prima la nuova directory come copia di ripristino:

sudo cp -a /etc/coolwsd /etc/coolwsd.pre-restore
sudo cp -a /root/collabora-restore/coolwsd/. /etc/coolwsd/
sudo systemctl start coolwsd

Se le versioni differiscono, unisci le impostazioni che hai effettivamente modificato anziché sostituire indiscriminatamente il nuovo file. In questo modo eviti di scartare le nuove impostazioni predefinite o gli elementi obbligatori introdotti dalla versione più recente.

Ripristinare una distribuzione Docker

Ricrea il container a partire dall'immagine registrata e dal file Docker Compose o docker rundalla definizione originale. Ripristina la configurazione bind-mounted dell'host, le chiavi di verifica e gli altri file esterni nei percorsi originali dell'host prima di avviare il container.

Se hai scelto deliberatamente di mantenere coolwsd.xmlil file all'interno del container anziché utilizzarlo come bind mount, la procedura documentata da Collabora consente di ricopiarlo. In pratica, un bind mount sull'host è più facile da riprodurre perché la configurazione persiste anche in caso di sostituzione del container.

Azione: ripristinare prima la definizione di distribuzione, quindi ripristinare i file a cui fa riferimento. In questo modo si mantengono coerenti le variabili d'ambiente, i volumi e la configurazione XML.

Come verificare che il ripristino sia effettivamente andato a buon fine

Non giudicare il successo solo in base all'avvio del processo. Verifica il servizio dallo stesso percorso di rete utilizzato dai client.

Per un'installazione nativa:

sudo systemctl status coolwsd --no-pager
sudo journalctl -u coolwsd -n 100 --no-pager

Per Docker:

docker ps --filter name=collabora
docker logs --tail 100 collabora

Collabora documenta l' /hosting/capabilitiesendpoint come un modo per recuperare, tra le altre informazioni, il nome e la versione del prodotto in esecuzione. Tramite il tuo URL pubblico di Collabora, testalo con:

curl -fsS https://office.example.com/hosting/capabilities

Sostituisci il nome host con il tuo. Apri inoltre un documento reale dall'host WOPI e verifica che la modifica, il salvataggio e la riconnessione funzionino correttamente tramite il normale percorso del proxy inverso.

Azione: considerare il ripristino completato solo dopo che l'endpoint delle funzionalità ha risposto e un documento effettivo può essere aperto e salvato.

Lista di controllo pratica per il backup

Raccomandazione finale

Il piano di ripristino più affidabile per Collabora CODE non consiste nella copia di un singolo file. Mantieni coolwsd.xmlla versione esatta di CODE e la definizione di distribuzione insieme, come un unico set ripristinabile. Aggiungi chiavi di prova, regole proxy e materiale TLS solo dove la tua architettura li richiede effettivamente. Per gli aggiornamenti, ripristina la stessa versione quando possibile; se passi a una versione più recente, confronta e unisci la configurazione anziché sovrascrivere le nuove impostazioni predefinite senza prima verificarle.

Al 6 ottobre 2026, la versione corrente di CODE 26.04.4.2 è indicata nelle note di rilascio ufficiali di Collabora per la versione 26.04 e nei metadati dell'immagine Docker. Prima di una futura migrazione, si consiglia di consultare nuovamente queste fonti ufficiali, poiché le versioni delle immagini, i suggerimenti relativi ai proxy e le opzioni di configurazione sono in continua evoluzione.