Distribuisci Collabora CODE su Kubernetes con Helm

Al 10 ottobre 2026, il registro dei pacchetti upstream elenca la versione 1.3.0 del chart come ultima release. L'installazione del chart è solo una parte di un'implementazione funzionante. Sono necessari anche un hostname pubblico di Collabora, una voce valida nella lista di autorizzazione WOPI per l'host di archiviazione dei documenti e una configurazione di ingress che mantenga le richieste per ciascun documento sullo stesso pod. Il registro dei pacchetti upstream elenca la versione 1.3.0 del chart al momento della stesura di questo documento; verificare il repository prima dell'installazione poiché la versione del chart Helm e la versione dell'immagine del container CODE sono valori separati.

Questa procedura utilizza il chart ufficiale collabora/collabora-onlinee un NGINX Ingress Controller. Il file README del chart include anche esempi HAProxy; le annotazioni ingress sono specifiche del controller, quindi utilizza l'esempio relativo al controller installato anziché combinare annotazioni diverse.

Cosa preparare per prima

• Un cluster Kubernetes con autorizzazione a creare namespace, Deployment, Service e Ingress.
• Helm 3 e un controller ingress installato in grado di fornire HTTPS per un nome host come office.example.com.
• Il nome host pubblico del client WOPI, come Nextcloud o Seafile. Questo è l'host che Collabora deve autorizzare; non è il nome host di Collabora.
• Un segreto di Kubernetes per le credenziali della console di amministrazione di Collabora. Non conservare la password di esempio del chart né inserire una password reale in un file di valori.

1. Aggiungi il repository ufficiale dei grafici e controlla la release

Collabora pubblica il suo chart dal repository online del progetto. Aggiungilo, aggiorna l'indice locale e controlla i metadati del chart e i valori predefiniti prima dell'installazione:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm show chart collabora/collabora-online
helm show values collabora/collabora-online

La versione del grafico identifica il pacchetto, non necessariamente il tag dell'immagine CODE. Controlla il repository delle immagini e il tag nei valori di rilascio, quindi aggiungi ai preferiti la versione del grafico che hai esaminato per aggiornamenti ripetibili.

Crea un Secret con ambito namespace utilizzando il flusso di lavoro di gestione dei segreti approvato. I valori del grafico supportano un Secret esistente e nomi di chiave configurabili; i nomi di chiave predefiniti sono usernamee password. Verifica che il Secret esista nel collaboranamespace prima dell'installazione.

2. Impostare le opzioni host, ingress e proxy di WOPI

Crea my_values.yaml. Sostituisci entrambi i nomi host di esempio con i tuoi domini pubblici effettivi. Il aliasgroupsvalore identifica il client WOPI (ad esempio, il server Seafile o Nextcloud). L'host Ingress e server_nameidentifica il servizio Collabora a cui accedono i browser degli utenti.

replicaCount: 1

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    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

autoscaling:
  enabled: false

collabora:
  aliasgroups:
    - host: "https://files.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true
  server_name: office.example.com:443
  existingSecret:
    enabled: true
    secretName: collabora-admin
    usernameKey: username
    passwordKey: password

Questo esempio segue il modello di ingresso NGINX documentato da Collabora: le richieste vengono sottoposte ad hashing utilizzando il WOPISrcparametro e i timeout di lettura e invio del proxy vengono estesi per le sessioni dei documenti. Verifica i nomi delle annotazioni con la versione del tuo ingress-controller. Se utilizzi HAProxy, fai riferimento alle annotazioni HAProxy e alla configurazione di bilanciamento presenti nel file README del chart.

Le opzioni ssl.enable=falsee ssl.termination=truesono per una progettazione in cui TLS termina all'ingresso e il traffico dall'ingresso al pod è interno. Non significano che l'endpoint pubblico debba utilizzare HTTP. Mantieni l'hostname di ingresso su HTTPS e non esporre il servizio HTTP semplice del pod direttamente a Internet. Imposta server_namequando Collabora si trova dietro un proxy inverso o non può dedurre direttamente il suo hostname esterno.

Per più repliche fisse, impostale replicaCountcon attenzione e mantieni l'affinità di sessione. Il README upstream attualmente indica che HPA è disabilitato perché il ridimensionamento può interferire con la modifica collaborativa e il copia/incolla. Un numero maggiore di repliche da solo non garantisce un routing corretto; verifica che il tuo ingress invii le richieste per lo stesso documento allo stesso pod.

3. Installa Collabora CODE

Installa la release dal repository ufficiale e attendi che il deployment sia pronto:

helm install --create-namespace \
  --namespace collabora \
  collabora-online collabora/collabora-online \
  --values my_values.yaml

kubectl get pods -n collabora
kubectl get ingress -n collabora

Se stai aggiornando una release esistente, utilizza helm upgradelo stesso nome di release, namespace e file di valori anziché crearne una seconda. Prima di aggiornare un'istanza di produzione, consulta le note di rilascio del chart e le modifiche visualizzate.

Verifica che il pod sia pronto e che l'Ingress segnali l'host e l'indirizzo previsti. Se lo stato rimane in sospeso, esamina gli eventi e i log prima di modificare le impostazioni delle risorse:

kubectl describe pods -n collabora
kubectl logs -n collabora deployment/<deployment-name>

Dimensiona CPU e memoria in base al tuo carico di lavoro e alla capacità del cluster. Il file README del grafico fornisce esempi di richieste e limiti, non una garanzia per ogni implementazione. Fai attenzione a possibili rallentamenti, interruzioni per esaurimento della memoria e riavvii.

4. Verifica del ritrovamento e della modifica dei documenti

Dopo aver attivato DNS e TLS, richiedete l'endpoint di rilevamento di Collabora tramite il nome host pubblico:

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

Una risposta positiva dovrebbe contenere il file XML di rilevamento WOPI anziché una pagina di errore di ingresso o un avviso relativo al certificato. Successivamente, configura il client WOPI con lo stesso URL pubblico di Collabora e verifica che Collabora aliasgroupsincluda il nome host e la porta HTTPS di tale client. L'impostazione esatta del client dipende dal prodotto di archiviazione.

Apri un documento di prova dal client WOPI e apporta una piccola modifica. Verifica che l'editor si carichi, che una seconda sessione del browser possa unirsi se è necessaria la collaborazione e che la modifica venga salvata nel servizio di archiviazione. Questo controllo end-to-end verifica il funzionamento di DNS, TLS in ingresso, routing di sessione, autorizzazione host WOPI e trasferimento file.

Presupposti comuni da verificare

• "Helm installato, quindi Collabora è pronto per la produzione." Il grafico crea risorse Kubernetes, ma DNS, TLS, autorizzazione host WOPI, routing in ingresso e dimensionamento delle risorse dipendono ancora dal cluster. Verificare ciascuno degli elementi sopra indicati.
• "L'host di ingresso e l'host WOPI sono la stessa impostazione." Spesso differiscono: l'host di ingresso è l'indirizzo pubblico di Collabora; l'host WOPI è il server di archiviazione. Inserire ciascuno nel campo corretto del diagramma.
• "Un maggior numero di repliche migliora automaticamente la collaborazione." Il grafico a monte documenta l'affinità di sessione e attualmente disabilita HPA perché il ridimensionamento può interrompere la modifica collaborativa. Inizia con una sola replica o con un numero fisso predefinito e preserva l'affinità di routing.
• "È possibile fornire un piccolo frammento XML come configurazione personalizzata." Il valore del grafico coolwsd_xml_contentsostituisce il file di configurazione predefinito e richiede il contenuto completo del file. Si consiglia di utilizzare i valori specifici del grafico per i gruppi di alias e i parametri, a meno che non si disponga di una configurazione XML completa e compatibile con la versione.

Riferimenti ufficiali

• README per la distribuzione del chart Helm di Collabora Online
• Valori ufficiali del grafico e opzioni di configurazione
• Versioni del pacchetto di diagrammi Collabora
• Documentazione di Kubernetes Ingress