Collega Nextcloud a un container Collabora CODE self-hosted

Per connettere Nextcloud a un container Collabora Online Development Edition (CODE) self-hosted, esegui CODE su un nome host separato, mettilo dietro HTTPS e inserisci il suo URL pubblico in Nextcloud Office. Il container CODE deve inoltre consentire l'origine del sito Nextcloud come host WOPI. Nell'esempio seguente, Nextcloud è cloud.example.come Collabora è office.example.com; sostituisci entrambi con i tuoi nomi host reali.

Cosa bisogna preparare prima di iniziare?

È necessario disporre di un'installazione funzionante di Nextcloud, di un host Docker in grado di eseguire il container CODE, di record DNS per i nomi host di Nextcloud e Collabora e di certificati HTTPS validi per entrambi i siti pubblici. L'host Nextcloud e il server Collabora devono essere in grado di comunicare tra loro tramite la rete. Un server Collabora dedicato è pensato per migliorare la capacità rispetto all'opzione CODE integrata; essendo ancora in fase di sviluppo, si consiglia di consultare i termini e le linee guida di rilascio di Collabora prima di utilizzarlo per implementazioni di grandi dimensioni o critiche per l'azienda.

Questa procedura presuppone che un proxy inverso sia in esecuzione sull'host Docker e inoltri il traffico HTTPS office.example.comalla porta locale del container. Se il proxy è in esecuzione in un container diverso o su un'altra macchina, non copiare la mappatura della porta di loopback senza modifiche: utilizzare una rete Docker privata o un indirizzo host privato raggiungibile dal proxy e proteggere il backend con un firewall in modo che non sia esposto pubblicamente.

1. Avvia il contenitore CODE

Innanzitutto, scarica l'immagine e avvia un container. Nelle impostazioni dell'alias, utilizza l'origine pubblica di Nextcloud, specificando protocollo e porta. Non inserire l'URL di Collabora. L'esempio di installazione Docker di Nextcloud utilizza questo schema:

docker pull collabora/code
docker run -t -d -p 127.0.0.1:9980:9980 \
  -e 'aliasgroup1=https://cloud.example.com:443' \
  --restart always \
  --cap-add MKNOD \
  collabora/code

Il binding loopback significa che la porta 9980 è raggiungibile solo dall'host Docker, ad esempio tramite un reverse proxy sullo stesso host. Il proxy fornisce ai browser e a Nextcloud un endpoint HTTPS pubblico, mantenendo privata la porta del container. Se Nextcloud viene servito su una porta non standard o tramite un hostname pubblico diverso, assicurati che l'alias corrisponda all'origine effettivamente utilizzata dagli utenti. Se disponi di più istanze di Nextcloud, configura ogni host WOPI consentito utilizzando la sintassi documentata di Collabora, anziché consentire domini arbitrari in modo generico.

Il comando sopra riportato segue l'esempio Docker del manuale di amministrazione di Nextcloud 35. Prima dell'utilizzo in produzione, consultare la documentazione corrente dell'immagine CODE e scegliere una politica di aggiornamento di release/tag adatta al proprio processo di manutenzione. Il riferimento all'immagine predefinita può cambiare con la pubblicazione delle release; pianificare gli aggiornamenti, monitorare il container e ritestare la modifica della documentazione dopo gli aggiornamenti.

2. Posiziona il container dietro il proxy inverso HTTPS

Configura il tuo proxy esistente per gestire https://office.example.come inoltrare le richieste al servizio CODE su 127.0.0.1:9980. Utilizza la configurazione proxy inverso corrente di Collabora per il tuo software proxy. Il proxy deve preservare i percorsi richiesti e supportare gli aggiornamenti WebSocket; la sessione del browser dell'editor dipende da essi. L'esempio Docker di Nextcloud include percorsi per /browser, /hosting/discovery, /hosting/capabilities, e /cool, incluso l'endpoint WebSocket. Alcune integrazioni utilizzano anche il percorso di compatibilità /lool.

Non considerare il caricamento corretto della homepage come prova del corretto funzionamento del proxy. Un proxy che gestisce le normali richieste HTTPS ma non riesce ad aggiornare le connessioni WebSocket può mostrare la finestra dell'editor e poi lasciarla in fase di caricamento o disconnessa. Utilizza un certificato pubblico valido per il nome host di Collabora. Mantieni la porta 9980 chiusa verso Internet quando il proxy è destinato a essere l'unico punto di accesso.

3. Abilita Nextcloud Office e inserisci l'URL del server

In Nextcloud, apri App e installa o abilita Nextcloud Office (l' richdocumentsintegrazione). Quindi apri le impostazioni di amministrazione → Office , scegli l'opzione server Collabora esterno e inserisci https://office.example.com. Salva l'impostazione. Usa l'URL pubblico, non localhost:9980: il server Nextcloud e i browser degli utenti devono risolvere lo stesso endpoint Collabora esterno.

Il manuale di amministrazione di Nextcloud indica che l'URL del server configurato deve utilizzare lo stesso protocollo dell'installazione di Collabora e raccomanda HTTPS. Dopo il salvataggio, Nextcloud potrebbe mostrare lo stato di connettività o di rilevamento. Se segnala un problema con il certificato, il DNS o WOPI, risolvilo prima di provare ad aprire un file.

4. Verificare il percorso WOPI e aprire un documento di prova

WOPI è il protocollo utilizzato da Nextcloud per consentire a Collabora un accesso controllato a un documento. Nelle impostazioni di amministrazione di Office di Nextcloud, esamina l' elenco degli indirizzi consentiti per le richieste WOPI e limita le richieste agli indirizzi IP da cui il servizio Collabora si connette a Nextcloud. Configura inoltre Collabora in modo che accetti solo l'host WOPI previsto. L'indirizzo esatto può variare in presenza di container, NAT o proxy inverso, quindi utilizza l'indirizzo sorgente effettivamente rilevato da Nextcloud nei suoi log anziché fare delle supposizioni.

Per una verifica funzionale, accedi come un normale utente Nextcloud, crea o carica un piccolo file DOCX o ODT e aprilo dalla sezione File. Verifica che l'editor si carichi, apporta una modifica innocua, attendi l'indicatore di salvataggio, chiudi il documento, quindi riaprilo e verifica che la modifica sia stata mantenuta. Esegui il test con ogni tipo di file e gruppo di utenti rilevante per la tua implementazione; un test DOCX riuscito non garantisce che ogni formato o percorso di autorizzazione sia configurato correttamente.

Cosa bisogna controllare se l'editor non si apre?

• Errore di rilevamento o di connessione: verificare che l' office.example.comindirizzo venga risolto dal server Nextcloud e dal browser, che il certificato sia valido e che il proxy invii /hosting/discoverya CODE.
• Caricamento infinito o editor disconnesso: verifica la gestione dell'aggiornamento WebSocket del proxy inverso e i /coolpercorsi. Esamina i log del proxy e del container per individuare le richieste rifiutate.
• Host WOPI rifiutato: confronta la configurazione aliasgroup1con l'origine pubblica esatta di Nextcloud, inclusi schema e porta. Verifica l'elenco di indirizzi WOPI consentiti di Nextcloud rispetto all'indirizzo IP di origine di Collabora visibile a Nextcloud.
• Funziona sull'host ma non in Nextcloud: verifica la connettività dal server Nextcloud all'URL pubblico di Collabora. Il nome host interno di un container o l'indirizzo localhost dell'host Docker non sono automaticamente raggiungibili da ogni altro container.
• Avviso relativo al certificato: correggere la catena di certificati o la mancata corrispondenza del nome host. Disabilitare la verifica del certificato può nascondere la causa e indebolire la connessione.

Per la diagnosi, confronta la tua configurazione con l' esempio ufficiale di installazione Docker di Nextcloud , le relative linee guida di configurazione di Office e WOPI e la documentazione di Collabora sull'immagine Docker CODE e sul reverse proxy . Tali riferimenti sono soggetti a modifiche di versione; i comandi qui riportati riflettono l'esempio di amministrazione di Nextcloud 35 disponibile il 10 ottobre 2026.