How to Configure Collabora Online Behind Nginx

What a working reverse proxy should do

A healthy Collabora Online deployment behind Nginx gives users one public HTTPS address for the editor while keeping the Collabora service on a private network. The editor should load its browser assets, discover office capabilities, open a document through the connected storage platform, and keep its WebSocket connection alive during editing. A valid Nginx syntax check alone does not prove those paths work.

This example assumes a standalone Collabora server or CODE container listens on port 9980, Nginx serves office.example.com, and TLS ends at Nginx. Replace the hostname and certificate paths with yours. The backend address 127.0.0.1:9980 applies only when Nginx and Collabora share a host and the service is bound to loopback. For separate containers, use the Collabora service name on a private Docker network, such as http://collabora:9980.

Before changing Nginx

Confirm that the public DNS name resolves to the proxy, that the TLS certificate covers that exact name, and that Nginx can reach Collabora on its internal address. If you use Docker, attach both services to a user-defined network and do not publish the Collabora port publicly. If Nginx runs on the host, bind the container port to loopback, for example 127.0.0.1:9980:9980. Your firewall should expose the public web ports you intend to serve, not the Collabora backend port.

Choose one TLS arrangement. The configuration below uses TLS from the browser to Nginx and plain HTTP on a trusted private hop to Collabora. This is TLS termination. If policy requires encryption between the proxy and Collabora as well, use HTTPS for the upstream and configure Nginx to trust the backend certificate. Do not switch only the proxy_pass scheme: the server-side TLS settings must match the actual Collabora listener. Collabora documents both proxy arrangements in its Nginx reverse-proxy guidance and 25.04 SDK manual.

Set Collabora's proxy-aware TLS options

For TLS termination, configure Collabora's coolwsd service with ssl.enable=false and ssl.termination=true. How you set these values depends on how Collabora was installed: edit the supported coolwsd.xml configuration or use the documented options for your package or container. With the CODE Docker image, deployments commonly pass the options as extra_params; check the image documentation for your version and quote arguments correctly in Compose. Restart or recreate the Collabora service after changing its configuration.

Essas configurações informam ao Collabora que a conexão externa está protegida pelo proxy, mesmo que o salto do proxy para o servidor de armazenamento utilize HTTP. Elas não instalam um certificado público, não configuram o DNS nem autorizam um servidor de armazenamento a usar o Collabora. Configure a lista de permissões de hosts WOPI ou as configurações de integração separadamente, de acordo com sua plataforma de armazenamento.

Configure o Nginx para encaminhar as rotas do editor.

O Nginx deve repassar os recursos de descoberta e do navegador, além de preservar a atualização do WebSocket usada pela edição interativa. O exemplo a seguir é para um único servidor. Defina o `websocket` mapno httpcontexto do Nginx, como no arquivo `main` nginx.conf, e não dentro do host virtual:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Insira o bloco de servidor na configuração do site incluída pelo Nginx. Isso pressupõe que os certificados TLS já estejam instalados e que a conexão entre o proxy e o Collabora seja HTTP:

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;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    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 $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

Os caminhos que começam com `/` /cooltransportam as principais requisições WebSocket e do editor; o padrão também inclui /loolcaminhos legados para compatibilidade. O proxy WebSocket do Nginx requer os cabeçalhos de atualização HTTP/1.1 porque Upgrade`/` e Connection`/` são cabeçalhos de salto a salto. O longo tempo limite de leitura ajuda a evitar o fechamento de uma conexão de edição ativa devido a um tempo limite curto de proxy comum. Consulte a documentação do proxy WebSocket do Nginx e a referência do módulo proxy .

Para HTTPS no servidor upstream, altere os URLs do backend https://e configure a verificação de certificado upstream e a cadeia de certificados confiáveis ​​do Nginx adequadamente. Evite desabilitar a verificação de certificado como solução permanente. Se o Nginx estiver em outro contêiner, substitua o endereço de loopback pelo nome do serviço Collabora; 127.0.0.1dentro do contêiner proxy, aponte de volta para esse contêiner proxy.

Ao usar um prefixo URI, como `/`, /collabora/em vez de um nome de host dedicado, a configuração e os URLs de descoberta gerados pelo Collabora exigem tratamento adicional de caminhos. Comece com um nome de host dedicado, a menos que sua plataforma suporte explicitamente a implantação de subcaminhos. Um bloco de servidor que encaminha solicitações na raiz não faz com que os URLs gerados pela descoberta funcionem automaticamente com um prefixo.

Recarregue e verifique cada camada.

Valide a configuração do Nginx antes de aplicá-la e, em seguida, recarregue o serviço:

sudo nginx -t
sudo systemctl reload nginx

Se a verificação de sintaxe falhar, corrija primeiro o arquivo e a linha relatados. Uma recarga bem-sucedida confirma que o Nginx aceitou a configuração, não que o backend, o certificado ou o caminho do WebSocket estejam funcionando. Verifique a validade do DNS e do certificado separadamente e, em seguida, solicite os dois endpoints do Collabora por meio do nome de host público:

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

O endpoint de descoberta deve retornar XML em vez de uma página 404 do Nginx ou uma página de login; as capacidades devem retornar uma resposta do Collabora. Inspecione os URLs do editor do XML de descoberta: eles devem usar o nome do host HTTPS público e caminhos acessíveis, não um nome de contêiner ou um endereço somente interno. A imagem de exemplo abaixo mostra os tipos de respostas a serem procuradas; os valores exibidos são ilustrativos e não representam a saída de um servidor em produção.

Por fim, configure sua plataforma de documentos para usar https://office.example.como Collabora como servidor e abra um documento de teste. Um bom indicador de sucesso é que o editor carregue e permaneça responsivo enquanto você digita, salva e reabre o documento. Nas ferramentas de desenvolvedor do navegador, a solicitação WebSocket /cool/deve ser atualizada com sucesso; o status HTTP 101 Switching Protocolsé o resultado esperado do handshake do WebSocket. Não considere um exemplo de status exibido como prova de que seu servidor passou nessa verificação.

Analise os fracassos pelos seus sintomas.

• 502 Bad Gateway: O Nginx não consegue alcançar o servidor upstream. Verifique o nome do serviço, a porta, a rede do contêiner, o listener e os logs. Se os contêineres estiverem separados, não use o endereço de loopback do contêiner proxy.
• Erro 404 na descoberta ou nos recursos do navegador: Confirme se a solicitação chega ao host virtual correto e se o encaminhamento do caminho está correto, sem reescrita de URI indesejada. Teste a URL pública, não apenas a URL do servidor.
• O editor carrega, mas trava ou desconecta: Inspecione a /cool/.../wsrequisição. Cabeçalhos de atualização ausentes, uma conexão upstream HTTP/1.0, um tempo limite curto ou um proxy que armazena a conexão em buffer podem interromper a edição. Confirme se a requisição é atualizada e permanece aberta enquanto o documento estiver ativo.
• Host WOPI não autorizado: O proxy pode estar funcionando corretamente, mas o Collabora pode estar rejeitando a plataforma de armazenamento. Verifique o nome real do host WOPI na lista de permissões do Collabora e na configuração do conector da plataforma. Não resolva o problema expondo o backend à internet pública.
• Aviso sobre conteúdo misto ou certificado: Certifique-se de que o URL do editor público e os URLs na descoberta usem HTTPS e que o certificado corresponda ao nome do host. Se você encerrar o TLS no Nginx, verifique também a configuração de encerramento do Collabora.

Após a aprovação nessas verificações, mantenha o backend do Collabora privado e monitore os logs do Nginx e do Collabora ao atualizar qualquer um dos componentes. Este exemplo com um único servidor upstream não configura alta disponibilidade, balanceamento de carga ou afinidade de sessão por documento. Para múltiplas réplicas do Collabora, siga as orientações de implantação do controlador ou balanceador de carga do Collabora relevante e teste a afinidade de documentos antes de rotear o tráfego de produção.

Fontes e notas de versão

Os detalhes de configuração foram verificados em relação à documentação de proxy da Collabora, ao manual do SDK 25.04 e às referências do Nginx sobre WebSocket e módulos de proxy, em 6 de outubro de 2026. As opções de pacote e contêiner podem variar de acordo com a versão da Collabora; confirme os nomes das configurações para a versão que você está executando antes de aplicá-las. Este artigo não pressupõe uma plataforma de armazenamento específica nem comprova uma implantação em produção.