CODE Docker를 사용하여 10분 만에 Nextcloud Office를 설정하는 방법

2026년 최신 참고 사항: Nextcloud 35 문서에서는 Euro-Office 기반의 Nextcloud Office 와 Collabora Online 을 구분하고 있습니다 . Collabora Online은 여전히 ​​지원되는 대안이며 공식 CODE Docker 이미지를 사용하여 자체 호스팅할 수 있습니다. 이 가이드에서는 외부 Collabora/CODE 경로를 사용합니다. 명칭이 중요한 이유는 이전 가이드에서 CODE를 마치 "Nextcloud Office" 뒤에 있는 유일한 서버인 것처럼 설명하는 경우가 있었기 때문입니다. 이전 버전을 기준으로 작성된 지침을 적용하기 전에 최신 Nextcloud Office 개요를 참조하십시오.

Nextcloud 사이트가 이미 HTTPS를 사용하고 있고, Docker가 설치되어 있으며, Collabora에 필요한 DNS 이름이 office.example.com준비되어 있다면 통합 자체는 약 10분 안에 완료될 수 있습니다. DNS 전파, 인증서 발급, 방화벽 변경 또는 리버스 프록시 문제 해결에는 더 많은 시간이 소요될 수 있으며, 이러한 작업은 예상 시간에 포함되지 않습니다.

시작하기 전에 필요한 것

빠른 설치 방법은 기존 Nextcloud 인스턴스 하나, Docker를 실행할 수 있는 Linux 호스트 하나, 그리고 CODE용 전용 HTTPS 호스트 이름이 필요하다고 가정합니다. Nextcloud의 최신 Docker 예제에서는 별도의 서브도메인과 유효한 TLS 인증서를 권장합니다. CODE는 내부적으로 9980 포트에서 수신 대기하며, 리버스 프록시를 통해 브라우저와 Nextcloud에 안전하게 노출됩니다.

• 다음과 같은 URL로 접속 가능한 정상 작동하는 Nextcloud 서버입니다 https://cloud.example.com.
• CODE를 실행할 호스트에 Docker Engine을 설치합니다.
• office.example.com리버스 프록시를 가리키는 DNS 레코드와 같은 것입니다 .
• 사무실 호스트 이름에 대한 유효한 HTTPS 인증서.
• Nextcloud에 대한 관리자 권한과 Docker 호스트에 대한 루트 또는 sudo 권한이 필요합니다.

Nextcloud의 최신 설치 문서에 따르면 내장된 CODE 서버는 개인 또는 소규모 팀 사용에 가장 적합하지만, 더 나은 성능을 위해서는 Collabora Online 전용 설치를 권장합니다. 아래에서 사용된 이미지는 Docker Hub의 공식 collabora/code 이미지 입니다.

1단계: CODE Docker 이미지를 다운로드합니다.

Docker 호스트에서 Docker가 사용 가능한지 확인하고 공식 이미지를 다운로드하십시오.

docker --version
docker pull collabora/code:latest

Collabora는 업데이트가 자주 게시되므로 이 latest태그는 간략한 설정 가이드에 유용합니다. 프로덕션 환경에서는 테스트를 거친 특정 버전을 고정하고, 재구축 중에 예기치 않은 이미지 변경이 발생하는 것을 방지하기 위해 계획적인 업그레이드를 예약하는 것이 좋습니다.

2단계: Nextcloud 호스트용 CODE를 시작하세요

현재 Nextcloud Docker 예제는 aliasgroup1CODE에게 어떤 Nextcloud 호스트가 통합될 수 있는지 알려줍니다. 예제 호스트 이름을 실제 Nextcloud URL로 바꾸세요.

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

리버스 프록시가 동일 서버에서 실행되는 경우, 바인딩을 통해 127.0.0.1포트 9980이 인터넷에 직접 노출되는 것을 방지할 수 있습니다. 프록시가 다른 머신에서 실행되는 경우, 프록시만 CODE에 접근할 수 있도록 네트워크 규칙을 설정해야 합니다. 단순히 포트 9980을 모든 사용자에게 공개하지 마십시오.

컨테이너가 실행 중인지 확인하세요:

docker ps --filter name=collabora-code
docker logs --tail 50 collabora-code

3단계: CODE 앞에 HTTPS와 리버스 프록시를 설치합니다.

Nextcloud는 Collabora에 필요한 경로를 /browser` /hosting/discovery/etc/ collabora/`, `/etc/collabora/`, `/etc/collabora/`로 명시하고 있으며, WebSocket 트래픽은 ` /hosting/capabilities/etc /cool/adminws/ collabora/` /cool아래에 있습니다 /cool/.../ws. 따라서 일반적인 "WebSocket을 제외한 모든 트래픽을 프록시"로 설정하면 편집기가 부분적으로 열렸다가 연결이 끊어지는 경우가 많습니다.

Nginx의 경우, 다음의 간략한 예제는 CODE의 기본 내부 HTTPS를 유지하고 공개 TLS 연결을 Nginx에서 종료합니다. 실제 인증서 경로는 사용자 환경에 맞게 사용하십시오.

server {
    listen 443 ssl http2;
    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 https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /hosting/discovery { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /hosting/capabilities { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
    location ^~ /cool/adminws { proxy_pass https://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_ssl_verify off; }
    location ~ ^/cool/(.*)/ws$ { proxy_pass https://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_ssl_verify off; }
    location ^~ /cool { proxy_pass https://127.0.0.1:9980; proxy_set_header Host $host; proxy_ssl_verify off; }
}

이는 의도적으로 최소한의 라우팅 예시일 뿐, 완벽한 Nginx 보안 기준선을 보여주는 것은 아닙니다. 내부 TLS를 비활성화한 상태로 CODE를 실행하는 경우, 업스트림이 변경되므로 http://127.0.0.1:9980컨테이너를 일관되게 구성해야 합니다. HTTP 프록시 대상과 HTTPS를 기대하는 CODE 컨테이너를 혼용하지 마십시오.

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

Nextcloud 설정을 변경하기 전에 브라우저에서 다음 URL을 여세요.

https://office.example.com/hosting/discovery

프록시 오류, 인증서 경고 또는 연결 실패 메시지 대신 WOPI 검색 XML을 수신해야 합니다. 명령줄에서도 테스트할 수 있습니다.

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

이 방법이 실패하면 DNS, TLS, 프록시 또는 컨테이너 문제를 먼저 해결하십시오. 문제가 있는 엔드포인트에 Nextcloud를 연결하는 것은 문제 해결 과정을 한 단계 더 복잡하게 만들 뿐입니다.

5단계: Nextcloud 오피스 통합을 활성화합니다.

관리자 권한으로 Nextcloud에 로그인하고, 앱을 열고 , Office 및 텍스트 로 이동 하여 설치에 사용 가능한 오피스 통합 앱을 활성화하세요. 현재 Nextcloud Collabora Docker 예제에서는 관리자에게 여전히 "Nextcloud Office" 앱을 설치한 다음 Office 관리 설정에서 외부 서버를 구성하도록 안내하고 있지만, Nextcloud 35 개요에서는 Euro-Office와 Collabora 제품이 명확하게 구분되어 있습니다.

Nextcloud 릴리스에서 사용하는 레이블이 약간 다를 경우, 이전 스크린샷과 정확히 일치한다고 가정하기보다는 관리 인터페이스에 표시된 제품 이름을 따르세요.

6단계: Nextcloud에서 외부 CODE 서버를 가리키도록 설정합니다.

관리 설정 → 오피스를 엽니다 . 외부 Collabora/오피스 서버 옵션을 선택하고 다음을 입력합니다.

https://office.example.com

설정을 저장하고 Nextcloud의 연결 확인을 기다리세요. Nextcloud는 양쪽에서 동일한 프로토콜(HTTPS 권장)을 사용할 것을 권장합니다. 연결 확인이 성공하면 Nextcloud가 Collabora 엔드포인트에 연결할 수 있다는 의미이지만, 실제 편집 세션 중에 모든 브라우저의 WebSocket 경로 및 WOPI 요청이 정상적으로 작동한다는 것을 보장하는 것은 아닙니다.

7단계: WOPI 요청 제한

기본 연결이 성공적으로 완료되면 WOPI 구성을 강화하십시오. Nextcloud의 최신 구성 가이드에서는 WOPI 요청을 파일 요청이 필요한 Collabora 서버의 IP 주소로 제한할 것을 강력히 권장합니다. 관리 설정 → 오피스 에서 'WOPI 요청 허용 목록 ' 필드를 활용하십시오 .

WOPI 흐름은 Collabora가 Nextcloud 사용자를 대신하여 문서를 검색하고 작성하는 방식이기 때문에 이는 중요한 보안 제어입니다. 배포 환경에 따라 실제 CODE 서버 경로를 나타내는 IP 주소 또는 네트워크를 사용하십시오. 서버 URL 필드와 유사해 보인다는 이유만으로 호스트 이름을 IP 허용 목록 필드에 붙여넣지 마십시오. 현재 사용 가능한 옵션은 Nextcloud의 Collabora 구성 및 WOPI 지침을 참조하십시오.

8단계: 실제 문서를 열고 저장을 확인합니다.

Nextcloud에서 간단한 ODT 또는 DOCX 파일을 생성하고, 파일을 열어 문장을 입력한 후 편집기를 닫고 다시 파일을 엽니다. 이렇게 하면 브라우저 → 공개 CODE 호스트 이름 → 리버스 프록시 → CODE → Nextcloud에 대한 WOPI 요청 → 스토리지에 저장이라는 전체 과정을 확인할 수 있습니다.

Office 설정 페이지에서 서버에 연결할 수 있다고 표시된다고 해서 설정이 완료된 것은 아닙니다. 정상적인 결과는 편집기가 연결 경고 없이 로드되고, 문서를 수정할 수 있으며, 저장된 변경 사항이 다시 열었을 때도 유지되는 것입니다. 편집기 셸은 로드되지만 편집 연결이 끊어지는 경우, 먼저 WebSocket /cool/.../ws연결 문제를 확인하십시오. 편집기에서 파일을 전혀 로드할 수 없는 경우, CODE 로그, Nextcloud 로그, 두 서버 간의 DNS 확인, 그리고 WOPI 허용 목록 규칙을 확인하십시오.

빠른 문제 해결 체크리스트

CODE를 최신 상태로 유지하면서 업그레이드로 인한 불편함을 방지하세요.

Collabora는 CODE 업데이트를 자주 게시합니다. 공식 Docker Hub 페이지에는 활발하게 관리되는 태그가 표시되며, Nextcloud의 업그레이드 지침에 따르면 Docker 배포는 최신 이미지를 가져와 컨테이너를 다시 생성하는 방식으로 업데이트됩니다. 개인용 서버의 경우 업데이트 추적이 latest어느 정도 효과적일 수 있습니다. 하지만 기업용의 경우, 검증된 태그를 고정하고, 릴리스 노트를 읽고, 구성을 백업한 다음, 유지 관리 기간 동안 업그레이드하는 것이 좋습니다.

또한 CODE의 범위를 염두에 두어야 합니다. Docker Hub에서는 CODE를 가정 사용자를 위한 개발 버전으로 설명하고 있는 반면, Nextcloud 문서에서는 더 큰 규모 또는 안정성이 중요한 배포에는 지원되는 엔터프라이즈 옵션을 권장하고 있습니다. 10분 만에 Docker를 설정할 수 있는 것은 개인 클라우드, 연구실 또는 소규모 팀에는 적합하지만, 용량 계획, 모니터링, 백업 또는 엔터프라이즈 지원을 대체할 수는 없습니다.

최종 결과

컨테이너가 실행되고, HTTPS 프록싱이 올바르게 작동하고, /hosting/discovery응답하고, Nextcloud 통합이 제대로 연결되고 https://office.example.com, WOPI가 제한되고, 실제 문서가 열리고 저장되면 통합이 완료됩니다. 가장 중요한 것은 명령어의 개수가 아니라 네트워크 경로의 일관성을 유지하는 것입니다. Nextcloud, CODE, 리버스 프록시, 그리고 사용자의 브라우저는 모두 올바른 WebSocket 및 WOPI 경로를 통해 예상되는 HTTPS 호스트 이름에 접근할 수 있어야 합니다.