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"

YOUR_TESTED_TAG프로덕션 환경과 유사한 배포에 안전 하다고 자동으로 가정하는 대신, 검증된 버전으로 교체하십시오 latest. 또한 통합에 적합한 WOPI 호스트 또는 별칭 설정을 구성하십시오. 이러한 값은 Nextcloud, ownCloud, 다른 WOPI 호스트 또는 사용자 지정 통합에 연결하는지에 따라 달라집니다.

컨테이너를 시작한 후, 컨테이너가 실행 중인지, 그리고 포트 매핑이 의도한 경계와 일치하는지 확인하십시오.

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

26.04 배포용 버전 노트

현재 26.04 이미지 문제를 해결할 때 두 개의 SSL 플래그를 유일한 변수로 간주하지 마십시오. 2026년 중반, Collabora는 배포판이 없는 Docker 이미지와 SSL이 비활성화된 구성에서 발생하는 회귀 문제를 추적했습니다. 공식 GitHub 이슈에는 26.04 시작 회귀 문제가 기록되어 있으며, Collabora 커뮤니티의 후속 보고에 따르면 영향을 받았던 SSL 종료 동작이 이후 버전인 26.04.2.4.1 이미지에서 다시 정상적으로 작동하는 것으로 나타났습니다. 이미지 업그레이드 직후 이전에 정상적으로 작동하던 종료 구성이 제대로 작동하지 않는 경우 CollaboraOnline/online 이슈 #16019를 검토하십시오.

이는 이미지 버전을 고정하고 테스트해야 하는 또 다른 이유입니다. Nginx에서 구성 오류와 컨테이너 이미지 회귀는 유사하게 나타날 수 있습니다. 둘 다 502 응답이나 업스트림 연결 실패로 표시될 수 있습니다.

3단계: Collabora 경로에 대한 TLS 종료 및 프록시를 설정하도록 Nginx 구성

Nginx는 Collabora 호스트 이름에 대한 유효한 인증서가 필요하며 Collabora의 HTTP 엔드포인트와 WebSocket 트래픽을 포워딩해야 합니다. Collabora의 프록시 가이드에는 브라우저 자산, 검색, 기능, 주요 WebSocket 연결, 다운로드/업로드 경로 및 관리자 WebSocket에 대한 전용 위치가 나와 있습니다. 다음 구성은 해당 구조를 따르면서 공통으로 전달되는 헤더를 추가합니다.

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

WebSocket 헤더는 단순히 보기 위한 것이 아닙니다. Nginx 공식 문서에 따르면 ` http`와 `http`는 홉별 헤더이며, 리버스 프록시를 사용하는 WebSocket 연결에는 명시적으로 전달해야 합니다. 자세한 내용은 Nginx WebSocket 프록싱 문서를 참조하십시오 Upgrade. 표준 프록시 모듈 문서( ngx_http_proxy_module )에서도 `http` , `http`, `http` 헤더에 대해 다룹니다 .Connectionproxy_set_headerproxy_passproxy_read_timeout

4단계: 재시작 전 Nginx 유효성 검사

이미 정상적으로 작동 중인 Nginx 구성을 교체하기 전에 먼저 해당 구성을 테스트하십시오.

sudo nginx -t

구문 테스트가 성공한 경우에만 다시 로드하세요.

sudo systemctl reload nginx

다음으로 Nginx 자체에서 로컬 Collabora 백엔드에 연결할 수 있는지 확인하십시오. 동일 호스트 설정에서는 다음과 같은 확인 방법이 유용합니다.

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

정확한 응답 헤더는 Collabora 릴리스 버전에 따라 다를 수 있지만, 핵심 결과는 TCP 연결이 성공하고 엔드포인트가 시간 초과 또는 연결 거부 대신 응답한다는 것입니다. 이 로컬 요청이 실패하는 경우 공용 TLS 설정을 변경해도 근본적인 컨테이너 또는 네트워크 문제는 해결되지 않습니다.

5단계: 공개 HTTPS 엔드포인트를 확인합니다.

공용 호스트 이름을 확인할 수 있는 클라이언트에서 Nginx를 통해 검색 엔드포인트를 요청합니다.

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

브라우저 요청은 https://office.example.com/hosting/discoveryXML을 반환해야 합니다. 이는 루트 URL에 의존하는 것보다 더 나은 기능 검증 방법입니다. 왜냐하면 루트 페이지의 동작은 WOPI의 주요 계약이 아니며 버전에 따라 다를 수 있기 때문입니다.

또한 브라우저 또는 TLS 진단 도구를 사용하여 인증서 체인을 검사하십시오. 호스트 이름이 인증서와 일치해야 하고, 체인이 신뢰할 수 있어야 하며, Collabora가 브라우저에 일반 HTTP URL을 제공하여 발생하는 혼합 콘텐츠 경고가 없어야 합니다.

6단계: 실제 문서와 웹소켓을 테스트합니다.

연결 성공은 필수 조건이지만 충분조건은 아닙니다. 실제 WOPI 호스트에서 문서를 열고 라이브 세션이 제대로 작동하는지 확인하기 위해 충분한 시간 동안 열어 두십시오. 브라우저 개발자 도구에서 Collabora WebSocket 요청이 반복적으로 재연결되거나 400/502 오류를 반환하는 대신 성공적으로 연결되어야 합니다. 정상적인 세션에서는 문서를 입력하고 저장한 후 다시 열 수 있어야 합니다.

에디터 셸이 로드되지만 곧바로 문서 로드에 실패하는 경우, WebSocket 경로, 프록시 타임아웃, WOPI 허용 목록 및 호스트 헤더 동작을 우선적으로 확인하십시오. Nginx 로그에 WebSocket 연결이 설정되기 전에 업스트림 연결 오류가 표시되는 경우, CODE의 리스너와 이미지 버전을 먼저 확인하십시오.

일반적인 고장 원인 진단 방법

502 배드 게이트웨이

502 오류는 일반적으로 Nginx가 구성된 업스트림에서 유효한 응답을 받지 못했음을 의미합니다. CODE가 실제로 9980 포트에서 수신 대기 중인지, 그리고 올바른 업스트림 프로토콜을 사용하고 있는지 확인하십시오. 의도된 SSL 종료 설계에서는 프록시에서 CODE로의 홉은 HTTP입니다. 이미지 오류로 인해 플래그 설정에도 불구하고 CODE가 내부적으로 HTTPS를 계속 사용하는 경우, 로그 및 직접 curl테스트를 통해 불일치를 확인할 수 있습니다. 설명할 수 없는 구성 오류를 숨기기 위해 업스트림을 HTTPS로 영구적으로 전환하지 마십시오. 먼저 실행 중인 정확한 CODE 이미지의 동작을 확인하십시오.

검색 기능은 작동하지만 문서가 열리지 않습니다.

이 문제는 TLS 자체보다는 WebSocket 포워딩이나 WOPI 인증과 관련이 있는 경우가 많습니다. 경로 /cool/.../ws, 업그레이드 헤더, 그리고 WOPI 소스로 허용한 호스트를 확인하십시오. Collabora는 HTTPS를 통해 완벽하게 접속 가능한 상태에서도 편집 세션이 거부되거나 실패할 수 있습니다.

혼합 콘텐츠 또는 잘못된 스키마 URL

브라우저가 HTTP 리소스를 참조하는 HTTPS 페이지를 발견하면 ssl.termination=true전달된 스키마 헤더와 서버 이름을 확인하십시오. 배포 환경의 공개 측은 비공개 홉이 HTTP이더라도 일관되게 HTTPS임을 나타내야 합니다.

편집 기능은 정상적으로 작동하지만 컨테이너 상태가 비정상으로 보고됩니다.

최근 26.04 릴리스에서는 distroless-image 전환 과정에서 변경된 상태 확인 동작이 도입되었습니다. Collabora는 프로브가 TLS 종료 뒤에 있는 HTTP 백엔드 구성을 제대로 처리하지 못하는 사례를 추적했습니다. 기능 테스트는 통과했지만 Docker 상태가 예기치 않게 빨간색으로 표시되는 경우, 작동하는 프록시를 재설계하기 전에 릴리스별 문제 기록을 확인하십시오. CollaboraOnline/online 이슈 #16032를 참조하세요 .

다른 디자인을 사용해야 하는 시점은 언제일까요?

리버스 프록시와 Collabora가 신뢰할 수 있는 로컬 인터페이스 또는 격리된 사설 네트워크를 통해 통신하는 경우 프록시 측 SSL 종료가 적합합니다. Nginx와 CODE 간의 트래픽이 신뢰할 수 없는 네트워크를 통과하는 경우 내부 홉에서 일반 HTTP를 사용하는 것은 보안 요구 사항을 충족하지 못할 수 있습니다. 이 경우 백엔드에도 TLS를 사용하거나 두 서비스를 모두 가로채기 위험이 없는 보호된 네트워크에 배치해야 합니다.

마찬가지로, 이미 인증서, 라우팅 및 웹소켓을 올바르게 처리하는 플랫폼 관리형 인그레스를 운영하고 있다면 Collabora만을 위해 두 번째 Nginx 계층을 추가하는 것은 큰 이점이 없습니다. 올바른 아키텍처는 불필요한 홉 없이 단일하고 관찰 가능한 TLS 경계를 제공하는 것입니다.

최종 검증 체크리스트

• Collabora 호스트 이름은 리버스 프록시로 확인됩니다.
• 포트 443은 해당 호스트 이름에 대한 신뢰할 수 있는 인증서를 제공합니다.
• CODE는 9980번 포트를 통해 불필요하게 공용 인터넷에 노출되지 않습니다.
• ssl.enable=false그리고 ssl.termination=trueHTTP 백엔드 설계에 적용됩니다.
• Nginx는 CODE의 개인 IP 주소로 접속할 수 있습니다.
• /hosting/discovery공개 HTTPS URL을 통해 응답합니다.
• WebSocket /cool/.../ws업그레이드가 성공적으로 완료되었습니다.
• 실제 문서는 열고, 편집하고, 저장하고, 다시 엽니다.
• 배포하려는 정확한 CODE 이미지 버전을 고정하고 테스트했습니다.

위의 모든 검사를 통과하면 SSL 종료가 제대로 작동하는 것입니다. 즉, 외부 트래픽은 HTTPS로 보호되고, Collabora는 공용 연결을 안전한 것으로 인식하며, 편집 경로는 계속 작동합니다. 검사 중 하나라도 실패하면 스택의 여러 부분을 한 번에 변경하기보다는 해당 계층에서 문제를 해결하십시오.