Como configurar o Collabora CODE no Kubernetes com o Helm

Uma página do Collabora Online pode permanecer em branco ou exibir uma mensagem informando que o servidor do escritório está indisponível, mesmo após o pod CODE estar em execução. Um pod íntegro é apenas uma parte da configuração: o navegador e seu aplicativo WOPI devem acessar o Collabora por meio do nome de host público, as configurações de TLS e proxy devem estar corretas e o Collabora deve confiar no host WOPI. O gráfico Helm oficial do Collabora implanta o servidor no Kubernetes; ele não instala nem configura o Nextcloud, o ownCloud ou outro host WOPI para você.

Este guia utiliza o gráfico Helm mantido pela Collabora com um exemplo de NGINX Ingress. Substitua os domínios de exemplo pelos seus próprios. O CODE é a Edição de Desenvolvimento do Collabora Online, destinada à avaliação, uso doméstico e pequenas equipes; a Collabora afirma que não é recomendada para ambientes de produção que necessitam de uma versão estável e com suporte. Para cargas de trabalho de produção, avalie a oferta do Collabora Online com suporte e seus termos de licenciamento e suporte.

O que você precisa antes da instalação

• Um cluster Kubernetes em funcionamento kubectle o Helm 3 com acesso ao cluster.
• Um controlador Ingress instalado no cluster. O exemplo abaixo usa ingress-nginx; o gráfico da Collabora também documenta o HAProxy e oferece suporte a outras configurações de roteamento.
• Um nome DNS, como por exemplo, office.example.comapontando para o endereço de entrada público, além de um certificado TLS armazenado como um segredo do Kubernetes no namespace Collabora.
• Uma aplicação WOPI, como o Nextcloud, com um URL como cloud.example.com. O Collabora deve ser capaz de acessar a aplicação WOPI, e a aplicação e os navegadores dos usuários devem ser capazes de acessar o Collabora.
• Um plano TLS claro. Este exemplo encerra o HTTPS na entrada e envia HTTP para o serviço Collabora dentro do cluster.

Para uma implantação rápida em casa ou para testes, um único pod CODE simplifica o roteamento. Várias réplicas podem aumentar a capacidade, mas o guia do Kubernetes da Collabora destaca um requisito de balanceamento de carga baseado em WOPISrc para que as sessões de edição do mesmo documento acessem o mesmo pod. Não aumente o número de réplicas antes de confirmar se o seu controlador de entrada (ingress controller) pode fornecer a afinidade necessária.

Passo 1: Adicione o gráfico oficial e selecione uma versão.

A Collabora publica seu gráfico do projeto CollaboraOnline. A página de lançamentos lista atualmente a versão 1.3.5 do gráfico (verificada em 6 de outubro de 2026). Verifique as versões disponíveis em seu ambiente e fixe a versão do gráfico para que uma atualização posterior do repositório não altere silenciosamente o gráfico que você implanta.

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

O repositório oficial de gráficos é útil para verificar as configurações padrão atuais antes de escrever alterações:

helm show values collabora/collabora-online --version 1.3.5

Se o seu repositório listar um gráfico compatível mais recente ao seguir este guia, revise as notas de versão e os valores antes de substituí-lo. A versão do gráfico e a versão da imagem do aplicativo CODE são entradas de versão relacionadas, mas não são a mesma configuração.

Etapa 2: Crie um namespace e proteja a senha de administrador.

Crie o namespace e um segredo do Kubernetes para as credenciais de administrador opcionais do Collabora do gráfico. Substitua a senha de espaço reservado por um segredo forte ou crie o segredo por meio do gerenciador de segredos da sua organização ou do fluxo de trabalho de segredos do GitOps. Não inclua uma senha real no arquivo values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

O gráfico permite referenciar um segredo existente. Habilitar essa opção evita inserir a senha de administrador diretamente no arquivo de valores do Helm. Mantenha o segredo restrito ao namespace e aos usuários ou contas de serviço que administram esta implantação.

Etapa 3: Configure o nome do host, o host WOPI e o ingress

Crie um arquivo chamado collabora-values.yaml. Este exemplo pressupõe o uso do ingress-nginx, um segredo TLS chamado office-example-com-tls, e o Nextcloud em https://cloud.example.com. O grupo de alias deve nomear o host do aplicativo WOPI que o Collabora tem permissão para contatar; não é o nome de host público do Collabora.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

O exemplo documentado do gráfico aliasgroupspermite o host WOPI e utiliza esses parâmetros SSL quando um proxy reverso encerra o TLS. Nessa configuração, o tráfego externo office.example.comusa HTTPS, enquanto o ingress encaminha o tráfego para o Collabora via HTTP dentro do cluster. Se o seu ingress usa TLS passthrough ou um protocolo interno diferente, não copie esses sinalizadores SSL cegamente; ajuste-os para corresponder ao caminho TLS real e aos valores atuais do gráfico.

Confirme se o segredo TLS existe no collaboranamespace. Se você usar um controlador de entrada diferente, substitua a classe e as anotações pelos equivalentes documentados desse controlador. Mantenha o tráfego WebSocket habilitado e permita conexões de longa duração; os valores padrão do controlador variam.

Etapa 4: Renderize e instale o gráfico

Primeiro, renderize os manifestos para detectar erros de YAML e revisar as configurações geradas de Ingress, Service e workload. Em seguida, instale a versão do chart fixada:

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

Acompanhe os recursos à medida que forem disponibilizados:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Aguarde até que o pod fique pronto antes de conectar o aplicativo WOPI. Se ele permanecer pendente, verifique se o cluster possui CPU e memória disponíveis para agendamento suficientes e se algum seletor de nó, restrição ou cota de recursos impede a alocação. O gráfico deixa as solicitações e os limites de recursos para o operador escolher; o arquivo README da Collabora fornece valores de recursos de exemplo maiores para ambientes de produção, mas o dimensionamento real depende da edição simultânea e da carga de trabalho dos documentos.

Etapa 5: Conecte o Nextcloud ou outro host WOPI

Abra as configurações do Office ou do Collabora do seu aplicativo WOPI e insira a URL do serviço externo https://office.example.com. No Nextcloud, o manual de administração descreve como configurar a URL do servidor Collabora Online nas configurações de administração do Office. Verifique também a lista de permissões de solicitações WOPI do Nextcloud se sua configuração restringir quais hosts podem se conectar. O endereço deve ser acessível tanto pelos navegadores dos usuários finais quanto pelo servidor de aplicativos que faz as solicitações WOPI.

Se a conexão falhar com uma mensagem de “host WOPI não autorizado” ou similar, compare o URL do host WOPI real com o especificado collabora.aliasgroups. Verifique o esquema, o nome do host e a porta, e adicione deliberadamente quaisquer nomes de host alternativos legítimos. Evite padrões de host genéricos, a menos que compreenda o seu efeito. Se usar mais de uma aplicação WOPI, siga a estrutura de grupos de aliases documentada na tabela para cada host, em vez de permitir todos os domínios.

Quando você deve expandir para além de um único pod?

Para um teste em pequena escala, uma única réplica com escalonamento automático desativado evita a complexidade de roteamento. Para múltiplas réplicas, o README do gráfico Collabora mostra a afinidade do NGINX com base no WOPISrcargumento de consulta. Adicione a anotação documentada ao ingress ao usar o ingress-nginx:

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

Isso direciona as solicitações para o mesmo documento para o mesmo pod de backend, o que é importante para edição colaborativa e solicitações de área de transferência. Consulte a documentação da sua versão exata do controlador de entrada; uma anotação compatível com o ingress-nginx não é automaticamente válida para HAProxy, Traefik ou uma implementação da API Gateway. Após habilitar mais réplicas ou escalonamento automático, teste edições simultâneas no mesmo documento e monitore os logs do Collabora e os logs de acesso de entrada. O dimensionamento de recursos, o comportamento da sessão e a alta disponibilidade exigem validação específica para cada carga de trabalho.

Verifique a implantação pelo lado de fora.

1. Confirme se o Kubernetes reporta o pod como Pronto e se o Serviço e o Ingress existem: kubectl get pods,svc,ingress -n collabora.
2. Verifique o endpoint de descoberta público. Ele deve retornar XML em vez de um erro de navegador ou proxy:

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

3. Abra o aplicativo WOPI e edite um documento de teste. Confirme se o editor carrega, se as alterações são salvas e se, ao reabrir o documento, o conteúdo salvo é exibido.
4. Se estiver usando várias réplicas, abra o mesmo documento em duas sessões e confirme se ambas conseguem colaborar sem reconexões repetidas. Isso ajuda a identificar problemas de afinidade entre as sessões.
5. Analise os registros em busca de erros de TLS, autorização WOPI ou erros de origem:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   Se o gráfico criar uma carga de trabalho com nome diferente, use kubectl get deployments -n collaborae substitua o nome real.

Uma resposta de descoberta bem-sucedida confirma que o endpoint público está fornecendo metadados do Collabora; isso não prova que a autenticação WOPI ou o salvamento de documentos estejam funcionando. O teste de documento de ponta a ponta é a verificação final.

Pontos de falha comuns

• O Ingress retorna 404 ou 502: verifique o DNS, a classe do Ingress, o segredo TLS e os endpoints do serviço. Confirme se o Ingress consegue alcançar o serviço Collabora na porta de serviço do gráfico.
• A descoberta funciona, mas o editor permanece em branco: verifique os erros no console do navegador e os registros do proxy. Verifique as configurações de encerramento HTTPS, o tratamento de websockets e os tempos limite de requisição longos.
• Host WOPI não autorizado: permita a origem do aplicativo WOPI em aliasgroups; não substitua o nome do host do servidor de escritório.
• Se um pod for reiniciado ou removido, inspecione kubectl describe podos logs do contêiner e defina solicitações e limites de recursos realistas para o cluster disponível.
• A edição torna-se instável após a adição de réplicas: verifique a afinidade baseada em WOPISrc e confirme se o controlador preserva o argumento de consulta ao rotear as solicitações.

Com o gráfico instalado, o endpoint de descoberta acessível e um documento real aberto e salvo com sucesso por meio do aplicativo WOPI, a implantação principal do CODE está funcionando. Mantenha a versão do gráfico fixada e repita essas verificações após atualizações do gráfico, alterações de entrada ou alterações de escalabilidade.

Referências oficiais

• Guia de implantação e gráfico Helm do Kubernetes mantido pela Collabora
• Valores do gráfico de colaboração Helm
• Lançamentos de gráficos da Collabora
• Guia do Collabora Online Development Edition (CODE)
• Manual de configuração do Nextcloud Office
• Documentação de anotações do ingress-nginx
• Referência do comando de instalação do Helm