Comment configurer Collabora Online derrière Nginx

Que devrait faire un proxy inverse fonctionnel ?

Un déploiement Collabora Online fonctionnel derrière Nginx offre aux utilisateurs une adresse HTTPS publique pour l'éditeur, tout en maintenant le service Collabora sur un réseau privé. L'éditeur doit charger ses ressources de navigateur, détecter les fonctionnalités bureautiques, ouvrir un document via la plateforme de stockage connectée et maintenir sa connexion WebSocket active pendant l'édition. Une vérification syntaxique Nginx valide ne garantit pas à elle seule le bon fonctionnement de ces chemins.

Cet exemple suppose qu'un serveur Collabora autonome ou un conteneur CODE écoute sur le port 9980, que Nginx assure le service office.example.comet que la connexion TLS se termine au niveau de Nginx. Remplacez le nom d'hôte et le chemin du certificat par les vôtres. L'adresse du serveur d'arrière-plan 127.0.0.1:9980s'applique uniquement lorsque Nginx et Collabora partagent le même hôte et que le service est lié à l'interface de bouclage. Pour des conteneurs séparés, utilisez le nom du service Collabora sur un réseau Docker privé, tel que `/etc/collabora/collabora` http://collabora:9980.

Avant de modifier Nginx

Vérifiez que le nom DNS public pointe bien vers le proxy, que le certificat TLS couvre exactement ce nom et que Nginx peut accéder à Collabora via son adresse interne. Si vous utilisez Docker, connectez les deux services à un réseau défini par l'utilisateur et ne publiez pas le port Collabora. Si Nginx est exécuté sur l'hôte, configurez le port du conteneur pour qu'il soit accessible via l'interface de bouclage (boucle locale, .uk) 127.0.0.1:9980:9980. Votre pare-feu doit autoriser l'accès aux ports web publics que vous souhaitez utiliser, et non au port backend de Collabora.

Choisissez une configuration TLS. La configuration ci-dessous utilise TLS entre le navigateur et Nginx, puis HTTP simple via un routeur privé de confiance vers Collabora. Il s'agit d'une terminaison TLS. Si votre politique exige également un chiffrement entre le proxy et Collabora, utilisez HTTPS pour la connexion en amont et configurez Nginx pour qu'il fasse confiance au certificat du serveur. Ne modifiez pas uniquement le proxy_passprotocole : les paramètres TLS côté serveur doivent correspondre à ceux du serveur Collabora. Collabora documente les deux configurations de proxy dans son guide sur le proxy inverse Nginx et dans le manuel du SDK 25.04 .

Configurer les options TLS de Collabora compatibles avec les proxys

Pour la terminaison TLS, configurez le service Collabora coolwsdavec ssl.enable=falseles options appropriées ssl.termination=true. La manière de définir ces valeurs dépend de l'installation de Collabora : modifiez la coolwsd.xmlconfiguration fournie ou utilisez les options documentées pour votre package ou conteneur. Avec l'image Docker CODE, les déploiements transmettent généralement les options sous la formeextra_params ; consultez la documentation de l'image pour votre version et veillez à insérer correctement les guillemets dans Compose. Redémarrez ou recréez le service Collabora après avoir modifié sa configuration.

Ces paramètres indiquent à Collabora que la connexion externe est protégée par le proxy, même si la communication entre le proxy et le serveur dorsal utilise le protocole HTTP. Ils n'installent aucun certificat public, ne configurent pas le DNS et n'autorisent aucun serveur de stockage à utiliser Collabora. Configurez séparément la liste blanche des hôtes WOPI ou les paramètres d'intégration en fonction de votre plateforme de stockage.

Configurer Nginx pour rediriger les routes de l'éditeur

Nginx doit transmettre les ressources de découverte et de navigateur et préserver la mise à niveau WebSocket utilisée par l'édition interactive. Voici un exemple sur un seul serveur. Définissez le paramètre mapdans le httpcontexte Nginx, par exemple dans le fichier principal nginx.conf, et non à l'intérieur de l'hôte virtuel :

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Placez le bloc serveur dans la configuration du site fournie par Nginx. Ceci suppose que les certificats TLS sont déjà installés et que la connexion proxy-Collabora est de type HTTP :

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;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    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 $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

Les chemins commençant /coolpar ` /lool/ etc / websocket ...UpgradeConnection

Pour utiliser HTTPS sur le serveur en amont, modifiez les URL du serveur https://et configurez correctement la vérification du certificat en amont et la chaîne de certificats de confiance de Nginx. Évitez de désactiver la vérification du certificat comme solution de contournement permanente. Si Nginx se trouve dans un autre conteneur, remplacez l'adresse de bouclage par le nom du service Collabora ; 127.0.0.1à l'intérieur du conteneur proxy, pointez vers ce dernier.

Lorsque vous utilisez un préfixe d'URI au /collabora/lieu d'un nom d'hôte dédié, la configuration et les URL de découverte générées par Collabora nécessitent une gestion supplémentaire des chemins. Privilégiez un nom d'hôte dédié, sauf si votre plateforme prend explicitement en charge le déploiement par sous-chemin. Un bloc serveur qui redirige les requêtes à la racine ne permet pas automatiquement aux URL générées par la découverte de fonctionner avec un préfixe.

Rechargez et vérifiez chaque couche

Validez la configuration Nginx avant de l'appliquer, puis rechargez le service :

sudo nginx -t
sudo systemctl reload nginx

Si la vérification de syntaxe échoue, corrigez d'abord le fichier et la ligne signalés. Un rechargement réussi confirme que Nginx a accepté la configuration, et non que le serveur, le certificat ou le chemin WebSocket fonctionnent. Vérifiez séparément la validité du DNS et du certificat, puis interrogez les deux points de terminaison Collabora via le nom d'hôte public :

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

Le point de terminaison de découverte doit renvoyer du XML et non une page 404 Nginx ou une page de connexion ; les capacités doivent renvoyer une réponse de Collabora. Vérifiez les URL de l'éditeur du XML de découverte : elles doivent utiliser le nom d'hôte HTTPS public et des chemins accessibles, et non un nom de conteneur ou une adresse interne. L'image ci-dessous illustre les types de réponses attendues ; les valeurs affichées sont données à titre d'exemple et ne proviennent pas d'un serveur en production.

Enfin, configurez votre plateforme de documents pour https://office.example.comqu'elle utilise Collabora comme serveur et ouvrez un document de test. Un bon indicateur de réussite est le chargement et la réactivité de l'éditeur pendant la saisie, l'enregistrement et la réouverture du document. Dans les outils de développement du navigateur, la requête WebSocket /cool/devrait aboutir ; le statut HTTP 101 Switching Protocolscorrespond au résultat attendu de la négociation WebSocket. Ne considérez pas un exemple de statut affiché comme preuve que votre serveur a réussi ce test.

Analyser les échecs à partir de leurs symptômes

• Erreur 502 Bad Gateway : Nginx ne parvient pas à joindre le serveur en amont. Vérifiez le nom du service, le port, le réseau du conteneur, le listener et les journaux. Si les conteneurs sont distincts, n'utilisez pas l'adresse de bouclage du conteneur proxy.
• Erreur 404 lors de la découverte ou de l'utilisation des ressources du navigateur : vérifiez que la requête atteint bien l'hôte virtuel et que la redirection s'effectue correctement, sans réécriture d'URI involontaire. Testez l'URL publique, et pas seulement l'URL du serveur.
• L'éditeur se charge mais se bloque ou se déconnecte : examinez la /cool/.../wsrequête. Des en-têtes de mise à niveau manquants, une connexion HTTP/1.0 en amont, un délai d'attente trop court ou un proxy qui met la connexion en mémoire tampon peuvent interrompre l'édition. Vérifiez que la requête est bien mise à niveau et reste ouverte pendant que le document est actif.
• Hôte WOPI non autorisé : le proxy peut fonctionner correctement tandis que Collabora rejette la plateforme de stockage. Vérifiez que le nom d'hôte WOPI réel correspond bien à la liste blanche de Collabora et à la configuration du connecteur de la plateforme. Ne résolvez pas ce problème en exposant le serveur à Internet.
• Avertissement relatif au contenu mixte ou au certificat : assurez-vous que l’URL de l’éditeur public et les URL détectées utilisent le protocole HTTPS et que le certificat correspond au nom d’hôte. Si la terminaison TLS est gérée par Nginx, vérifiez également le paramètre de terminaison de Collabora.

Une fois ces vérifications effectuées, conservez le backend Collabora privé et surveillez les journaux Nginx et Collabora lors de la mise à jour de l'un ou l'autre composant. Cet exemple à serveur unique ne configure ni la haute disponibilité, ni l'équilibrage de charge, ni l'affinité de session par document. Pour plusieurs réplicas Collabora, suivez les instructions de déploiement du contrôleur ou de l'équilibreur de charge Collabora concerné et testez l'affinité des documents avant de router le trafic de production.

Sources et notes de version

Les détails de configuration ont été vérifiés le 6 octobre 2026 à l'aide de la documentation relative aux proxys de Collabora, du manuel du SDK 25.04 et des références WebSocket et du module proxy de Nginx. Les options de package et de conteneur peuvent varier selon la version de Collabora ; veuillez vérifier les noms des paramètres pour la version que vous utilisez avant de les appliquer. Cet article ne présuppose aucune plateforme de stockage particulière et ne constitue pas une preuve de déploiement en production.