Comment configurer Collabora CODE sur Kubernetes avec Helm

Une page Collabora Online peut rester blanche ou indiquer que le serveur Office est indisponible, même après le lancement du pod CODE. Un pod opérationnel ne constitue qu'une partie de la configuration : le navigateur et votre application WOPI doivent pouvoir accéder à Collabora via le nom d'hôte public, les paramètres TLS et de proxy doivent être compatibles, et Collabora doit faire confiance à l'hôte WOPI. Le graphique Helm officiel de Collabora déploie le serveur dans Kubernetes ; il n'installe ni ne configure Nextcloud, ownCloud ou tout autre hôte WOPI.

Ce guide utilise le graphique Helm maintenu par Collabora avec un exemple d'entrée NGINX. Remplacez les domaines d'exemple par les vôtres. CODE est l'édition de développement de Collabora Online, conçue pour l'évaluation, l'utilisation personnelle et les petites équipes ; Collabora précise qu'elle n'est pas recommandée pour les environnements de production nécessitant une version stable et prise en charge. Pour les charges de travail en production, veuillez évaluer l'offre Collabora Online prise en charge ainsi que ses conditions de licence et de support.

Ce dont vous avez besoin avant l'installation

• Un cluster Kubernetes fonctionnel kubectl, et Helm 3 avec accès au cluster.
• Un contrôleur Ingress est installé dans le cluster. L'exemple ci-dessous utilise ingress-nginx ; le graphique Collabora documente également HAProxy et prend en charge d'autres configurations de routage.
• Un nom DNS pointant par exemple office.example.comvers l'adresse d'entrée publique, ainsi qu'un certificat TLS stocké en tant que secret Kubernetes dans l'espace de noms Collabora.
• Une application WOPI telle que Nextcloud, dont l'URL est par exemplecloud.example.com : Collabora, doit pouvoir accéder à cette application WOPI, et l'application ainsi que les navigateurs des utilisateurs doivent pouvoir accéder à Collabora.
• Un plan TLS clair. Cet exemple termine le trafic HTTPS à l'entrée et envoie du trafic HTTP au service Collabora au sein du cluster.

Pour un déploiement rapide à domicile ou pour des tests, un seul pod CODE simplifie le routage. Plusieurs réplicas peuvent augmenter la capacité, mais le guide Kubernetes de Collabora recommande un équilibrage de charge basé sur WOPISrc afin que les sessions d'édition d'un même document soient dirigées vers le même pod. N'augmentez pas le nombre de réplicas avant d'avoir vérifié que votre contrôleur d'entrée peut fournir l'affinité requise.

Étape 1 : Ajoutez le graphique officiel et sélectionnez une version

Collabora publie son graphique depuis le projet CollaboraOnline. La page de publication indique actuellement la version 1.3.5 (vérifiée le 6 octobre 2026). Vérifiez les versions disponibles dans votre environnement et conservez la version du graphique afin qu'une mise à jour ultérieure du dépôt ne modifie pas silencieusement le graphique déployé.

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

Le dépôt officiel de graphiques est utile pour vérifier les valeurs par défaut actuelles avant d'écrire des modifications :

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

Si votre dépôt propose un graphique compatible plus récent lorsque vous suivez ce guide, consultez ses notes de version et ses valeurs avant de l'utiliser. La version du graphique et la version de l'image de l'application CODE sont des paramètres de version liés, mais il ne s'agit pas du même paramètre.

Étape 2 : Créez un espace de noms et protégez le mot de passe administrateur

Créez l'espace de noms et un secret Kubernetes pour les identifiants d'administrateur Collabora optionnels du graphique. Remplacez le mot de passe par défaut par un secret robuste, ou créez le secret via le gestionnaire de secrets de votre organisation ou le workflow de secrets GitOps. Ne commettez pas de mot de passe réel dans ce secret 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'

Le graphique permet de référencer un secret existant. L'activation de cette fonctionnalité évite d'inclure directement le mot de passe administrateur dans le fichier de valeurs Helm. Veillez à ce que ce secret soit accessible uniquement à l'espace de noms et aux utilisateurs ou comptes de service qui administrent ce déploiement.

Étape 3 : Configurer le nom d’hôte, l’hôte WOPI et l’entrée

Créez un fichier nommé collabora-values.yaml. Cet exemple suppose l'utilisation d'ingress-nginx, d'un secret TLS nommé office-example-com-tls, et de Nextcloud à l'emplacement https://cloud.example.com. Le groupe d'alias doit désigner l'hôte de l'application WOPI que Collabora est autorisé à contacter ; il ne s'agit pas du nom d'hôte public de 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'exemple documenté du graphique aliasgroupsautorise l'hôte WOPI et ces paramètres SSL lorsqu'un proxy inverse termine la connexion TLS. Dans cette configuration, le trafic externe office.example.comutilise HTTPS, tandis que le serveur d'entrée achemine le trafic vers Collabora via HTTP au sein du cluster. Si votre serveur d'entrée utilise le transfert TLS ou un protocole interne différent, ne copiez pas ces indicateurs SSL tels quels ; adaptez-les au chemin TLS réel et aux valeurs actuelles du graphique.

Vérifiez que le secret TLS existe dans l' collaboraespace de noms. Si vous utilisez un autre contrôleur d'entrée, remplacez la classe et les annotations par leurs équivalents documentés. Activez le trafic WebSocket et autorisez les connexions persistantes ; les valeurs par défaut varient selon le contrôleur.

Étape 4 : Générer et installer le graphique

Commencez par générer les manifestes pour détecter les erreurs YAML et vérifiez les paramètres Ingress, Service et Workload générés. Installez ensuite la version du graphique épinglée :

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

Surveillez les ressources dès leur mise en service :

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

Attendez que le pod soit prêt avant de connecter l'application WOPI. S'il reste en attente, vérifiez que le cluster dispose de suffisamment de ressources CPU et de mémoire planifiables et qu'aucun sélecteur de nœud, aucune contamination ou aucun quota de ressources n'empêche son placement. Le graphique laisse à l'opérateur le soin de choisir les demandes et les limites de ressources ; le fichier README de Collabora fournit des exemples de valeurs de ressources plus importantes pour les environnements de production, mais le dimensionnement réel dépend de la charge de travail liée à l'édition simultanée et au volume de documents.

Étape 5 : Connectez Nextcloud ou un autre hôte WOPI

Ouvrez les paramètres Office ou Collabora de votre application WOPI et saisissez l'URL du service externe https://office.example.com. Dans Nextcloud, le manuel d'administration explique comment configurer l'URL du serveur Collabora Online dans les paramètres d'administration d'Office. Vérifiez également la liste blanche des requêtes WOPI de Nextcloud si votre configuration restreint les hôtes autorisés à se connecter. L'adresse doit être accessible à la fois par les navigateurs des utilisateurs et par le serveur d'applications effectuant les requêtes WOPI.

Si la connexion échoue avec un message d'erreur « hôte WOPI non autorisé » ou similaire, comparez l'URL de l'hôte WOPI collabora.aliasgroups. Vérifiez le schéma, le nom d'hôte et le port, et ajoutez volontairement des noms d'hôtes alternatifs légitimes. Évitez les noms d'hôtes trop généraux, sauf si vous en comprenez les conséquences. Si vous utilisez plusieurs applications WOPI, respectez la structure de groupes d'alias documentée pour chaque hôte, plutôt que d'autoriser tous les domaines.

Quand faut-il passer à plus d'un seul module ?

Pour un test à petite échelle, une seule réplique avec la mise à l'échelle automatique désactivée évite la complexité du routage. Pour plusieurs répliques, le fichier README du graphique Collabora indique l'affinité NGINX en fonction de l' WOPISrcargument de requête. Ajoutez l'annotation documentée à l'entrée lors de l'utilisation d'ingress-nginx :

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

Cela dirige les requêtes concernant un même document vers le même pod backend, ce qui est essentiel pour l'édition collaborative et les accès au presse-papiers. Consultez la documentation pour connaître la version exacte de votre contrôleur d'entrée ; une annotation prise en charge par ingress-nginx n'est pas automatiquement valide pour HAProxy, Traefik ou une implémentation d'API Gateway. Après avoir activé davantage de réplicas ou la mise à l'échelle automatique, testez les modifications simultanées du même document et observez les journaux Collabora et les journaux d'accès à l'entrée. Le dimensionnement des ressources, le comportement des sessions et la haute disponibilité nécessitent une validation spécifique à la charge de travail.

Vérifier le déploiement de l'extérieur

1. Vérifiez que Kubernetes signale le pod comme étant prêt et que le service et l'entrée existent : kubectl get pods,svc,ingress -n collabora.
2. Vérifiez le point de terminaison de découverte public. Il devrait renvoyer du XML plutôt qu'une erreur de navigateur ou de proxy :

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

3. Ouvrez l'application WOPI et modifiez un document de test. Vérifiez que l'éditeur se charge, que les modifications sont enregistrées et que la réouverture du document affiche le contenu enregistré.
4. Si vous utilisez plusieurs répliques, ouvrez le même document dans deux sessions et vérifiez que les deux peuvent collaborer sans avoir à se reconnecter constamment. Cela permet d'identifier les problèmes d'affinité de session.
5. Consultez les journaux pour détecter les erreurs TLS, d'autorisation WOPI ou en amont :

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

   Si le graphique crée une charge de travail portant un nom différent, utilisez kubectl get deployments -n collaboraet remplacez le nom réel.

Une réponse positive à la requête de découverte confirme que le point de terminaison public diffuse les métadonnées Collabora ; elle ne prouve cependant pas que l’authentification WOPI ni l’enregistrement des documents fonctionnent. Le test de bout en bout des documents constitue la vérification finale.

Points de défaillance communs

• Si Ingress renvoie une erreur 404 ou 502, vérifiez le DNS, la classe Ingress, le secret TLS et les points de terminaison du service. Assurez-vous qu'Ingress peut atteindre le service Collabora sur le port de service indiqué dans le graphique.
• La découverte fonctionne, mais l'éditeur reste vide : examinez les erreurs de la console du navigateur et les journaux du proxy. Vérifiez les paramètres de terminaison HTTPS, la gestion des WebSockets et les délais d'expiration des requêtes.
• Hôte WOPI non autorisé : autorisez l’origine de l’application WOPI dansaliasgroups ; ne remplacez pas le nom d’hôte du serveur Office.
• Le pod redémarre ou est expulsé : examinez kubectl describe podles journaux du conteneur, puis définissez des demandes et des limites de ressources réalistes pour le cluster disponible.
• L'édition devient instable après l'ajout de répliques : vérifiez l'affinité basée sur WOPISrc et confirmez que le contrôleur préserve l'argument de requête lors du routage des requêtes.

Une fois le graphique installé, le point de terminaison de découverte accessible et un document ouvert et enregistré avec succès via l'application WOPI, le déploiement CODE principal fonctionne. Veillez à conserver la version du graphique et à répéter ces vérifications après chaque mise à jour, modification du point d'entrée ou changement d'échelle.

Références officielles

• Guide de déploiement et graphique Helm Kubernetes maintenu par Collabora
• Valeurs du graphique Collabora Helm
• Sorties des classements Collabora
• Guide d'utilisation de Collabora Online Development Edition (CODE)
• Manuel de configuration de Nextcloud Office
• documentation des annotations ingress-nginx
• Référence des commandes d'installation Helm