Comment configurer HTTPS et un certificat SSL pour ONLYOFFICE Docker

Pour sécuriser ONLYOFFICE Docs via HTTPS dans un conteneur Docker, utilisez un certificat correspondant au nom d'hôte public, rendez-le disponible dans le conteneur et publiez le port HTTPS de ce dernier. HTTPS est une connexion web chiffrée ; un certificat TLS permet aux navigateurs de vérifier qu'ils ont bien atteint le serveur attendu. Ce guide utilise un certificat et une clé privée que vous avez déjà obtenus auprès d'une autorité de certification (AC) de confiance. Si vous utilisez un proxy inverse, suivez la procédure décrite ci-dessous, car le proxy peut gérer le protocole HTTPS.

Quelle configuration HTTPS convient à votre déploiement ?

ONLYOFFICE Docs peut servir des requêtes HTTPS directement depuis son conteneur Docker, ou un proxy inverse comme NGINX ou Traefik peut accepter les requêtes HTTPS et les rediriger vers Docs. L'utilisation directe de TLS est une solution simple pour un serveur autonome dont les ports publics 80 et 443 sont disponibles. Un proxy inverse est souvent plus simple lorsqu'un autre service web utilise déjà ces ports ou que plusieurs sites partagent un même serveur. Évitez de configurer les deux couches sans discernement : déterminez quel composant gère la terminaison TLS et documentez si la connexion entre le proxy et le conteneur est de type HTTP ou HTTPS.

Ce guide explique comment configurer une connexion HTTPS directe avec un certificat émis par une autorité de certification. ONLYOFFICE propose également une option Let's Encrypt automatiqueLETS_ENCRYPT_DOMAIN ; LETS_ENCRYPT_MAILcelle-ci nécessite que les ports 80 et 443 soient accessibles et non utilisés par un proxy. Un certificat auto-signé est utile pour un réseau de test privé, mais les navigateurs publics et les services de stockage connectés ne lui feront pas automatiquement confiance.

Que devez-vous préparer en premier ?

• Un hôte Linux avec Docker Engine et le plugin Docker Compose installés.
• Un enregistrement DNS de type A pour le nom d'hôte, par exemple `example.com` docs.example.com, pointant vers l'adresse IPv4 publique de l'hôte. Ajoutez un enregistrement AAAA uniquement si IPv6 est configuré et accessible.
• Règles de pare-feu entrant et de pare-feu cloud autorisant le port TCP 443. Si vous demandez ou renouvelez des certificats avec validation HTTP, le port TCP 80 peut également être requis.
• Une chaîne de certificats correspondant au nom d'hôte exact et à sa clé privée associée. Les autorités de certification fournissent généralement un fichier de chaîne complète et un fichier de clé privée.
• Un répertoire hôte persistant pour le volume de données ONLYOFFICE et un jeton JWT robuste. Le JWT (JSON Web Token) est un secret partagé utilisé pour authentifier les requêtes entre Docs et une application intégrée.

Étape 1 : Placez le certificat et la clé privée sur l’hôte

Dans cet exemple, l'hôte conserve les données persistantes sous /srv/onlyoffice/data. Remplacez le nom d'hôte et les chemins d'accès par les vôtres. Stockez la chaîne complète du certificat sous tls.crtet la clé privée correspondante sous tls.keydans un certssous-répertoire :

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

Veillez à ce que la clé privée ne soit accessible qu'au compte ou au service qui en a besoin. Ne la collez pas dans un fichier Compose, un rapport de problème ou un dépôt public. Si Docker ne peut pas lire la clé en raison de problèmes de propriété ou d'autorisations, limitez l'accès à la durée d'exécution du conteneur plutôt que de rendre la clé accessible à tous.

Vérifiez les dates et les noms d'hôte du certificat avant de démarrer le service :

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

La liste des noms alternatifs du sujet (SAN) doit inclure le nom d'hôte exact que les utilisateurs visiteront. Vous pouvez comparer les clés publiques dérivées du certificat et la clé privée ; les deux hachages doivent correspondre.

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

Étape 2 : Configurer le service Docker Compose

La documentation Docker d'ONLYOFFICE place les certificats sous `/etc/certs` /var/www/onlyoffice/Data/certs. Sa liste actuelle de variables d'environnement indique que les noms de fichiers de certificat par défaut sont `/etc/certs` et `/etc tls.crt/ tls.keycerts`, tandis que les exemples d'installation utilisent également `/etc/certs` onlyoffice.crtet onlyoffice.key`/etc/certs`. Définir explicitement les chemins permet d'éviter de dépendre d'une convention de nommage de fichiers. Le répertoire hôte est monté dans le répertoire de données du conteneur correspondant, et le port 443 est publié comme port hôte 443.

Créez un compose.yamlfichier similaire à celui-ci, en remplaçant la valeur JWT d'exemple par un secret généré pour votre installation. L'image ci-dessous correspond à une version d'exemple ; consultez la liste des images officielles et utilisez une version que vous souhaitez maintenir.

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

Générez un secret robuste et openssl rand -hex 32placez-le dans le fichier d'environnement ou la configuration Compose avec les permissions appropriées. Si une autre application s'intègre à Docs, configurez-la avec le même secret JWT et l'adresse HTTPS publique. S'il s'agit d'une installation existante, conservez ses volumes, réseaux, autres variables d'environnement et paramètres d'intégration lors de la modification du fichier Compose existant ; ne remplacez pas une définition de service fonctionnelle par cet exemple minimal.

Démarrez ou recréez le service à partir du répertoire contenant le fichier Compose :

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

Étape 3 : Tester le protocole HTTPS et le certificat

Ouvrez https://docs.example.comle fichier dans un navigateur en remplaçant le nom d'hôte par le vôtre. Vérifiez que le navigateur affiche une connexion sécurisée et ne signale aucune erreur de nom, de certificat expiré ou d'émetteur non approuvé. Assurez-vous que la page d'accueil d'ONLYOFFICE Docs se charge correctement. Si Docs est connecté à Nextcloud, ownCloud ou une autre plateforme, testez également l'ouverture et l'enregistrement d'un document ; le verrouillage du navigateur ne suffit pas à prouver le bon fonctionnement des requêtes de rappel de l'intégration ni de la configuration JWT.

Depuis un terminal, demandez au serveur son certificat TLS et testez la réponse HTTPS :

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

Cette -servernameoption envoie le nom d'hôte via l'indication du nom de serveur (SNI), ce qui permet au serveur de sélectionner le certificat approprié lorsqu'une adresse IP est partagée par plusieurs noms d'hôte. La date, l'émetteur et le SAN du certificat doivent correspondre à ceux du certificat installé. Vérifiez docker compose logssi le navigateur ne parvient pas à se connecter ou si le conteneur redémarre de manière répétée.

Que se passe-t-il si un proxy inverse gère déjà le protocole HTTPS ?

Si NGINX, Traefik, Caddy ou une passerelle d'hébergement possède déjà les ports publics 80 et 443, il est préférable d'installer le certificat public sur ce proxy. Dans cette configuration, publiez le conteneur Docs uniquement sur un réseau Docker privé ou configurez son port HTTP en boucle locale, puis configurez le proxy pour qu'il transfère les requêtes nécessaires et le trafic WebSocket. Définissez l'adresse ONLYOFFICE de l'application d'intégration sur l' https://URL publique. Suivez les instructions actuelles du proxy et d'ONLYOFFICE concernant les en-têtes transférés et le protocole TLS en amont ; ne publiez pas le port 443 du conteneur sur le même port hôte que celui utilisé par le proxy.

Choisissez ce modèle lorsqu'un proxy achemine le trafic de plusieurs services. Utilisez la configuration de conteneur direct décrite ci-dessus lorsque Docs doit gérer le point de terminaison HTTPS public et que les ports nécessaires sont disponibles. Si le proxy se connecte au conteneur via HTTP, cette connexion interne n'est pas chiffrée ; assurez-vous qu'elle se trouve sur un réseau privé de confiance ou configurez le protocole TLS en amont si vos exigences de sécurité l'imposent.

Problèmes courants et comment les résoudre

• Le navigateur indique que le certificat est invalide. Vérifiez le nom d'hôte SAN, la date d'expiration du certificat, la chaîne complète et assurez-vous que le DNS pointe bien vers l'hôte prévu. Un certificat pour le domaine nu ne couvre pas automatiquement un sous-domaine.
• Le conteneur signale un certificat ou une clé manquante. Vérifiez le chemin source de l'hôte, la destination du montage de liaison, les noms de fichiers exacts et les deux SSL_..._PATHvaleurs. La syntaxe Docker --mountexige que le chemin source existe ; les montages de liaison Compose doivent également pointer vers le répertoire existant souhaité.
• Le port 443 est déjà utilisé. Arrêtez le service en conflit, utilisez un proxy inverse ou choisissez un autre port public et assurez-vous que l'URL et le pare-feu le confirment. Si un proxy est utilisé, il devrait généralement être propriétaire du port public 443.
• Le protocole HTTPS fonctionne, mais l'édition de documents échoue. Vérifiez l'URL d'intégration, le jeton JWT sur les deux services, les règles de redirection du proxy et assurez-vous que Docs peut accéder à la plateforme de stockage. Effectuez un véritable cycle d'ouverture et d'enregistrement.
• Le certificat a été renouvelé, mais le site utilise toujours l'ancien. Vérifiez que le renouvellement a bien mis à jour le fichier monté sur l'hôte et qu'ONLYOFFICE l'a rechargé. Si nécessaire, redémarrez le service après le renouvellement, par exemple avec un hook de déploiement Certbot exécuté docker compose restart documentserverdepuis le répertoire du projet Compose. Testez le renouvellement avec l'option de simulation de Certbot avant de l'automatiser.

Maintenez le certificat à jour.

La configuration HTTPS n'est pas terminée tant que le renouvellement n'est pas planifié. Notez qui émet et renouvelle le certificat, où est stockée la clé privée, quel processus copie les fichiers renouvelés dans le répertoire monté et comment le service les recharge. Exécutez le test à blanc du client de renouvellement, surveillez l'expiration du certificat et vérifiez le point de terminaison public après chaque renouvellement. Si vous utilisez les variables Let's Encrypt intégrées à ONLYOFFICE au lieu d'un certificat géré par l'hôte, suivez les instructions Docker actuelles pour cette méthode et vérifiez son comportement de renouvellement pour l'image et le déploiement exacts que vous utilisez.

Pour plus d'informations, consultez le guide d'installation Docker et HTTPS de ONLYOFFICE Docs , la documentation sur le montage de volumes Docker , la documentation Docker Compose , les étiquettes d'images Docker officielles de ONLYOFFICE et les instructions officielles de Certbot . Les étiquettes disponibles et les détails d'interface peuvent changer ; vérifiez-les lors de la préparation d'un nouveau déploiement.