Come configurare Collabora CODE su Kubernetes con Helm

Una pagina di Collabora Online può rimanere vuota o segnalare che il server dell'ufficio non è disponibile anche dopo l'avvio del pod CODE. Un pod funzionante è solo una parte della configurazione: il browser e l'applicazione WOPI devono raggiungere Collabora tramite l'hostname pubblico, le impostazioni TLS e proxy devono essere compatibili e Collabora deve considerare attendibile l'host WOPI. Il chart Helm ufficiale di Collabora distribuisce il server in Kubernetes; non installa né configura Nextcloud, ownCloud o un altro host WOPI.

Questa guida utilizza il chart Helm gestito da Collabora con un esempio di NGINX Ingress. Sostituisci i domini di esempio con i tuoi. CODE è Collabora Online Development Edition, pensato per la valutazione, l'uso domestico e i piccoli team; Collabora afferma che non è raccomandato per ambienti di produzione che necessitano di una versione stabile e supportata. Per carichi di lavoro di produzione, valuta l'offerta Collabora Online supportata e i relativi termini di licenza e supporto.

Cosa ti serve prima dell'installazione

• Un cluster Kubernetes funzionante kubectle Helm 3 con accesso al cluster.
• Un controller Ingress installato nel cluster. L'esempio seguente utilizza ingress-nginx; il diagramma di Collabora documenta anche HAProxy e supporta altre configurazioni di routing.
• Un nome DNS che office.example.compunta all'indirizzo di ingresso pubblico, più un certificato TLS memorizzato come segreto di Kubernetes nello spazio dei nomi Collabora.
• Un'applicazione WOPI come Nextcloud con un URL del tipo cloud.example.com. Collabora deve essere in grado di raggiungere l'applicazione WOPI e i browser dell'applicazione e degli utenti devono essere in grado di raggiungere Collabora.
• Un piano TLS chiaro. Questo esempio termina HTTPS all'ingresso e invia HTTP al servizio Collabora all'interno del cluster.

Per una distribuzione rapida a casa o per un test, un singolo pod CODE semplifica il routing. Più repliche possono migliorare la capacità, ma la guida Kubernetes di Collabora indica un requisito di bilanciamento del carico basato su WOPISrc in modo che le sessioni di modifica per lo stesso documento raggiungano lo stesso pod. Non scalare le repliche prima di aver verificato che il controller di ingresso possa fornire l'affinità necessaria.

Passaggio 1: Aggiungi la tabella ufficiale e seleziona una versione

Collabora pubblica il suo chart dal progetto CollaboraOnline. La pagina delle release attualmente elenca la versione 1.3.5 del chart (verificata il 6 ottobre 2026). Controlla le versioni disponibili nel tuo ambiente e blocca la versione del chart in modo che un successivo aggiornamento del repository non modifichi silenziosamente il chart che distribuisci:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

Il repository ufficiale dei grafici è utile per verificare le impostazioni predefinite correnti prima di apportare modifiche:

helm show values collabora/collabora-online --version 1.3.5

Se, seguendo questa guida, il repository elenca un chart compatibile più recente, prima di sostituirlo è necessario esaminare le note di rilascio e i valori relativi a tale versione. La versione del chart e la versione dell'immagine dell'applicazione CODE sono parametri di rilascio correlati, ma non corrispondono alla stessa impostazione.

Passaggio 2: Creare uno spazio dei nomi e proteggere la password di amministratore

Crea il namespace e un Kubernetes Secret per le credenziali facoltative di amministratore di Collabora del chart. Sostituisci la password segnaposto con un segreto sicuro oppure crea il Secret tramite il gestore dei segreti della tua organizzazione o il flusso di lavoro dei segreti di GitOps. Non inserire una password reale in values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

Il grafico supporta il riferimento a un Secret esistente. Abilitando questa opzione si evita di inserire la password di amministratore direttamente nel file dei valori di Helm. Mantenere il Secret accessibile solo allo spazio dei nomi e agli utenti o account di servizio che amministrano questa distribuzione.

Passaggio 3: Configurare il nome host, l'host WOPI e l'ingresso

Crea un file denominato collabora-values.yaml. Questo esempio presuppone ingress-nginx, un TLS Secret denominato office-example-com-tlse Nextcloud all'indirizzo https://cloud.example.com. Il gruppo alias deve specificare l'host dell'applicazione WOPI a cui Collabora è autorizzato a connettersi; non si tratta del nome host pubblico di Collabora.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

L'esempio documentato nel diagramma utilizza aliasgroupsquesti parametri SSL per consentire all'host WOPI di utilizzare il protocollo quando un proxy inverso termina il TLS. In questa configurazione, il traffico esterno office.example.comutilizza HTTPS, mentre l'ingresso inoltra il traffico a Collabora tramite HTTP all'interno del cluster. Se l'ingresso utilizza il passthrough TLS o un protocollo interno diverso, non copiare ciecamente questi flag SSL; adattarli al percorso TLS effettivo e ai valori correnti del diagramma.

Verifica che il segreto TLS esista nello collaboraspazio dei nomi. Se utilizzi un controller di ingresso diverso, sostituisci la classe e le annotazioni con i corrispondenti elementi documentati di tale controller. Mantieni il traffico WebSocket abilitato e consenti le connessioni di lunga durata; le impostazioni predefinite del controller variano.

Passaggio 4: Eseguire il rendering e installare il grafico

Innanzitutto, genera i manifest per individuare eventuali errori YAML e rivedi le impostazioni di Ingress, Service e workload generate. Dopodiché, installa la release del chart bloccata:

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

Osserva le risorse non appena vengono rese disponibili:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Attendi che il pod diventi Pronto prima di connettere l'applicazione WOPI. Se rimane in stato In sospeso, verifica che il cluster disponga di CPU e memoria scheduled sufficienti e che eventuali selettori di nodi, taint o quote di risorse impediscano il posizionamento. Il grafico lascia all'operatore la scelta delle richieste e dei limiti delle risorse; il file README di Collabora fornisce valori di risorse di esempio più elevati per ambienti di produzione, ma il dimensionamento effettivo dipende dal numero di modifiche simultanee e dal carico di lavoro dei documenti.

Passaggio 5: Connetti Nextcloud o un altro host WOPI

Apri le impostazioni di Office o Collabora della tua applicazione WOPI e inserisci l'URL del servizio esterno https://office.example.com. In Nextcloud, il manuale di amministrazione descrive come impostare l'URL del server Collabora Online nelle impostazioni di amministrazione di Office. Verifica anche l'elenco di indirizzi consentiti per le richieste WOPI di Nextcloud se la tua configurazione limita gli host che possono connettersi. L'indirizzo deve essere raggiungibile sia dai browser degli utenti finali sia dal server dell'applicazione che effettua le richieste WOPI.

Se la connessione fallisce con un messaggio di "host WOPI non autorizzato" o simile, confronta l'URL effettivo dell'host WOPI con quello di collabora.aliasgroups. Verifica lo schema, il nome host e la porta e aggiungi deliberatamente eventuali nomi host alternativi legittimi. Evita di utilizzare modelli di host generici a meno che tu non ne comprenda l'effetto. Se utilizzi più di un'applicazione WOPI, segui la struttura del gruppo di alias documentata nella tabella per ciascun host anziché consentire tutti i domini.

Quando è opportuno espandere la rete oltre un singolo modulo?

Per una prova di piccole dimensioni, una replica con l'autoscaling disabilitato evita la complessità del routing. Per più repliche, il file README del grafico di Collabora mostra l'affinità NGINX in base WOPISrcall'argomento della query. Aggiungere l'annotazione documentata all'ingress quando si utilizza ingress-nginx:

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

Questo indirizza le richieste per lo stesso documento allo stesso pod di backend, il che è importante per la modifica collaborativa e le richieste di copia negli appunti. Controlla la documentazione per la versione esatta del tuo ingress-controller; un'annotazione supportata da ingress-nginx non è automaticamente valida per HAProxy, Traefik o un'implementazione dell'API Gateway. Dopo aver abilitato più repliche o l'autoscaling, testa le modifiche simultanee allo stesso documento e monitora i log di Collabora e i log di accesso ingress. Il dimensionamento delle risorse, il comportamento della sessione e l'alta disponibilità richiedono una convalida specifica per il carico di lavoro.

Verificare l'implementazione dall'esterno

1. Conferma che Kubernetes segnali il pod come pronto e che il servizio e l'ingress esistano: kubectl get pods,svc,ingress -n collabora.
2. Verifica l'endpoint di rilevamento pubblico. Dovrebbe restituire un file XML anziché un errore del browser o del proxy:

   curl -fsS https://office.example.com/hosting/discovery | head -c 300

3. Apri l'applicazione WOPI e modifica un documento di prova. Verifica che l'editor si carichi, che le modifiche vengano salvate e che, riaprendo il documento, il contenuto salvato sia visibile.
4. Se si utilizzano più repliche, aprire lo stesso documento in due sessioni diverse e verificare che entrambe possano collaborare senza dover riconnettersi ripetutamente. Questo aiuta a identificare eventuali problemi di affinità di sessione.
5. Esamina i log per individuare errori relativi a TLS, autorizzazione WOPI o server a monte:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   Se il grafico crea un carico di lavoro con un nome diverso, utilizzare kubectl get deployments -n collaborae sostituire il nome effettivo.

Una risposta di rilevamento positiva conferma che l'endpoint pubblico sta fornendo metadati di Collabora; non dimostra tuttavia che l'autenticazione WOPI o il salvataggio del documento funzionino correttamente. Il test end-to-end del documento rappresenta la verifica finale.

Punti di guasto comuni

• Ingress restituisce 404 o 502: verificare DNS, classe ingress, segreto TLS e endpoint del servizio. Confermare che ingress possa raggiungere il servizio Collabora sulla porta del servizio del chart.
• La fase di rilevamento funziona, ma l'editor rimane vuoto: controlla gli errori della console del browser e i log del proxy. Verifica le impostazioni di terminazione HTTPS, la gestione dei websocket e i timeout delle richieste di lunga durata.
• Host WOPI non autorizzato: consentire l'origine dell'applicazione WOPI in aliasgroups; non sostituire il nome host di office-server.
• Il pod si riavvia o viene rimosso: ispeziona kubectl describe podi log del container, quindi imposta richieste e limiti di risorse realistici per il cluster disponibile.
• La modifica diventa instabile dopo l'aggiunta di repliche: verificare l'affinità basata su WOPISrc e confermare che il controller mantenga l'argomento di query durante l'instradamento delle richieste.

Con il chart installato, l'endpoint di rilevamento raggiungibile e un documento reale aperto e salvato correttamente tramite l'applicazione WOPI, la distribuzione CODE principale funziona. Mantieni la versione del chart bloccata e ripeti questi controlli dopo gli aggiornamenti del chart, le modifiche all'ingress o le modifiche di scalabilità.

Riferimenti ufficiali

• Chart Helm di Kubernetes e guida alla distribuzione gestiti in collaborazione
• Valori del grafico Helm collaborativi
• collabora chart releases
• Linee guida di Collabora Online Development Edition (CODE)
• Manuale di configurazione di Nextcloud Office
• documentazione delle annotazioni di ingress-nginx
• Riferimento al comando di installazione di Helm