Configurar HTTPS para ONLYOFFICE Docs en Docker

Para una conexión directa a ONLYOFFICE Docs, publique el puerto 443 del contenedor, guarde los archivos de certificado en el directorio de datos montado y configure el contenedor para que apunte a dichos archivos. Si un proxy inverso ya proporciona HTTPS, mantenga TLS en ese proxy y reenvíe el host y el protocolo originales a ONLYOFFICE en lugar de habilitar un segundo punto final TLS de forma predeterminada.

Por ejemplo, si el nombre de host público es docs.example.com, primero determine si apunta directamente al servidor de documentos o a un proxy. Utilice únicamente la configuración que coincida a continuación.

1. Decide dónde termina HTTPS.

TLS finaliza donde se descifra HTTPS: ya sea en el contenedor de ONLYOFFICE o en un proxy inverso. Elija el componente que recibe la conexión pública.

• Acceso directo: los clientes se conectan https://docs.example.comal puerto 443 del host, que está asignado al puerto 443 del contenedor. El contenedor del servidor de documentos necesita un certificado y su clave privada correspondiente.
• Acceso mediante proxy: los clientes se conectan al proxy a través de HTTPS; el proxy reenvía el tráfico al servidor de documentos a través de la red interna. En esta configuración, el certificado normalmente reside en el proxy. La guía de proxy de ONLYOFFICE exige el uso de los X-Forwarded-Protoencabezados y X-Forwarded-Hostpara que la aplicación pueda identificar el esquema de solicitud pública y el nombre de host.

El mapeo de puertos 443:443no crea HTTPS; solo mapea puertos. Para el acceso directo, el contenedor también debe leer el certificado y la clave. Si el proxy es el propietario de la URL pública, utilice las instrucciones oficiales de proxy inverso de ONLYOFFICE .

2. Configurar HTTPS directo en Docker Compose

Utilice esta ruta cuando el contenedor sirva HTTPS directamente. Para el acceso público, utilice un certificado de confianza para el nombre de host público. Un certificado autofirmado puede cifrar el tráfico, pero los clientes mostrarán una advertencia sobre la identidad a menos que estén configurados para confiar en él.

ONLYOFFICE Docs almacena los certificados en la siguiente ruta /var/www/onlyoffice/Data/certspor defecto, y su configuración actual de Docker los incluye tls.crtcomo tls.keyrutas predeterminadas para el certificado y la clave. Los ejemplos de la documentación no siempre han utilizado nombres de archivo idénticos, por lo que este ejemplo establece ambas rutas explícitamente.

services:
  documentserver:
    # Keep your existing image, environment, networks, and other settings.
    ports:
      - "443:443"
    volumes:
      - ./documentserver-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

Este es un extracto, no una definición de servicio de reemplazo. Mantenga la imagen, JWT, red y configuración de volumen existentes. En relación con el archivo Compose, coloque el certificado en ./documentserver-data/certs/tls.crty su clave correspondiente en ./documentserver-data/certs/tls.key. Incluya la cadena de certificados proporcionada por su proveedor y asegúrese de que el certificado cubra docs.example.com.

El montaje de enlace mantiene los archivos fuera de un contenedor reemplazable. Restrinja el acceso a la clave privada y asegúrese de que el contenedor pueda leerla; de lo contrario, HTTPS podría fallar al iniciarse. Nunca comparta la clave en una solicitud de soporte.

3. Aplicar el cambio sin reemplazar accidentalmente la implementación.

1. Realice una copia de seguridad del archivo Compose y del directorio del certificado, y luego confirme que el certificado y la clave coinciden con el nombre de host público.
2. Realice los cambios de puerto, volumen y ruta en el servicio existente. No inicie un segundo contenedor con el mismo puerto de host ni descarte los volúmenes existentes para aplicar TLS.
3. Recrea el servicio si cambiaste sus puertos, puntos de montaje o entorno. Con Compose, ejecuta docker compose up -d documentserverdesde el directorio que contiene el archivo Compose, sustituyendo el nombre real de tu servicio. Si solo reemplazaste los archivos de certificado en un directorio ya montado, reinicia el contenedor existente para que el servidor vuelva a cargar los archivos: docker restart <container_name>.
4. Compruebe los registros de inicio si HTTPS no se abre: docker logs <container_name>Busque errores de archivos faltantes, permisos o certificados/claves antes de cambiar configuraciones no relacionadas.

Reiniciar el servicio no permite añadir un punto de montaje ni modificar los puertos publicados; para realizar estas modificaciones, es necesario recrearlo. Reemplazar archivos en un punto de montaje persistente existente no requiere modificar Compose.

4. Mantenga TLS en un proxy inverso cuando ya esté dando servicio al dominio.

Si un proxy inverso ya está en funcionamiento https://docs.example.com, conserve su clave privada en el proxy. Reenvíe el tráfico a través de una red controlada y configure el parámetro X-Forwarded-Proto: httpsplus X-Forwarded-Hostcon el nombre de host público. Utilice el ejemplo oficial de su software de proxy.

El candado del navegador protege la conexión entre el cliente y el proxy, no necesariamente todos los saltos internos. HTTP en una red Docker controlada puede ser adecuado para algunas implementaciones; proteja el salto entre el proxy y el contenedor si atraviesa una red no confiable.

Otra limitación: cambiar el certificado TLS no soluciona un JWT no válido, un puerto de firewall bloqueado ni una dirección de servidor de documentos pública incorrecta en la configuración de integración. Si el certificado es válido, pero la carga o edición de documentos sigue fallando, revise los registros de la aplicación y del proxy correspondientes en lugar de regenerar los certificados repetidamente.

Verificar el resultado

Desde un cliente con acceso al servicio público, abra https://docs.example.come inspeccione los detalles del certificado del navegador. Confirme que el nombre de host coincide, que el certificado está vigente y que el navegador no informa de un emisor no confiable ni de una discrepancia en el nombre. También puede inspeccionar el protocolo de enlace TLS desde una terminal curl -Iv https://docs.example.com; revise el certificado y la salida de la conexión en lugar de confiar únicamente en si se carga la página.

Finalmente, abre un documento de la aplicación de integración. La verificación del navegador confirma el punto final público, no todas las configuraciones de integración ni las rutas internas. Si hay advertencias de certificado, vuelve a comprobar el nombre de host, la cadena, las rutas, los permisos y la terminación TLS. Si HTTPS se verifica pero la edición falla, revisa los registros y la configuración de autenticación o enrutamiento.

Para obtener más información sobre las rutas de Docker compatibles, las variables de certificado y las opciones integradas de Let's Encrypt, consulte la documentación de instalación de Docker y HTTPS de ONLYOFFICE . El comando exacto para actualizar una implementación existente depende de cómo se creó originalmente; conserve los volúmenes y la configuración de integración actuales de dicha implementación al aplicar los cambios TLS pertinentes.