Collabora Online Documentation

When using the COOL Controller, you must configure the reverse proxy to hash on RouteToken and split the controller URLs. The client-facing indirection_endpoint.url must go through the proxy, while the monitors.monitor WebSocket should point directly to the controller Service in-cluster to avoid passing through nginx.

Configuration Pattern:

1. Set reverseProxy.hashParam to RouteToken.
2. Enable reverseProxy.controller.enabled.
3. Set collabora.extra_params with the external host for the indirection endpoint and the internal cluster DNS for the monitor WebSocket.

reverseProxy:
  enabled: true
  hashParam: RouteToken
  controller:
    enabled: true
    upstream: cool-controller.collabora.svc.cluster.local:9000
  route:
    enabled: true
    host: cool.apps.example.com

collabora:
  extra_params: >-
    --o:ssl.enable=false
    --o:ssl.termination=false
    --o:indirection_endpoint.url=http://cool.apps.example.com/controller/routeToken
    --o:monitors.monitor[0]=ws://cool-controller.collabora.svc.cluster.local:9000/controller/ws
    --o:monitors.monitor[0][@retryInterval]=5

To deploy Collabora Online on Kubernetes, you must use Helm and ensure your Ingress Controller supports session affinity based on the WOPISrc parameter. This ensures that all users editing the same document and all clipboard requests are served by the same pod, which is vital for collaborative editing and copy/paste functionality.

Prerequisites

1. Install Helm.
2. Set up an Ingress Controller (Nginx or HAProxy).
   • Note for OpenShift: It is recommended to deploy the HAProxy Kubernetes Ingress in the collabora namespace instead of the default OpenShift Router, as the Router lacks necessary advanced annotations.

Installation Steps

1. Create a my_values.yaml file with your specific configuration (see configuration guides below).
2. Add the Collabora Helm repository:

   helm repo add collabora https://collaboraonline.github.io/online/

3. Install the chart:

   helm install --create-namespace --namespace collabora collabora-online collabora/collabora-online -f my_values.yaml

Collabora Online supports integration with kube-prometheus-stack for monitoring and the Logging Operator for log management.

Monitoring with Prometheus and Grafana

To enable monitoring, ensure your my_values.yaml includes the prometheus and grafana blocks. If using kube-prometheus-stack, use that as the release name so labels match.

Logging with Logging Operator

To enable logging, set logging.enabled: true. You can use ecs: true to remap fields to the Elastic Common Schema and additionalFilters to exclude noisy logs (e.g., info/debug/trace levels).

### Monitoring Configuration
```yaml
prometheus:
  servicemonitor:
     enabled: true
     labels:
        release: "kube-prometheus-stack"
  rules:
     enabled: true
     additionalLabels:
        release: "kube-prometheus-stack"
grafana:
  dashboards:
     enabled: true

Logging Configuration

logging:
  enabled: true
  ecs: true
  dedot: "-"
  additionalFilters:
    - grep:
        exclude:
          - key: "$['log']['level']"
            pattern: '/(info|debug|trace)/'
  globalOutputRefs:
    - "default"

To serve Collabora through the default OpenShift Router using the in-namespace proxy, use the following Helm configuration. Note that in restricted-v2 environments, the per-document jail is disabled and working paths must be moved to /tmp using extraVolumes and extraVolumeMounts.

Required extra_params for OpenShift:

• --o:ssl.enable=false
• --o:ssl.termination=false
• --o:security.capabilities=false
• --o:child_root_path=/tmp/coolwsd-child-roots
• --o:cache_files.path=/tmp/coolwsd-cache

helm install collabora-online collabora/collabora-online -n collabora \
  --set replicaCount=3 \
  --set 'collabora.aliasgroups[0].host=https://your-wopi-host' \
  --set 'securityContext.runAsNonRoot=true' \
  --set 'securityContext.seccompProfile.type=RuntimeDefault' \
  --set 'securityContext.capabilities.drop[0]=ALL' \
  --set 'collabora.extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:security.capabilities=false --o:child_root_path=/tmp/coolwsd-child-roots --o:cache_files.path=/tmp/coolwsd-cache' \
  --set reverseProxy.enabled=true \
  --set reverseProxy.route.enabled=true \
  --set reverseProxy.route.host=cool.apps.example.com

Collabora Online requires specific Ingress annotations to handle long-lived connections and ensure document affinity via the WOPISrc URL parameter.

HAProxy Configuration

Use balance url_param WOPISrc to ensure all URLs containing the same WOPISrc are routed to the same pod. Use hash-type consistent for better distribution.

Nginx Configuration

Use the upstream-hash-by annotation with $arg_WOPISrc to achieve document affinity.

Important: Horizontal Pod Autoscaling (HPA) is currently disabled because scaling events can break collaborative editing and copy/paste. Set replicaCount manually based on your needs.

### HAProxy Example
```yaml
ingress:
  enabled: true
  className: "haproxy"
  annotations:
     haproxy.org/timeout-tunnel: "3600s"
     haproxy.org/backend-config-snippet: |
        balance url_param WOPISrc check_post
        hash-type consistent

Nginx Example

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"

Collabora Online requires session affinity (every request for a document must reach the same pod). If you cannot use an Ingress controller (e.g., in OpenShift), enable the in-namespace nginx reverse proxy using reverseProxy.enabled=true.

Key Configuration Options:

• reverseProxy.enabled: Enables the nginx deployment and associated services.
• reverseProxy.hashParam: Determines the hashing parameter. Use WOPISrc (default) for standalone deployments. Use RouteToken when running with the COOL Controller.
• reverseProxy.endpointReloader.enabled: Enables a sidecar to reload nginx when pods change. Set to false if your cluster forbids shared process namespaces.
• reverseProxy.controller.enabled: When true, proxies only the client-facing /controller endpoint.
• reverseProxy.controller.upstream: The service address for the COOL Controller (e.g., cool-controller.namespace.svc.cluster.local:9000).

To avoid restarting pods when modifying WOPI hosts, you can use Remote/Dynamic Configuration. This allows Collabora to fetch configuration from an external webserver via a JSON file.

Setup Requirements

1. Set the remoteconfigurl environment variable in the collabora.env section.
2. Enable dynamicConfig.enabled: true in your my_values.yaml.
3. Note: The remoteconfigurl currently only supports HTTPS.

Example Configuration

collabora:
   env:
      - name: remoteconfigurl
         value: https://dynconfig.public.example.com/config/config.json

dynamicConfig:
   enabled: true
   ingress:
      enabled: true
      hosts:
      - host: "dynconfig.public.example.com"
   configuration:
      kind: "configuration"
      storage:
         wopi:
         alias_groups:
            groups:
            - host: "https://domain1\\.xyz\\.abc\\.com/"
               allow: true