How to Configure SSL Termination for a Collabora CODE Container

SSL termination is a strong fit for a Collabora Online Development Edition (CODE) container when you want one public HTTPS endpoint while keeping certificate management at a reverse proxy such as Nginx. In this design, the browser connects to Nginx over HTTPS, Nginx decrypts the traffic, and Collabora receives plain HTTP on its internal port. The quality target is not merely “the page loads.” A successful deployment should have a valid public certificate, a reachable WOPI discovery endpoint, working WebSocket upgrades, and a real document-editing session that stays connected.

Collabora’s own proxy documentation describes this SSL-offload pattern as an HTTP-only connection between the proxy and Collabora, with ssl.enable=false and ssl.termination=true on the Collabora side. See the Collabora Online reverse proxy settings. The examples below use Nginx and Docker Compose, but the same outcome can be achieved with other reverse proxies if they preserve the required host and WebSocket behavior.

What a Good SSL-Termination Setup Should Achieve

Step 1: Confirm the Network Boundary Before Changing Collabora

Decide where TLS ends and which hosts can reach port 9980. If Nginx runs on the same machine as Docker, binding the published port to 127.0.0.1 is a simple way to prevent direct Internet access. Docker documents that publishing a port to 127.0.0.1 keeps it local to the host; see Docker’s port-publishing documentation.

If Nginx runs in another container, a shared private Docker network is usually cleaner than publishing 9980 publicly. The principle is the same: clients should use the HTTPS reverse-proxy hostname, not the Collabora container directly.

Step 2: Run CODE in SSL-Termination Mode

For proxy-side TLS termination, Collabora should know that the original client-facing scheme is HTTPS even though its immediate upstream connection is HTTP. The documented settings are:

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

A minimal Compose example looks like this:

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"

Verwenden Sie stattdessen YOUR_TESTED_TAGeine von Ihnen geprüfte Version, anstatt automatisch davon auszugehen, dass diese latestfür den Produktiveinsatz geeignet ist. Konfigurieren Sie außerdem die entsprechenden WOPI-Host- oder Alias-Einstellungen für Ihre Integration. Diese Werte hängen davon ab, ob Sie Nextcloud, ownCloud, einen anderen WOPI-Host oder eine benutzerdefinierte Integration verbinden.

Nach dem Start des Containers überprüfen Sie, ob er läuft und ob die Portzuordnung Ihren gewünschten Grenzen entspricht:

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

Versionshinweis für 26.04-Bereitstellungen

Behandeln Sie die beiden SSL-Flags nicht als einzige Variable bei der Fehlersuche in einem aktuellen 26.04-Image. Mitte 2026 verfolgte Collabora Regressionen im Zusammenhang mit dem Docker-Image ohne Distro und SSL-deaktivierten Konfigurationen. Ein offizielles GitHub-Issue dokumentiert eine Regression beim Start von 26.04. Die Collabora-Community berichtete, dass das betroffene SSL-Terminierungsverhalten in einem späteren 26.04.2.4.1-Image wieder funktionierte. Prüfen Sie das CollaboraOnline/online-Issue #16019, falls eine zuvor funktionierende Terminierungskonfiguration unmittelbar nach einem Image-Upgrade nicht mehr funktioniert.

Dies ist auch ein Grund, Ihre Image-Version festzulegen und zu testen. Ein Konfigurationsfehler und eine Regression des Container-Images können sich für Nginx ähnlich äußern: Beide können als 502-Fehler oder als fehlgeschlagene Upstream-Verbindung angezeigt werden.

Schritt 3: Nginx so konfigurieren, dass TLS-Verbindungen beendet und Collabora-Pfade weitergeleitet werden

Nginx benötigt ein gültiges Zertifikat für den Collabora-Hostnamen und muss sowohl die HTTP-Endpunkte als auch den WebSocket-Verkehr von Collabora weiterleiten. Die Proxy-Anleitung von Collabora zeigt die entsprechenden Speicherorte für Browser-Ressourcen, Discovery, Capabilities, die wichtigsten WebSocket-Verbindungen, Download-/Upload-Pfade und den Admin-WebSocket an. Die folgende Konfiguration folgt dieser Struktur und fügt zusätzlich die üblichen weitergeleiteten Header hinzu:

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

Die WebSocket-Header sind nicht rein kosmetischer Natur. Die offizielle Nginx-Dokumentation erklärt, dass Upgradees Connectionsich um Hop-by-Hop-Header handelt, die für Reverse-Proxying von WebSockets explizit übergeben werden müssen. Siehe Nginx WebSocket-Proxying . Die Dokumentation des Standard-Proxy-Moduls behandelt ebenfalls die Header ` <WebSocketHeader>` proxy_set_header, proxy_pass`<WebSocketHeader>` und `<WebSocketHeader> proxy_read_timeout`: ngx_http_proxy_module .

Schritt 4: Nginx vor dem Neuladen validieren

Testen Sie die Nginx-Konfiguration, bevor Sie eine funktionierende Konfiguration ersetzen:

sudo nginx -t

Nur neu laden, wenn der Syntaxtest erfolgreich ist:

sudo systemctl reload nginx

Prüfen Sie anschließend, ob Nginx selbst das lokale Collabora-Backend erreichen kann. Bei einer Konfiguration auf demselben Host ist folgender Test hilfreich:

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

Die genauen Antwort-Header können je nach Collabora-Version variieren, das entscheidende Ergebnis ist jedoch, dass die TCP-Verbindung erfolgreich hergestellt wird und der Endpunkt antwortet, anstatt einen Timeout zu verursachen oder die Verbindung abzulehnen. Schlägt diese lokale Anfrage fehl, behebt eine Änderung der öffentlichen TLS-Einstellungen nicht das zugrunde liegende Container- oder Netzwerkproblem.

Schritt 5: Überprüfen Sie den öffentlichen HTTPS-Endpunkt

Von einem Client, der den öffentlichen Hostnamen auflöst, wird der Discovery-Endpunkt über Nginx angefordert:

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

Eine Browseranfrage https://office.example.com/hosting/discoverysollte XML zurückgeben. Dies ist eine bessere Funktionsprüfung als die Verwendung der Stamm-URL, da das Verhalten der Stammseite nicht dem Hauptvertrag von WOPI entspricht und je nach Version variieren kann.

Überprüfen Sie außerdem die Zertifikatskette mit Ihrem Browser oder einem TLS-Diagnosetool. Der Hostname sollte mit dem Zertifikat übereinstimmen, die Kette sollte vertrauenswürdig sein und es sollten keine Warnungen wegen gemischter Inhalte auftreten, die dadurch verursacht werden, dass Collabora dem Browser unverschlüsselte HTTP-URLs übermittelt.

Schritt 6: Testen Sie ein echtes Dokument und den WebSocket

Eine erfolgreiche Erkennung ist notwendig, aber nicht ausreichend. Öffnen Sie ein Dokument von Ihrem WOPI-Host und lassen Sie es lange genug geöffnet, um die Live-Sitzung zu testen. In den Entwicklertools Ihres Browsers sollte die Collabora-WebSocket-Anfrage erfolgreich aktualisiert werden, anstatt wiederholt die Verbindung herzustellen oder einen 400/502-Fehler zurückzugeben. Eine funktionierende Sitzung sollte es Ihnen ermöglichen, das Dokument zu bearbeiten, zu speichern und erneut zu öffnen.

Lädt die Editor-Shell, das Dokument aber kurz darauf nicht, sollten Sie den WebSocket-Pfad, das Proxy-Timeout, die WOPI-Zulassungsliste und das Verhalten des Host-Headers priorisieren. Falls die Nginx-Logs einen Upstream-Verbindungsfehler anzeigen, bevor eine WebSocket-Verbindung hergestellt wird, überprüfen Sie zuerst den Listener und die Image-Version von CODE.

Wie man häufige Fehlerarten diagnostiziert

502 Bad Gateway

Ein 502-Fehler bedeutet in der Regel, dass Nginx keine gültige Antwort vom konfigurierten Upstream-Server erhalten konnte. Prüfen Sie, ob CODE tatsächlich auf Port 9980 lauscht und ob Sie das korrekte Upstream-Protokoll verwenden. Im vorgesehenen SSL-Terminierungsdesign erfolgt die Kommunikation zwischen Proxy und CODE über HTTP. Falls eine Image-Regression dazu führt, dass CODE trotz Ihrer Flags intern weiterhin HTTPS ausliefert, decken Logs und ein direkter curlTest die Diskrepanz auf. Wechseln Sie nicht dauerhaft zu einem HTTPS-Upstream-Server, nur um eine unerklärliche Konfigurationsregression zu kaschieren; überprüfen Sie zunächst das Verhalten des exakten CODE-Images, das Sie verwenden.

Die Dokumentensuche funktioniert, aber die Dokumente lassen sich nicht öffnen.

Dies deutet häufig eher auf WebSocket-Weiterleitung oder WOPI-Autorisierung als auf TLS selbst hin. Überprüfen Sie die /cool/.../wsRoute, die Upgrade-Header und den Host, den Sie als WOPI-Quelle zugelassen haben. Collabora kann über HTTPS einwandfrei erreichbar sein und dennoch eine Bearbeitungssitzung ablehnen oder zum Fehlschlagen bringen.

URLs mit gemischten Inhalten oder fehlerhaftem Schema

Wenn ein Browser eine HTTPS-Seite sieht, die auf HTTP-Ressourcen verweist, überprüfen Sie ssl.termination=trueden weitergeleiteten Schema-Header und den Servernamen. Die öffentliche Seite der Bereitstellung muss sich stets als HTTPS identifizieren, auch wenn die private Verbindung über HTTP läuft.

Der Container meldet einen fehlerhaften Zustand, obwohl die Bearbeitung funktioniert.

Die kürzlich veröffentlichten Versionen 26.04 führten ein geändertes Verhalten der Integritätsprüfung im Zuge der Umstellung auf Distributionless-Images ein. Collabora hat einen Fall dokumentiert, in dem die Prüfung eine HTTP-Backend-Konfiguration hinter TLS-Terminierung nicht berücksichtigte. Falls Funktionstests erfolgreich sind, die Docker-Integritätsprüfung jedoch unerwartet einen roten Status anzeigt, prüfen Sie bitte die versionsspezifische Problemhistorie, bevor Sie einen funktionierenden Proxy neu konfigurieren. Siehe CollaboraOnline/online Issue #16032 .

Wann sollte man ein anderes Design verwenden?

SSL-Terminierung auf Proxy-Seite ist dann sinnvoll, wenn der Reverse-Proxy und Collabora über eine vertrauenswürdige lokale Schnittstelle oder ein isoliertes privates Netzwerk kommunizieren. Falls der Datenverkehr zwischen Nginx und CODE ein nicht vertrauenswürdiges Netzwerk durchläuft, erfüllt unverschlüsseltes HTTP auf der internen Schnittstelle möglicherweise nicht Ihre Sicherheitsanforderungen. Verwenden Sie in diesem Fall auch für den Backend-Verkehr TLS oder platzieren Sie beide Dienste in einem geschützten Netzwerk, in dem das Abfangen von Datenverkehr keine realistische Bedrohung darstellt.

Wenn Sie bereits einen plattformverwalteten Ingress betreiben, der Zertifikate, Routing und WebSockets korrekt handhabt, bringt das Hinzufügen einer zweiten Nginx-Schicht nur für Collabora kaum Vorteile. Die richtige Architektur bietet Ihnen eine einzige, transparente TLS-Schnittstelle ohne unnötige Zwischenschritte.

Checkliste zur abschließenden Validierung

• Der Collabora-Hostname wird zum Reverse-Proxy aufgelöst.
• Port 443 stellt ein vertrauenswürdiges Zertifikat für diesen Hostnamen bereit.
• Der Code wird nicht unnötigerweise über Port 9980 im öffentlichen Internet zugänglich gemacht.
• ssl.enable=falseund ssl.termination=truewerden für das HTTP-Backend-Design angewendet.
• Nginx kann CODE über seine private Adresse erreichen.
• /hosting/discoveryantwortet über die öffentliche HTTPS-URL.
• Das /cool/.../wsWebSocket-Upgrade war erfolgreich.
• Ein echtes Dokument wird geöffnet, bearbeitet, gespeichert und wieder geöffnet.
• Sie haben die exakte CODE-Image-Version, die Sie einsetzen möchten, festgelegt und getestet.

Wenn alle diese Prüfungen erfolgreich sind, funktioniert die SSL-Terminierung einwandfrei: Der externe Datenverkehr ist durch HTTPS geschützt, Collabora erkennt die öffentliche Verbindung als sicher und der Bearbeitungspfad bleibt funktionsfähig. Schlägt eine Prüfung fehl, beheben Sie das Problem auf dieser Ebene, anstatt mehrere Teile des Protokolls gleichzeitig zu ändern.