Comment configurer la terminaison SSL pour un conteneur Collabora CODE

La terminaison SSL est parfaitement adaptée à un conteneur Collabora Online Development Edition (CODE) lorsque vous souhaitez un point de terminaison HTTPS public tout en confiant la gestion des certificats à un proxy inverse tel que Nginx. Dans cette architecture, le navigateur se connecte à Nginx via HTTPS, Nginx déchiffre le trafic et Collabora reçoit du trafic HTTP non chiffré sur son port interne. L'objectif de qualité ne se limite pas au simple chargement de la page. Un déploiement réussi doit comporter un certificat public valide, un point de terminaison de découverte WOPI accessible, des mises à jour WebSocket fonctionnelles et une session d'édition de document réelle et stable.

La documentation de Collabora sur les proxys décrit ce modèle de déchargement SSL comme une connexion HTTP uniquement entre le proxy et Collabora, ssl.enable=falsecôté ssl.termination=trueCollabora. Consultez les paramètres du proxy inverse de Collabora Online . Les exemples ci-dessous utilisent Nginx et Docker Compose, mais le même résultat peut être obtenu avec d'autres proxys inverses, à condition qu'ils conservent le comportement requis pour l'hôte et les WebSockets.

Ce qu'une bonne configuration de terminaison SSL devrait permettre

Étape 1 : Confirmez les limites du réseau avant de modifier Collabora

Déterminez où se termine la connexion TLS et quels hôtes peuvent accéder au port 9980. Si Nginx est installé sur la même machine que Docker, limiter le port publié à une adresse IP publique 127.0.0.1est un moyen simple d'empêcher l'accès direct à Internet. La documentation Docker indique que publier un port sur une adresse IP publique 127.0.0.1le maintient local à l'hôte ; consultez la documentation de Docker sur la publication des ports .

Si Nginx s'exécute dans un autre conteneur, un réseau Docker privé partagé est généralement plus sûr que de publier le port 9980 publiquement. Le principe reste le même : les clients doivent utiliser le nom d'hôte du proxy inverse HTTPS, et non directement le conteneur Collabora.

Étape 2 : Exécuter le code en mode de terminaison SSL

Pour la terminaison TLS côté proxy, Collabora doit savoir que le protocole côté client d'origine est HTTPS, même si sa connexion en amont immédiate est HTTP. Les paramètres documentés sont les suivants :

--o:ssl.enable=false --o:ssl.termination=true

Voici un exemple minimal de Compose :

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

Remplacez-la YOUR_TESTED_TAGpar une version que vous avez validée au lieu de supposer automatiquement qu'elle latestest sûre pour un déploiement en production. Configurez également les paramètres d'hôte ou d'alias WOPI appropriés pour votre intégration ; ces valeurs dépendent du type d'hôte ou d'alias que vous utilisez : Nextcloud, ownCloud, un autre hôte WOPI ou une intégration personnalisée.

Après avoir démarré le conteneur, vérifiez qu'il est en cours d'exécution et que le mappage des ports correspond à la limite prévue :

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

Note de version pour les déploiements 26.04

Ne considérez pas les deux options SSL comme la seule variable lors du dépannage d'une image 26.04 actuelle. Mi-2026, Collabora a identifié des régressions liées à l'image Docker sans distribution et aux configurations sans SSL. Un problème officiel sur GitHub documente une régression au démarrage de la version 26.04, et la communauté Collabora a signalé que le comportement de terminaison SSL affecté fonctionnait à nouveau dans une image 26.04.2.4.1 ultérieure. Consultez le problème n° 16019 sur CollaboraOnline/online si une configuration de terminaison qui fonctionnait auparavant cesse de fonctionner immédiatement après une mise à niveau de l'image.

C’est aussi une raison de vérifier et de tester la version de votre image. Une erreur de configuration et une régression d’image de conteneur peuvent se ressembler du point de vue de Nginx : les deux peuvent se manifester par une réponse 502 ou une connexion amont défaillante.

Étape 3 : Configurer Nginx pour terminer les connexions TLS et faire office de proxy pour les chemins Collabora

Nginx nécessite un certificat valide pour le nom d'hôte Collabora et doit rediriger les points de terminaison HTTP de Collabora ainsi que le trafic WebSocket. Le guide du proxy Collabora indique les emplacements dédiés aux ressources du navigateur, à la découverte, aux fonctionnalités, aux principales connexions WebSocket, aux chemins de téléchargement/téléversement et à l'interface WebSocket d'administration. La configuration suivante respecte cette structure tout en ajoutant les en-têtes de redirection courants :

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

Les en-têtes WebSocket ne sont pas purement esthétiques. La documentation officielle de Nginx explique que les Upgradeen -têtes `WebSocket` et `WebSocketProxy` Connectionsont des en-têtes de saut par saut et doivent être explicitement fournis pour les WebSockets utilisant un proxy inverse. Voir la documentation sur le proxy WebSocket avec Nginx . La documentation du module proxy standard `ngx_http_proxy_module` couvre également les en-têtes ` WebSocket` proxy_set_header, ` WebSocketProxy`proxy_pass et proxy_read_timeout` WebSocketProxy` .

Étape 4 : Valider Nginx avant le rechargement

Testez la configuration Nginx avant de remplacer une configuration fonctionnelle :

sudo nginx -t

Ne rechargez que si le test de syntaxe réussit :

sudo systemctl reload nginx

Vérifiez ensuite que Nginx peut accéder au serveur Collabora local. Sur une configuration à hôte unique, une vérification utile consiste à :

curl -I http://127.0.0.1:9980/hosting/discovery

Les en-têtes de réponse exacts peuvent varier selon la version de Collabora, mais l'essentiel est que la connexion TCP réussisse et que le point de terminaison réponde au lieu d'expirer ou de refuser la connexion. Si cette requête locale échoue, la modification des paramètres TLS publics ne résoudra pas le problème sous-jacent lié au conteneur ou au réseau.

Étape 5 : Vérifier le point de terminaison HTTPS public

Depuis un client qui résout le nom d'hôte public, demandez le point de terminaison de découverte via Nginx :

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

Une requête du navigateur https://office.example.com/hosting/discoverydevrait renvoyer du XML. Ce contrôle fonctionnel est plus fiable que l'utilisation de l'URL racine, car le comportement de la page racine ne correspond pas au contrat WOPI principal et peut varier selon la version.

Vérifiez également la chaîne de certificats avec votre navigateur ou un outil de diagnostic TLS. Le nom d'hôte doit correspondre au certificat, la chaîne doit être approuvée et aucun avertissement de contenu mixte ne doit apparaître, Collabora ne devant pas diffuser d'URL HTTP simples au navigateur.

Étape 6 : Tester un document réel et le WebSocket

La réussite de la découverte est nécessaire, mais non suffisante. Ouvrez un document depuis votre serveur WOPI et laissez-le ouvert suffisamment longtemps pour tester la session en direct. Dans les outils de développement de votre navigateur, la requête WebSocket Collabora doit aboutir sans problème, sans tentatives de reconnexion répétées ni erreur 400/502. Une session fonctionnelle vous permettra de saisir du texte, d'enregistrer et de rouvrir le document.

Si l'interface de l'éditeur se charge mais que le document ne s'ouvre pas peu après, vérifiez en priorité le chemin WebSocket, le délai d'expiration du proxy, la liste blanche WOPI et le comportement de l'en-tête d'hôte. Si les journaux Nginx indiquent une erreur de connexion en amont avant l'établissement de toute connexion WebSocket, examinez d'abord le listener et la version de l'image de CODE.

Comment diagnostiquer les modes de défaillance courants

502 Mauvaise passerelle

Une erreur 502 signifie généralement que Nginx n'a pas pu obtenir de réponse valide du serveur en amont configuré. Vérifiez que CODE écoute bien sur le port 9980 et que vous utilisez le protocole en amont approprié. Dans la configuration prévue pour la terminaison SSL, le proxy vers CODE utilise HTTP. Si une régression de l'image système empêche CODE de continuer à utiliser HTTPS en interne malgré vos paramètres, les journaux et un curltest direct révéleront l'incompatibilité. Ne passez pas définitivement à un serveur en amont HTTPS simplement pour masquer une régression de configuration inexpliquée ; vérifiez d'abord le comportement exact de l'image CODE que vous utilisez.

La découverte fonctionne, mais les documents ne s'ouvrent pas.

Cela indique souvent un problème de redirection WebSocket ou d'autorisation WOPI plutôt que de protocole TLS. Vérifiez la /cool/.../wsroute, les en-têtes de mise à niveau et l'hôte autorisé comme source WOPI. Collabora peut être parfaitement accessible via HTTPS tout en refusant ou en faisant échouer une session d'édition.

URL à contenu mixte ou à schéma incorrect

Si un navigateur reçoit une page HTTPS faisant référence à des ressources HTTP, vérifiez ssl.termination=truel'en-tête de schéma de redirection et le nom du serveur. Le serveur public doit s'identifier systématiquement comme HTTPS, même si le serveur privé utilise HTTP.

Le conteneur signale un état instable même si la modification fonctionne

Les versions 26.04 récentes ont introduit un comportement de vérification d'intégrité qui a évolué lors de la transition vers une image sans distribution. Collabora a identifié un cas où la sonde ne respectait pas la configuration d'un serveur HTTP derrière une terminaison TLS. Si les tests fonctionnels réussissent mais que l'état de Docker est anormalement bas, consultez l'historique des problèmes spécifiques à cette version avant de repenser un proxy fonctionnel. Voir le problème n° 16032 sur CollaboraOnline/online .

Quand utiliser un design différent

La terminaison SSL côté proxy est appropriée lorsque le proxy inverse et Collabora communiquent via une interface locale de confiance ou un réseau privé isolé. Si le trafic entre Nginx et CODE transite par un réseau non sécurisé, l'utilisation du protocole HTTP simple sur le saut interne peut ne pas répondre à vos exigences de sécurité. Dans ce cas, utilisez également TLS pour le serveur, ou placez les deux services sur un réseau protégé où l'interception ne représente pas une menace réaliste.

De même, si vous utilisez déjà un serveur d'entrée géré par la plateforme qui prend en charge correctement les certificats, le routage et les WebSockets, l'ajout d'une seconde couche Nginx uniquement pour Collabora présente peu d'intérêt. L'architecture optimale est celle qui offre une limite TLS unique et observable, sans sauts inutiles.

Liste de contrôle de validation finale

• Le nom d'hôte Collabora est résolu en proxy inverse.
• Le port 443 présente un certificat de confiance pour ce nom d'hôte.
• Le code n'est pas inutilement exposé à l'Internet public sur le port 9980.
• ssl.enable=falseet ssl.termination=truesont appliquées à la conception du backend HTTP.
• Nginx peut accéder à CODE via son adresse privée.
• /hosting/discoveryrépond via l'URL HTTPS publique.
• La /cool/.../wsmise à niveau WebSocket a réussi.
• Un véritable document s'ouvre, se modifie, s'enregistre et se rouvre.
• Vous avez épinglé et testé la version exacte de l'image CODE que vous prévoyez de déployer.

Si tous ces contrôles sont réussis, la terminaison SSL fonctionne correctement : le trafic externe est protégé par HTTPS, Collabora considère la connexion publique comme sécurisée et le chemin d’édition reste fonctionnel. En cas d’échec d’un contrôle, il convient de résoudre le problème à ce niveau plutôt que de modifier plusieurs éléments de la pile simultanément.