Como configurar HTTPS e um certificado SSL para o Docker do ONLYOFFICE

Para colocar o ONLYOFFICE Docs atrás de um contêiner Docker com HTTPS, use um certificado que corresponda ao nome de host público, disponibilize-o dentro do contêiner e publique a porta HTTPS do contêiner. HTTPS é a conexão web criptografada; um certificado TLS ajuda os navegadores a verificar se acessaram o servidor esperado. Este guia usa um certificado e uma chave privada que você já obteve de uma autoridade certificadora (CA) confiável. Se você usa um proxy reverso, siga a opção separada abaixo, pois o proxy pode lidar com HTTPS.

Qual configuração HTTPS é mais adequada para sua implementação?

O ONLYOFFICE Docs pode servir HTTPS diretamente do seu contêiner Docker, ou um proxy reverso como NGINX ou Traefik pode aceitar HTTPS e encaminhar as requisições para o Docs. O TLS direto é uma escolha simples para um servidor independente cujas portas públicas 80 e 443 estejam disponíveis. Um proxy reverso costuma ser mais simples quando outro serviço web já possui essas portas ou quando vários sites compartilham um mesmo servidor. Evite configurar ambas as camadas às cegas: decida qual componente encerra o TLS e documente se a conexão do proxy com o contêiner é HTTP ou HTTPS.

Este guia passo a passo configura HTTPS direto com um certificado emitido por uma Autoridade Certificadora (CA). A ONLYOFFICE também documenta uma opção automática do Let's Encrypt usando o protocolo `--encrypt-80` LETS_ENCRYPT_DOMAINe LETS_ENCRYPT_MAILo protocolo `--encrypt-443`; ela requer que as portas 80 e 443 estejam acessíveis e não estejam ocupadas por um proxy. Um certificado autoassinado é útil para uma rede de teste privada, mas navegadores públicos e serviços de armazenamento conectados não confiarão nele automaticamente.

O que você deve preparar primeiro?

• Um host Linux com o Docker Engine e o plugin Docker Compose instalados.
• Um registro DNS A para o nome do host, como por exemplo docs.example.com, apontando para o endereço IPv4 público do host. Adicione um registro AAAA somente se o IPv6 estiver configurado e acessível.
• Regras de firewall de entrada e firewall em nuvem que permitem a porta TCP 443. Se você solicitar ou renovar certificados com validação HTTP, a porta TCP 80 também poderá ser necessária.
• Uma cadeia de certificados para o nome de host exato e sua chave privada correspondente. As autoridades certificadoras geralmente fornecem um arquivo de cadeia completa e um arquivo de chave privada.
• Um diretório de host persistente para o volume de dados do ONLYOFFICE e um segredo JWT forte. JWT (JSON Web Token) é um segredo compartilhado usado para autenticar solicitações entre o Docs e um aplicativo de integração.

Passo 1: Coloque o certificado e a chave privada no host.

Neste exemplo, o host mantém dados persistentes em /srv/onlyoffice/data. Substitua o nome do host e os caminhos de exemplo pelos seus próprios. Armazene a cadeia completa do certificado como tls.crte a chave privada correspondente como tls.keyem um certssubdiretório:

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

Mantenha a chave privada legível apenas pela conta ou serviço que precisa dela. Não a cole em um arquivo Compose, um relatório de problema ou um repositório público. Se o Docker não conseguir ler a chave devido à propriedade ou permissões, ajuste o acesso de forma restrita para o ambiente de execução do contêiner, em vez de torná-la legível para todos.

Verifique as datas e os nomes de host do certificado antes de iniciar o serviço:

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

A lista de Nomes Alternativos do Assunto (SAN) deve incluir o nome de host exato que as pessoas visitarão. Você pode comparar as chaves públicas derivadas do certificado e da chave privada; os dois hashes devem corresponder.

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

Etapa 2: Configurar o serviço Docker Compose

A documentação do Docker da ONLYOFFICE coloca os certificados em `/etc/docs` /var/www/onlyoffice/Data/certs. Sua lista atual de variáveis ​​de ambiente define os nomes de arquivo de certificado padrão como `/etc/docs` tls.crte `/etc/docs`, enquanto as instruções de instalação de exemplo também tls.keyusam `/etc/ docs` e `/etc/docs`. Definir os caminhos explicitamente evita depender de uma convenção de nomenclatura de arquivos. O diretório do host é montado no diretório de dados do contêiner correspondente e a porta 443 é publicada como a porta 443 do host.onlyoffice.crtonlyoffice.key

Crie um compose.yamlarquivo como este, substituindo o valor JWT de exemplo por um segredo gerado para sua instalação. A tag de imagem abaixo é uma versão de exemplo; verifique a lista de imagens oficial e use uma versão que você pretende manter.

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

Gere um segredo forte e openssl rand -hex 32coloque-o no arquivo de ambiente ou na configuração do Compose com as permissões de arquivo adequadas. Se outro aplicativo se integrar ao Docs, configure esse aplicativo com o mesmo segredo JWT e o endereço HTTPS público. Se esta for uma instalação existente, preserve seus volumes, redes, outras variáveis ​​de ambiente e configurações de integração ao editar o arquivo Compose existente; não substitua uma definição de serviço em funcionamento por este exemplo mínimo.

Inicie ou recrie o serviço a partir do diretório que contém o arquivo Compose:

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

Etapa 3: Teste o HTTPS e o certificado

Abra https://docs.example.comem um navegador, substituindo o nome do host. Verifique se o navegador exibe uma conexão segura e não reporta incompatibilidade de nome, certificado expirado ou emissor não confiável. Confirme se a página inicial do ONLYOFFICE Docs carrega. Quando o Docs estiver conectado ao Nextcloud, ownCloud ou outra plataforma, teste também a abertura e o salvamento de um documento; o travamento do navegador por si só não comprova que as solicitações de retorno de chamada da integração ou a configuração do JWT funcionam.

A partir do terminal, solicite o certificado TLS do servidor e teste a resposta HTTPS:

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

Essa -servernameopção envia o nome do host usando a Indicação de Nome do Servidor (SNI), o que permite que um servidor selecione o certificado correto quando vários nomes de host compartilham um endereço. As datas, a autoridade emissora e o SAN do certificado devem corresponder ao certificado que você instalou. Verifique docker compose logsse o navegador não consegue se conectar ou se o contêiner reinicia repetidamente.

E se um proxy reverso já lidar com HTTPS?

Se o NGINX, Traefik, Caddy ou um gateway de hospedagem já possuir as portas públicas 80 e 443, pode ser melhor instalar o certificado público nesse proxy. Nessa topologia, publique o contêiner Docs apenas em uma rede Docker privada ou vincule sua porta HTTP ao loopback e, em seguida, configure o proxy para encaminhar as solicitações necessárias e o tráfego WebSocket. Defina o endereço do ONLYOFFICE do aplicativo de integração para a https://URL pública. Siga as instruções atuais do proxy e do ONLYOFFICE para cabeçalhos encaminhados e TLS upstream; não publique a porta 443 do contêiner na mesma porta do host que o proxy já utiliza.

Escolha este padrão quando um proxy rotear o tráfego para vários serviços. Use a configuração de contêiner direto acima quando o Docs precisar do endpoint HTTPS público e as portas necessárias estiverem livres. Se o proxy se conectar ao contêiner via HTTP, esse salto interno não será criptografado; mantenha-o em uma rede privada confiável ou configure TLS upstream se seus requisitos de segurança assim o exigirem.

Problemas comuns e como resolvê-los

• O navegador indica que o certificado é inválido. Verifique o nome de host SAN, a data de expiração do certificado, a cadeia completa e se o DNS aponta para o host correto. Um certificado para o domínio raiz não cobre automaticamente um subdomínio.
• O contêiner reporta a ausência de um certificado ou chave. Verifique o caminho de origem do host, o destino da montagem de diretórios, os nomes exatos dos arquivos e os dois SSL_..._PATHvalores. --mountA sintaxe do Docker exige que o caminho de origem exista; as montagens de diretórios do Compose também devem apontar para o diretório existente pretendido.
• A porta 443 já está alocada. Pare o serviço conflitante, use um proxy reverso ou escolha uma porta pública diferente para o host e certifique-se de que o URL e o firewall reflitam essa escolha. Se houver um proxy na frente, ele geralmente deve ser o proprietário da porta pública 443.
• O HTTPS funciona, mas a edição de documentos falha. Verifique o URL de integração, o segredo JWT em ambos os serviços, as regras de encaminhamento de proxy e se o Docs consegue acessar a plataforma de armazenamento. Teste um ciclo real de abrir e salvar.
• O certificado foi renovado, mas o site ainda exibe a versão antiga. Confirme se a renovação atualizou o arquivo montado no host e se o ONLYOFFICE o recarregou. Se necessário, reinicie o serviço após a renovação, por exemplo, com um hook de implantação do Certbot executado a docker compose restart documentserverpartir do diretório do projeto Compose. Teste a renovação com a opção de simulação do Certbot antes de confiar na automação.

Mantenha o certificado atualizado.

A configuração HTTPS não estará completa até que a renovação seja planejada. Registre quem emite e renova o certificado, onde a chave privada é armazenada, qual processo copia os arquivos renovados para o diretório montado e como o serviço os recarrega. Execute o teste de simulação do cliente de renovação, monitore a expiração do certificado e verifique o endpoint público após cada renovação. Se você usar as variáveis ​​Let's Encrypt integradas do ONLYOFFICE em vez de um certificado gerenciado pelo host, siga as instruções atuais do Docker para esse método e verifique o comportamento de renovação para a imagem e implantação exatas que você utiliza.

Para referência, consulte o guia de instalação do Docker e HTTPS da ONLYOFFICE Docs , a documentação de montagem de diretórios do Docker , a documentação do Docker Compose , as tags oficiais da imagem Docker da ONLYOFFICE e as instruções oficiais do Certbot . As tags disponíveis e os detalhes da interface podem mudar; verifique-os ao preparar uma nova implantação.