Implante o Collabora CODE no Kubernetes com o Helm.

Em 10 de outubro de 2026, o registro de pacotes upstream listava a versão 1.3.0 do gráfico como a versão mais recente. A instalação do gráfico é apenas parte de uma implantação funcional. Você também precisa de um nome de host público do Collabora, uma entrada válida na lista de permissões WOPI para o host de armazenamento de documentos e uma configuração de entrada que mantenha as solicitações para cada documento no mesmo pod. O registro de pacotes upstream listava a versão 1.3.0 do gráfico no momento da redação deste documento; verifique o repositório antes de instalar, pois a versão do gráfico Helm e a versão da imagem do contêiner CODE são valores separados.

Este procedimento utiliza o collabora/collabora-onlinegráfico oficial e um controlador de entrada NGINX. O arquivo README do gráfico também inclui exemplos de HAProxy; as anotações de entrada são específicas para cada controlador, portanto, use o exemplo correspondente ao controlador instalado em vez de misturar anotações.

O que preparar primeiro

• Um cluster Kubernetes com permissão para criar um namespace, um Deployment, um Service e um Ingress.
• Helm 3 e um controlador de entrada instalado que possa fornecer HTTPS para um nome de host como office.example.com.
• O nome de host público do cliente WOPI, como Nextcloud ou Seafile. Este é o host que a Collabora deve permitir; não é o nome de host da Collabora.
• Um segredo do Kubernetes para as credenciais do console de administração do Collabora. Não guarde a senha de exemplo do gráfico nem insira uma senha real em um arquivo de valores.

1. Adicione o repositório oficial de gráficos e inspecione a versão.

O Collabora publica seu gráfico a partir do repositório online do projeto. Adicione-o, atualize o índice local e inspecione os metadados e os valores padrão do gráfico antes de instalá-lo:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm show chart collabora/collabora-online
helm show values collabora/collabora-online

A versão do gráfico identifica o pacote, não necessariamente a tag CODE da imagem. Verifique o repositório de imagens e a tag nos valores de lançamento e, em seguida, fixe a versão do gráfico que você revisou para atualizações repetíveis.

Crie um segredo com escopo de namespace usando seu fluxo de trabalho de gerenciamento de segredos aprovado. Os valores do gráfico suportam um segredo existente e nomes de chave configuráveis; os nomes de chave padrão são `<secret>` usernamee `<key> password`. Verifique se o segredo existe no collaboranamespace antes de instalar.

2. Defina as opções de host, entrada e proxy do WOPI.

Crie um arquivo my_values.yaml. Substitua os dois nomes de host de exemplo pelos seus domínios públicos reais. O aliasgroupsvalor identifica o cliente WOPI (por exemplo, o servidor Seafile ou Nextcloud). O host de entrada server_nameidentifica o serviço Collabora que os navegadores dos usuários acessam.

replicaCount: 1

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    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

autoscaling:
  enabled: false

collabora:
  aliasgroups:
    - host: "https://files.example.com:443"
  extra_params: --o:ssl.enable=false --o:ssl.termination=true
  server_name: office.example.com:443
  existingSecret:
    enabled: true
    secretName: collabora-admin
    usernameKey: username
    passwordKey: password

Este exemplo segue o padrão de entrada NGINX documentado pela Collabora: as requisições são criptografadas usando o WOPISrcparâmetro e os tempos limite de leitura e envio do proxy são estendidos para as sessões de documentos. Confirme os nomes das anotações com a versão do seu controlador de entrada. Se você usa HAProxy, utilize as anotações do HAProxy e a configuração de balanceamento presentes no README do gráfico.

As opções `--ingress` ssl.enable=falsee `--public` ssl.termination=truesão para um design onde o TLS termina no ponto de entrada e o tráfego do ponto de entrada para o pod é interno. Elas não significam que o endpoint público deva usar HTTP. Mantenha o nome do host do ponto de entrada em HTTPS e não exponha o serviço HTTP puro do pod diretamente à internet. Defina essa opção server_namequando o Collabora estiver atrás de um proxy reverso ou não puder inferir diretamente seu nome de host externo.

Para múltiplas réplicas fixas, configure-as replicaCountdeliberadamente e mantenha a afinidade de sessão. O README original indica que o HPA está desativado porque o escalonamento pode interromper a edição colaborativa e o copiar/colar. Um número maior de réplicas por si só não garante o roteamento correto; confirme se o seu servidor de entrada envia solicitações para o mesmo documento para o mesmo pod.

3. Instale o Collabora CODE

Instale a versão do repositório oficial e aguarde até que a implantação esteja pronta:

helm install --create-namespace \
  --namespace collabora \
  collabora-online collabora/collabora-online \
  --values my_values.yaml

kubectl get pods -n collabora
kubectl get ingress -n collabora

Se você estiver atualizando uma versão existente, use helm upgradeo mesmo nome de versão, namespace e arquivo de valores em vez de criar uma segunda versão. Revise as notas de versão e as alterações renderizadas do gráfico antes de atualizar uma instância de produção.

Verifique se o pod está pronto e se o Ingress reporta o host e o endereço esperados. Se o problema persistir, inspecione os eventos e logs antes de alterar as configurações de recursos.

kubectl describe pods -n collabora
kubectl logs -n collabora deployment/<deployment-name>

Dimensionar CPU e memória de acordo com sua carga de trabalho e capacidade do cluster. O arquivo README do gráfico fornece exemplos de solicitações e limites, não sendo uma garantia para todas as implementações. Fique atento a limitações de desempenho, interrupções por falta de memória (OOM) e reinicializações.

4. Verificar descoberta e edição de documentos

Após o DNS e o TLS estarem ativos, solicite o endpoint de descoberta da Collabora através do nome de host público:

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

Uma resposta bem-sucedida deve conter o XML de descoberta do WOPI, em vez de uma página de erro de entrada ou um aviso de certificado. Em seguida, configure seu cliente WOPI com a mesma URL pública do Collabora e confirme se a URL do Collabora aliasgroupsinclui o nome do host HTTPS e a porta desse cliente. A configuração exata do cliente depende do produto de armazenamento.

Abra um documento de teste no cliente WOPI e faça uma pequena alteração. Confirme se o editor carrega, se uma segunda sessão do navegador pode ser iniciada caso seja necessária colaboração e se a alteração é salva no serviço de armazenamento. Essa verificação de ponta a ponta testa DNS, TLS de entrada, roteamento de sessão, autorização do host WOPI e transferência de arquivos.

Suposições comuns a verificar

• “O Helm está instalado, então o Collabora está pronto para produção.” O gráfico cria recursos do Kubernetes, mas DNS, TLS, autorização de host WOPI, roteamento de entrada e dimensionamento de recursos ainda dependem do seu cluster. Verifique cada item acima.
• “O host de entrada e o host WOPI têm a mesma configuração.” Eles geralmente diferem: o host de entrada é o endereço público do Collabora; o host WOPI é o servidor de armazenamento. Coloque cada um no campo correto do gráfico.
• “Mais réplicas melhoram automaticamente a colaboração.” O gráfico upstream documenta a afinidade de sessão e atualmente desativa o HPA porque o escalonamento pode interromper a edição colaborativa. Comece com uma réplica ou um número fixo deliberado e preserve a afinidade de roteamento.
• Um pequeno fragmento XML pode ser fornecido como configuração personalizada. O valor do gráfico coolwsd_xml_contentsubstitui o arquivo de configuração padrão e requer o conteúdo completo do arquivo. Prefira os valores dedicados do gráfico para grupos de aliases e parâmetros, a menos que você tenha uma configuração XML completa e compatível com a versão.

Referências oficiais

• Implantação do Helm Chart no Collabora Online - README
• Valores oficiais do gráfico e opções de configuração
• Versões do pacote de gráficos Collabora
• Documentação do Kubernetes Ingress