Docker 및 Nextcloud를 사용하여 Collabora Online CODE를 설치하는 방법

예시: 소규모 팀의 Nextcloud 파일이 에 호스팅되어 있다고 가정해 보겠습니다 https://cloud.example.com. 관리자는 별도의 Collabora Online Development Edition(CODE) 서버를 에 구축하고자 합니다 https://office.example.com. 이는 실제 설치 사례가 아니라, 단계별 설명을 위한 가상의 설정입니다. 예시의 호스트 이름은 실제 사용하시는 도메인으로 바꿔주시기 바랍니다.

CODE는 Nextcloud와는 별도의 서비스로 실행됩니다. Docker가 Collabora 서비스를 시작하고, TLS 리버스 프록시가 이를 공개하며, Nextcloud Office 통합 기능이 두 서비스를 연결합니다. 사용자의 브라우저는 공개된 Office URL에 접속할 수 있어야 하며, 서버는 관련 Nextcloud 및 Collabora 엔드포인트에 접속할 수 있어야 합니다. 현재 Nextcloud Office 설치 설명서에서는 Docker를 배포 옵션 중 하나로 설명하고 있으며, 전용 서버에는 일반적으로 리버스 프록시가 필요하다고 명시하고 있습니다.

시작하기 전에

예시를 위해, Linux 호스트에서 Docker를 실행할 수 있고, Nextcloud가 이미 HTTPS를 통해 작동하며, 두 호스트 이름 모두에 대한 DNS 레코드가 올바른 서버를 가리킨다고 가정합니다. 유효한 TLS 인증서를 발급받으세요 office.example.com. Collabora 서비스를 Docker 포트를 직접 인터넷에 개방하는 대신, 해당 호스트 이름을 통해 노출할 계획입니다.

• CODE 호스트가 를 확인하고 연결할 수 있는지 확인하십시오 cloud.example.com.
• https://office.example.com브라우저가 HTTPS에 접속할 수 있는지 확인하십시오 .
• 리버스 프록시를 Docker 호스트에서 실행할지 아니면 다른 곳에서 실행할지 선택하세요. 동일 호스트에서 실행되는 프록시는 루프백으로 공개된 컨테이너 포트를 사용할 수 있습니다. 다른 컨테이너에서 실행되는 프록시는 접근 가능한 공유 Docker 네트워크 또는 다른 개인 경로가 필요합니다.
• 실제 운영 환경에서 사용하기 전에 최신 CODE 및 Nextcloud 문서를 참조하여 호환성 및 프록시 요구 사항을 확인하십시오. CODE는 개발자용 에디션입니다. 벤더에서 지원하는 안정성 또는 지원이 필요한 팀은 지원되는 Collabora Online 제품을 검토해야 합니다.

아래 명령어는 공식 이미지 이름과 단일 Nextcloud 오리진을 사용합니다 . 예제에서는 릴리스 태그를 고정하지 않으므로 관리자는 이를 프로덕션 변경 관리 전략으로 collabora/code간주하기보다는 버전 관리 및 업데이트 정책을 결정해야 합니다 .latest

1. 사무실 호스트 이름을 서버로 지정하세요.

Collabora를 서비스하는 호스트 또는 로드 밸런서를 가리키는 DNS A 또는 AAAA 레코드를 생성하십시오 office.example.com. 리버스 프록시가 해당 이름에 유효한 인증서로 HTTPS 연결을 종료하고 Collabora 애플리케이션 경로 및 WebSocket 트래픽을 CODE 컨테이너로 전달하도록 구성하십시오. Collabora의 공식 리버스 프록시 설명서에는 프록시별 예제가 제공되므로, 실제 프록시 소프트웨어 및 현재 CODE 릴리스에 맞는 섹션을 참조하십시오.

일반적인 프록시 코드 조각을 맹목적으로 복사하지 마십시오. 프록시는 WebSocket 업그레이드를 지원하고, 필수 호스트 및 전달 프로토콜 정보를 유지하며, Collabora 경로(예: `/etc/colabora/example.com`, `/etc/colabora/example.com`, `/etc/colabora/example.com`)를 전달해야 합니다 . /browser정확한 지시문은 Apache, NGINX, Traefik 및 기타 게이트웨이에 따라 다릅니다. 프록시가 Docker 호스트에서 실행되는 경우 `/etc/colabora/example.com`으로 포워딩하는 것이 일반적인 비공개 대상입니다. 별도의 컨테이너에서 실행되는 경우 해당 루프백 주소는 CODE 호스트가 아닌 프록시 컨테이너 자체를 가리킵니다./hosting/discovery/cool127.0.0.1:9980

2. CODE Docker 컨테이너를 시작합니다.

Docker 호스트에서 컨테이너를 풀(pull)하고 시작합니다. 이 예제에서는 포트가 루프백에 바인딩되어 있으므로 호스트의 모든 네트워크 인터페이스에 직접 노출되지 않습니다.

docker pull collabora/code

docker run -d --name collabora   -p 127.0.0.1:9980:9980   -e 'aliasgroup1=https://cloud.example.com:443'   --restart always   --cap-add MKNOD   collabora/code

이 aliasgroup1값은 이 CODE 서비스를 사용할 것으로 예상되는 Nextcloud 오리진에 대한 권한을 부여합니다. 스키마와 호스트 이름은 사용자가 Nextcloud에 액세스하는 데 사용하는 URL과 일치해야 하며, 공개 Nextcloud 서비스에서 기본값이 아닌 포트를 사용하는 경우 해당 포트를 포함해야 합니다. 여러 Nextcloud 인스턴스가 이 서비스를 사용할 경우, 임의의 호스트를 광범위하게 허용하는 대신 현재 CODE 이미지 문서에 따라 추가 허용 호스트 그룹을 구성하십시오.

이 명령은 리버스 프록시가 동일한 머신에 있고 루프백 포트로 포워딩한다고 가정합니다. Docker Compose, 컨테이너화된 프록시 또는 원격 프록시를 사용하는 경우 네트워킹 및 포트 노출 설정을 신중하게 조정해야 합니다. 프록시 연결이 작동하도록 포트 9980을 공개적으로 노출하지 마십시오. 개인 Docker 네트워크, 방화벽 규칙 또는 기타 제한된 경로를 사용하십시오. CODE Docker 이미지의 최신 옵션에 대한 자세한 내용은 Collabora의 CODE Docker 가이드를 참조하십시오 .

3. 리버스 프록시를 구성하고 코드를 확인하세요.

프록시 설정이 완료되면 사용 중인 소프트웨어에 맞는 방법으로 프록시를 다시 로드하고, 변경 사항을 적용하기 전에 구성을 확인하십시오. 그런 다음 도메인에 연결할 수 있는 컴퓨터에서 공개 검색 엔드포인트를 요청하십시오.

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

성공적인 응답에는 프록시 오류 페이지 대신 XML 검색 정보가 포함되어야 합니다. 이 검사는 공개 URL이 Collabora 엔드포인트에 도달하는지 확인하는 것이며, Nextcloud 인증, WebSocket 또는 문서 편집 기능이 아직 작동한다는 것을 증명하는 것은 아닙니다. 엔드포인트 검사에 실패할 경우 컨테이너도 검사해야 합니다.

docker ps --filter name=collabora
docker logs --tail=100 collabora

가상 환경에서 공용 URL에 대한 연결이 거부되면 DNS, TLS, 방화벽 또는 프록시 라우팅 문제일 가능성이 높습니다. 502 응답은 일반적으로 프록시가 컨테이너에 구성된 업스트림에 연결할 수 없음을 의미합니다. 검색은 정상적으로 작동하지만 이후 에디터 로딩 중에 오류가 발생하는 경우, WebSocket 포워딩 설정과 프록시에서 업그레이드 오류 또는 업스트림 오류가 보고되는지 확인하십시오.

4. Nextcloud를 Collabora에 연결

Nextcloud에서 앱 영역을 열고 사용 중인 버전에 맞는 오피스 통합 기능을 설치하거나 활성화하세요. 앱 이름은 릴리스 및 설치된 앱 카탈로그에 따라 "Nextcloud Office" 또는 "Collabora Online"일 수 있습니다. 그런 다음 Office 관리 설정을 열고 다음 단계를 따르세요.

https://office.example.com

설정을 저장하고 연결 상태를 확인하십시오. Nextcloud Office 구성 설명서에서는 이 필드를 Collabora 서버의 URL 및 포트로 정의하고 HTTPS 사용을 권장합니다. 브라우저에서 접속 가능한 공개 Collabora URL을 사용하십시오. 분할 DNS, NAT 또는 분할 네트워크 설치 환경에서는 Nextcloud에 해당 서비스에 대한 내부 경로가 필요할 수 있습니다. 서버에서 공개 DNS가 작동한다고 가정하지 말고 설치된 앱 버전의 고급 연결 옵션을 참조하십시오.

예시에서 Nextcloud는 cloud.example.com허용된 WOPI 호스트를 로 인식하고, 사용자의 브라우저는 해당 주소에서 편집기를 엽니다 office.example.com. Nextcloud 관리 페이지에 WOPI 요청 허용 목록이 있는 경우, 네트워크에서 정확한 주소를 확인한 후 예상되는 Collabora 서버 주소로 제한하십시오. Nextcloud는 WOPI 요청을 예상되는 Collabora 호스트로 제한할 것을 권장합니다. 특정 네트워크상의 이유 없이 광범위한 범위를 추가하지 마십시오.

5. 샘플 문서로 테스트해 보세요.

일반 Nextcloud 사용자 계정으로 로그인하고, 간단한 텍스트 문서를 작성하거나 임시 테스트 파일을 열어 브라우저 편집기를 선택하세요. 편집기 도구 모음이 로드되는지 확인하고, 간단한 변경을 수행한 후 저장 표시가 나타날 때까지 기다립니다. 파일을 닫았다가 다시 열어 변경 사항이 저장되었는지 확인하세요. 동시 편집이 지원되는 설치 환경이라면, 동일한 테스트 파일을 두 번째 사용자 세션에서 열고 현재 상태 또는 편집 내용이 예상대로 업데이트되는지 확인하세요.

이러한 검사는 주요 계층을 구분합니다. 검색 요청 테스트는 공용 라우팅을 테스트하고, Nextcloud 상태 테스트는 구성된 서버 연결을 테스트하며, 편집기 열기 테스트는 브라우저 액세스 및 WOPI 교환을 테스트하고, 파일 다시 열기 테스트는 저장 경로를 테스트합니다. 첫 번째 테스트에는 중요한 문서를 사용하지 마십시오. CODE는 개발 버전이므로 테스트 성공 여부가 조직의 가용성, 리소스 용량, 백업 및 지원 요구 사항 평가를 대체할 수 없습니다.

흔히 발생하는 문제 및 점검 사항

Nextcloud에서 서버에 연결할 수 없다고 보고합니다.

Office URL에 오타가 없는지, 유효한 인증서 체인인지, HTTPS 스키마가 일치하는지 확인하십시오. 브라우저와 Nextcloud 호스트 모두에서 검색 URL을 테스트하십시오. 서버 네트워크 내부에서 공용 DNS 확인이 다르게 되는 경우, 적절한 내부 경로를 구성하거나 커넥터에서 지원하는 고급 서버 URL 설정을 사용하십시오.

페이지는 열리지만 문서 편집기가 멈춥니다.

리버스 프록시 액세스 및 오류 로그를 검사하여 WebSocket 업그레이드 실패 원인을 파악하십시오. 프록시가 현재 Collabora 경로를 전달하고 장기 WebSocket 연결을 유지하는지 확인하십시오. 브라우저 개발자 도구를 사용하면 WebSocket 요청이 거부되었는지, HTTP로 리디렉션되었는지, 또는 인증서 오류로 차단되었는지 확인할 수 있습니다.

Collabora가 Nextcloud 호스트를 거부했습니다.

스키마, 호스트 이름, 포트를 포함한 실제 Nextcloud 오리진 정보를 구성된 별칭 그룹과 비교하십시오. 공개 URL, 내부 호스트 이름, 프록시 재작성 설정이 일치하지 않으면 호스트 인증 또는 WOPI 오류가 발생할 수 있습니다. 허용된 구성에는 의도한 Nextcloud 호스트 이름만 추가하십시오.

코드가 시작되었다가 종료되거나 비정상 상태가 됩니다.

docker logs collabora배포한 이미지 태그에 대한 디스크 및 메모리 용량, 컨테이너 권한, 런타임 요구 사항을 검토하십시오 . 현재 사용 환경에 대한 공식 지침에서 요구하지 않는 한, 권한 모드와 같은 플래그를 관련 없는 예제에서 복사하지 마십시오.

업데이트 및 운영 관리

보안 및 호환성을 위해 컨테이너 이미지를 최신 상태로 유지하되, 업무 시간 중에 검토되지 않은 새 이미지를 가져오는 대신 업그레이드 일정을 예약하고 테스트하십시오. 사용 중인 버전을 기록하고 관련 릴리스 노트를 읽고 롤백 경로를 확보하십시오. Collabora 또는 Nextcloud의 주요 변경 사항 후에는 엔드포인트 및 WebSocket 요구 사항이 변경될 수 있으므로 프록시 구성을 검토하십시오. 또한 활성 편집자 수가 증가함에 따라 호스트의 메모리, CPU, 스토리지 및 컨테이너 로그를 모니터링하십시오.

가상의 팀에게 있어, 설치 후 제한적인 사용을 위해서는 검색 엔드포인트가 응답하고, Nextcloud가 연결을 보고하고, 샘플 문서가 브라우저에서 열리고, 저장된 편집 내용이 다시 열었을 때도 유지되어야 합니다. 이러한 검사 중 하나라도 실패하면, 사용자가 서비스를 이용하기 전에 해당 부분을 먼저 해결해야 합니다.

공식 참고 자료

• Nextcloud 35 관리 설명서: Office 설치
• Nextcloud 관리 설명서: Docker 설치 예시 및 Apache 프록시 경로
• Nextcloud 35 관리 설명서: Office 구성 및 WOPI 안내
• Collabora Online: CODE Docker 이미지
• Collabora Online: 리버스 프록시 설정

본 문서는 2026년 10월 6일에 검토되었습니다. Nextcloud의 안정 버전 매뉴얼은 확인 당시 35 버전으로 표시되어 있었지만, 링크된 Docker 설치 가이드는 28 버전입니다. 따라서 해당 가이드를 설치 예시로 활용하시고, 프록시 구문은 Collabora 가이드 및 실제로 사용 중인 버전과 비교하여 확인하십시오.