Como configurar a terminação SSL para um contêiner Collabora CODE

A terminação SSL é uma excelente opção para um contêiner do Collabora Online Development Edition (CODE) quando se deseja um endpoint HTTPS público, mantendo o gerenciamento de certificados em um proxy reverso como o Nginx. Nesse design, o navegador se conecta ao Nginx via HTTPS, o Nginx descriptografa o tráfego e o Collabora recebe HTTP em sua porta interna. O objetivo de qualidade não é apenas "o carregamento da página". Uma implantação bem-sucedida deve ter um certificado público válido, um endpoint de descoberta WOPI acessível, atualizações WebSocket funcionando e uma sessão de edição de documentos ativa e estável.

A documentação do próprio Collabora sobre proxy descreve esse padrão de descarregamento SSL como uma conexão somente HTTP entre o proxy e o Collabora, com o host ssl.enable=falsee o WebSocket ssl.termination=trueconfigurados no lado do Collabora. Consulte as configurações de proxy reverso do Collabora Online . Os exemplos abaixo usam Nginx e Docker Compose, mas o mesmo resultado pode ser obtido com outros proxies reversos, desde que preservem o comportamento necessário em relação ao host e ao WebSocket.

O que uma boa configuração de terminação SSL deve alcançar

Etapa 1: Confirme o limite da rede antes de alterar o Collabora

Defina onde o TLS termina e quais hosts podem acessar a porta 9980. Se o Nginx estiver rodando na mesma máquina que o Docker, vincular a porta publicada a um endereço IP específico 127.0.0.1é uma maneira simples de impedir o acesso direto à internet. A documentação do Docker explica que publicar uma porta em um endereço IP específico a 127.0.0.1mantém local ao host; veja a documentação sobre publicação de portas do Docker .

Se o Nginx estiver sendo executado em outro contêiner, uma rede Docker privada compartilhada geralmente é mais adequada do que expor a porta 9980 publicamente. O princípio é o mesmo: os clientes devem usar o nome de host do proxy reverso HTTPS, e não o contêiner do Collabora diretamente.

Etapa 2: Execute o código no modo de terminação SSL

Para a terminação TLS no lado do proxy, o Collabora deve saber que o esquema original voltado para o cliente é HTTPS, mesmo que sua conexão upstream imediata seja HTTP. As configurações documentadas são:

--o:ssl.enable=false --o:ssl.termination=true

Um exemplo mínimo de Compose se parece com isto:

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

Substitua YOUR_TESTED_TAGpor uma versão que você tenha validado, em vez de presumir automaticamente que ela latesté segura para uma implantação em ambiente de produção. Configure também as definições de host ou alias WOPI apropriadas para a sua integração; esses valores dependem de se você está conectando o Nextcloud, o ownCloud, outro host WOPI ou uma integração personalizada.

Após iniciar o contêiner, confirme se ele está em execução e se o mapeamento de portas corresponde ao limite desejado:

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

Nota de versão para implantações do Ubuntu 26.04

Ao solucionar problemas em uma imagem 26.04 atual, não considere as duas flags SSL como a única variável. Em meados de 2026, a Collabora rastreou regressões relacionadas à imagem Docker sem distribuição e às configurações com SSL desativado. Um problema oficial no GitHub documenta uma regressão na inicialização da versão 26.04, e a comunidade Collabora relatou que o comportamento de encerramento SSL afetado voltou a funcionar em uma versão posterior, a 26.04.2.4.1. Consulte a issue #16019 no CollaboraOnline/online se uma configuração de encerramento que funcionava anteriormente parar de funcionar imediatamente após uma atualização de imagem.

Este também é um motivo para fixar e testar a versão da sua imagem. Um erro de configuração e uma regressão na imagem do contêiner podem parecer semelhantes no Nginx: ambos podem se manifestar como uma resposta 502 ou uma falha na conexão com o servidor upstream.

Etapa 3: Configure o Nginx para encerrar os caminhos TLS e de proxy do Collabora.

O Nginx precisa de um certificado válido para o hostname do Collabora e deve encaminhar os endpoints HTTP do Collabora, além do tráfego WebSocket. O guia de proxy do Collabora mostra locais dedicados para recursos do navegador, descoberta, funcionalidades, conexões WebSocket principais, caminhos de download/upload e o WebSocket de administração. A configuração a seguir segue essa estrutura, adicionando cabeçalhos de encaminhamento comuns:

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;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    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 "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

Os cabeçalhos do WebSocket não são meramente cosméticos. A documentação oficial do Nginx explica que `websocket.htaccess` Upgradee `websocket.htaccess` Connectionsão cabeçalhos de salto a salto e devem ser passados ​​explicitamente para WebSockets com proxy reverso. Consulte Proxy WebSocket do Nginx . A documentação do módulo proxy padrão também aborda proxy_set_header`websocket.htaccess`, proxy_pass`websocket.htaccess` e `websocket.htaccess` proxy_read_timeout: ngx_http_proxy_module .

Passo 4: Valide o Nginx antes de recarregar

Teste a configuração do Nginx antes de substituir uma configuração em funcionamento comprovadamente eficiente:

sudo nginx -t

Recarregue a página somente se o teste de sintaxe for bem-sucedido:

sudo systemctl reload nginx

Em seguida, confirme se o próprio Nginx consegue acessar o backend local do Collabora. Em uma configuração no mesmo host, uma verificação útil é:

curl -I http://127.0.0.1:9980/hosting/discovery

Os cabeçalhos de resposta exatos podem variar de acordo com a versão do Collabora, mas o resultado principal é que a conexão TCP seja bem-sucedida e o endpoint responda, em vez de expirar o tempo limite ou recusar a conexão. Se essa solicitação local falhar, alterar as configurações TLS públicas não resolverá o problema subjacente do contêiner ou da rede.

Etapa 5: Verifique o endpoint HTTPS público

A partir de um cliente que resolve o nome de host público, solicite o endpoint de descoberta através do Nginx:

curl -I https://office.example.com/hosting/discovery

Uma requisição do navegador https://office.example.com/hosting/discoverydeve retornar XML. Essa é uma verificação funcional melhor do que depender da URL raiz, pois o comportamento da página raiz não está de acordo com o contrato principal da WOPI e pode variar conforme a versão.

Inspecione também a cadeia de certificados com seu navegador ou uma ferramenta de diagnóstico TLS. O nome do host deve corresponder ao certificado, a cadeia deve ser confiável e não deve haver avisos de conteúdo misto causados ​​pela Collabora anunciando URLs HTTP simples para o navegador.

Etapa 6: Teste um documento real e o WebSocket

A descoberta bem-sucedida é necessária, mas não suficiente. Abra um documento do seu servidor WOPI e mantenha-o aberto por tempo suficiente para testar a sessão ativa. Nas ferramentas de desenvolvedor do navegador, a solicitação WebSocket do Collabora deve ser atualizada com sucesso, em vez de reconectar repetidamente ou retornar um erro 400/502. Uma sessão ativa deve permitir que você digite, salve e reabra o documento.

Se o shell do editor carregar, mas o documento falhar logo em seguida, priorize o caminho do WebSocket, o tempo limite do proxy, a lista de permissões WOPI e o comportamento do cabeçalho do host. Se os logs do Nginx mostrarem um erro de conexão upstream antes que qualquer WebSocket seja estabelecido, inspecione primeiro o listener e a versão da imagem do CODE.

Como diagnosticar modos de falha comuns

502 Bad Gateway

Um erro 502 geralmente significa que o Nginx não conseguiu obter uma resposta válida do servidor upstream configurado. Verifique se o CODE está realmente escutando na porta 9980 e se você está usando o protocolo upstream correto. No projeto de terminação SSL pretendido, o salto do proxy para o CODE é HTTP. Se uma regressão na imagem fizer com que o CODE continue servindo HTTPS internamente, apesar das suas configurações, os logs e um curlteste direto revelarão a incompatibilidade. Não mude permanentemente para um servidor upstream HTTPS apenas para ocultar uma regressão de configuração inexplicável; primeiro verifique o comportamento da imagem exata do CODE que você está executando.

O sistema de descoberta funciona, mas os documentos não abrem.

Isso geralmente indica um problema com o encaminhamento de WebSocket ou a autorização WOPI, e não com o próprio TLS. Verifique a /cool/.../wsrota, os cabeçalhos de atualização e o host que você permitiu como origem WOPI. O Collabora pode estar perfeitamente acessível via HTTPS, mas ainda assim rejeitar ou interromper uma sessão de edição.

URLs com conteúdo misto ou esquema incorreto

Se um navegador detectar uma página HTTPS que faça referência a recursos HTTP, verifique ssl.termination=trueo cabeçalho do esquema encaminhado e o nome do servidor. O lado público da implementação deve se identificar consistentemente como HTTPS, mesmo que o salto privado seja HTTP.

O contêiner é reportado como não íntegro, mesmo que a edição esteja funcionando.

As versões recentes do 26.04 introduziram um comportamento de verificação de integridade que mudou durante a transição para imagens sem distribuição (distroless-image). A Collabora rastreou um caso em que a sonda não respeitou uma configuração de backend HTTP por trás de uma terminação TLS. Se os testes funcionais forem aprovados, mas o status de integridade do Docker estiver inesperadamente vermelho, verifique o histórico de problemas específico da versão antes de redesenhar um proxy em funcionamento. Consulte a issue #16032 em CollaboraOnline/online .

Quando usar um design diferente

A terminação SSL no lado do proxy é apropriada quando o proxy reverso e o Collabora se comunicam por meio de uma interface local confiável ou uma rede privada isolada. Se o tráfego entre o Nginx e o CODE atravessar uma rede não confiável, o HTTP simples no salto interno pode não atender aos seus requisitos de segurança. Nesse caso, use TLS também no backend ou coloque ambos os serviços em uma rede protegida onde a interceptação não represente uma ameaça real.

Da mesma forma, se você já opera um ingress gerenciado pela plataforma que lida corretamente com certificados, roteamento e WebSockets, há pouco benefício em adicionar uma segunda camada Nginx apenas para o Collabora. A arquitetura correta é aquela que oferece um único limite TLS observável, sem saltos desnecessários.

Lista de verificação de validação final

• O nome de host do Collabora resolve para o proxy reverso.
• A porta 443 apresenta um certificado confiável para esse nome de host.
• O código não é exposto desnecessariamente à internet pública na porta 9980.
• ssl.enable=falsee ssl.termination=truesão aplicadas ao projeto do backend HTTP.
• O Nginx consegue acessar o CODE em seu endereço privado.
• /hosting/discoveryresponde através do URL HTTPS público.
• A /cool/.../wsatualização do WebSocket foi concluída com sucesso.
• Um documento real abre, edita, salva e reabre.
• Você fixou e testou a versão exata da imagem CODE que planeja implantar.

Se todas essas verificações forem aprovadas, a terminação SSL está funcionando corretamente: o tráfego externo está protegido por HTTPS, o Collabora reconhece a conexão pública como segura e o caminho de edição permanece funcional. Se uma verificação falhar, solucione o problema nessa camada em vez de alterar várias partes da pilha simultaneamente.