Cómo configurar HTTPS y un certificado SSL para ONLYOFFICE Docker

Para proteger ONLYOFFICE Docs con HTTPS en Docker, utilice un certificado que coincida con el nombre de host público, hágalo accesible dentro del contenedor y publique el puerto HTTPS del contenedor. HTTPS es la conexión web cifrada; un certificado TLS ayuda a los navegadores a verificar que han llegado al servidor esperado. Esta guía utiliza un certificado y una clave privada que ya ha obtenido de una autoridad de certificación (CA) de confianza. Si utiliza un proxy inverso, siga la opción que se describe a continuación, ya que el proxy podría gestionar HTTPS.

¿Qué configuración HTTPS se ajusta mejor a su implementación?

ONLYOFFICE Docs puede servir HTTPS directamente desde su contenedor Docker, o bien un proxy inverso como NGINX o Traefik puede aceptar HTTPS y reenviar las solicitudes a Docs. El TLS directo es una opción sencilla para un servidor independiente cuyos puertos públicos 80 y 443 estén disponibles. Un proxy inverso suele ser más simple cuando otro servicio web ya utiliza esos puertos o varios sitios comparten un mismo servidor. Evite configurar ambas capas a ciegas: decida qué componente finaliza TLS y documente si la conexión entre el proxy y el contenedor es HTTP o HTTPS.

Este tutorial configura HTTPS directo con un certificado emitido por una CA. ONLYOFFICE también documenta una opción de Let's Encrypt automática LETS_ENCRYPT_DOMAIN; LETS_ENCRYPT_MAILrequiere que los puertos 80 y 443 estén accesibles y no estén ocupados por un proxy. Un certificado autofirmado es útil para una red de prueba privada, pero los navegadores públicos y los servicios de almacenamiento conectados no lo aceptarán automáticamente.

¿Qué debes preparar primero?

• Un host Linux con Docker Engine y el complemento Docker Compose instalados.
• Un registro DNS A para el nombre de host, como docs.example.com, que apunte a la dirección IPv4 pública del host. Añada un registro AAAA solo si IPv6 está configurado y es accesible.
• Reglas de firewall de entrada y de firewall en la nube que permiten el puerto TCP 443. Si solicita o renueva certificados con validación HTTP, también puede ser necesario el puerto TCP 80.
• Una cadena de certificados para el nombre de host exacto y su clave privada correspondiente. Las autoridades de certificación suelen proporcionar un archivo de cadena completa y un archivo de clave privada.
• Un directorio persistente para el volumen de datos de ONLYOFFICE y un secreto JWT seguro. JWT (JSON Web Token) es un secreto compartido que se utiliza para autenticar las solicitudes entre Docs y una aplicación de integración.

Paso 1: Coloque el certificado y la clave privada en el host.

Para este ejemplo, el host mantiene datos persistentes en /srv/onlyoffice/data. Reemplace el nombre de host y las rutas de ejemplo con los suyos. Almacene la cadena completa del certificado como tls.crty la clave privada correspondiente como tls.keyen un certssubdirectorio:

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

Mantenga la clave privada legible únicamente por la cuenta o el servicio que la necesite. No la pegue en un archivo Compose, un informe de errores ni un repositorio público. Si Docker no puede leer la clave debido a la propiedad o los permisos, ajuste el acceso de forma restringida para el entorno de ejecución del contenedor en lugar de hacer que la clave sea legible para todos.

Antes de iniciar el servicio, compruebe las fechas y los nombres de host del certificado:

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

La lista de nombres alternativos del sujeto (SAN) debe incluir el nombre de host exacto que visitarán los usuarios. Puede comparar las claves públicas derivadas del certificado y la clave privada; los dos hashes deben coincidir:

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

Paso 2: Configurar el servicio Docker Compose

La documentación de Docker de ONLYOFFICE coloca los certificados en /var/www/onlyoffice/Data/certs. Su lista actual de variables de entorno proporciona los nombres de archivo de certificado predeterminados como tls.crty tls.key, mientras que las instrucciones de instalación de ejemplo también usan onlyoffice.crty onlyoffice.key. Establecer las rutas explícitamente evita depender de una convención de nombres de archivo. El directorio del host se monta mediante enlace en el directorio de datos del contenedor correspondiente, y el puerto 443 se publica como puerto 443 del host.

Crea un compose.yamlarchivo como este, reemplazando el valor JWT de ejemplo con un secreto generado para tu instalación. La etiqueta de imagen que aparece a continuación es un ejemplo; consulta la lista oficial de imágenes y utiliza la versión que tengas previsto mantener.

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

Genere un secreto seguro openssl rand -hex 32y colóquelo en el archivo de entorno o en la configuración de Compose con los permisos de archivo adecuados. Si otra aplicación se integra con Docs, configure esa aplicación con el mismo secreto JWT y la dirección HTTPS pública. Si se trata de una instalación existente, conserve sus volúmenes, redes, otras variables de entorno y la configuración de integración al editar el archivo Compose existente; no reemplace una definición de servicio que funcione con este ejemplo mínimo.

Inicie o vuelva a crear el servicio desde el directorio que contiene el archivo Compose:

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

Paso 3: Probar HTTPS y el certificado.

Abra el https://docs.example.comdocumento en un navegador, sustituyendo el nombre de host. Compruebe que el navegador muestre una conexión segura y que no indique una discrepancia en el nombre, un certificado caducado o un emisor no confiable. Confirme que se cargue la página de bienvenida de ONLYOFFICE Docs. Cuando Docs esté conectado a Nextcloud, ownCloud u otra plataforma, pruebe también a abrir y guardar un documento; el bloqueo del navegador por sí solo no demuestra que las solicitudes de devolución de llamada de la integración o la configuración JWT funcionen correctamente.

Desde la consola, solicita al servidor su certificado TLS y prueba la respuesta HTTPS:

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

Esta -servernameopción envía el nombre de host mediante Indicación de Nombre de Servidor (SNI), lo que permite que un servidor seleccione el certificado correcto cuando varios nombres de host comparten una dirección. Las fechas del certificado, el emisor y el SAN deben coincidir con el certificado que instaló. Compruebe docker compose logssi el navegador no puede conectarse o si el contenedor se reinicia repetidamente.

¿Qué ocurre si un proxy inverso ya gestiona HTTPS?

Si NGINX, Traefik, Caddy o una puerta de enlace de alojamiento ya poseen los puertos públicos 80 y 443, puede ser mejor instalar el certificado público en ese proxy. En esa topología, publique el contenedor Docs solo en una red Docker privada o vincule su puerto HTTP a la interfaz loopback, luego configure el proxy para reenviar las solicitudes y el tráfico WebSocket necesarios. Establezca la dirección ONLYOFFICE de la aplicación de integración en la https://URL pública. Siga las instrucciones actuales del proxy y de ONLYOFFICE para los encabezados reenviados y TLS ascendente; no publique el puerto 443 del contenedor en el mismo puerto del host que ya utiliza el proxy.

Seleccione este patrón cuando un proxy enrute el tráfico para varios servicios. Utilice la configuración directa del contenedor descrita anteriormente cuando Docs deba controlar el punto final HTTPS público y los puertos necesarios estén libres. Si el proxy se conecta al contenedor mediante HTTP, ese salto interno no está cifrado; manténgalo en una red privada de confianza o configure TLS ascendente si sus requisitos de seguridad así lo exigen.

Problemas comunes y cómo solucionarlos

• El navegador indica que el certificado no es válido. Verifique el nombre de host SAN, la fecha de caducidad del certificado, la cadena completa y que el DNS apunte al host correcto. Un certificado para el dominio principal no cubre automáticamente un subdominio.
• El contenedor informa que falta un certificado o clave. Verifique la ruta de origen del host, el destino del montaje de enlace, los nombres de archivo exactos y los dos SSL_..._PATHvalores. --mountLa sintaxis de Docker requiere que la ruta de origen exista; los montajes de enlace de Compose también deben apuntar al directorio existente previsto.
• El puerto 443 ya está asignado. Detenga el servicio que causa el conflicto, utilice un proxy inverso o seleccione un puerto de host público diferente y asegúrese de que la URL y el cortafuegos lo reflejen. Si hay un proxy delante, normalmente debería ser el propietario del puerto público 443.
• HTTPS funciona, pero la edición de documentos falla. Verifique la URL de integración, el secreto JWT en ambos servicios, las reglas de reenvío del proxy y si Docs puede acceder a la plataforma de almacenamiento. Pruebe un ciclo real de abrir y guardar.
• El certificado se renueva, pero el sitio sigue utilizando el antiguo. Confirme que la renovación actualizó el archivo montado en el host y que ONLYOFFICE lo recargó. Si es necesario, reinicie el servicio después de la renovación, por ejemplo, con un hook de implementación de Certbot que se ejecute docker compose restart documentserverdesde el directorio del proyecto Compose. Pruebe la renovación con la opción de prueba de Certbot antes de automatizarla.

Mantenga el certificado actualizado

La configuración HTTPS no se completa hasta que se planifica la renovación. Registre quién emite y renueva el certificado, dónde se almacena la clave privada, qué proceso copia los archivos renovados en el directorio montado y cómo el servicio los recarga. Ejecute la prueba de funcionamiento del cliente de renovación, supervise la caducidad del certificado y verifique el punto final público después de cada renovación. Si utiliza las variables Let's Encrypt integradas de ONLYOFFICE en lugar de un certificado administrado por el host, siga las instrucciones de Docker vigentes para ese método y compruebe su comportamiento de renovación para la imagen y el despliegue exactos que ejecuta.

Para más información, consulte la guía de instalación de Docker y HTTPS de ONLYOFFICE Docs , la documentación de montaje de enlace de Docker , la documentación de Docker Compose , las etiquetas oficiales de la imagen Docker de ONLYOFFICE y las instrucciones oficiales de Certbot . Las etiquetas disponibles y los detalles de la interfaz pueden cambiar; compruébelos al preparar una nueva implementación.