Docker Compose를 사용하여 ONLYOFFICE Docs Enterprise를 설치하는 방법

ONLYOFFICE Docs Enterprise는 공식 Docker-DocumentServer저장소를 사용하여 Docker Compose 배포로 실행할 수 있습니다. 핵심은 Enterprise 전용 Compose 파일을 생성한 다음, 영구 저장소, 안정적인 JWT 비밀 키, 라이선스 파일을 설정하여 서버를 프로덕션 환경으로 전환하는 것입니다. 이렇게 하면 온라인 편집 서비스인 Docs가 설치되며, ONLYOFFICE Workspace 포털 전체가 설치되는 것은 아닙니다.

아래 단계는 2026년 10월 6일 ONLYOFFICE의 엔터프라이즈 Docker 가이드 및 공식 저장소를 기준으로 확인되었습니다. 저장소의 기본 브랜치는 변경될 수 있으므로 장기간 사용할 서버의 경우 승인된 릴리스 또는 태그를 체크아웃하고 해당 버전을 배포 기록과 함께 보관하십시오.

빠른 요구 사항 체크리스트

ONLYOFFICE의 최신 엔터프라이즈 가이드에는 이러한 호스트 요구 사항이 명시되어 있습니다. 용량 요구 사항은 동시 사용자 수, 문서 복잡성 및 통합 기능에 따라 증가하므로 공급업체의 기본 요구 사항은 용량 보장치가 아닌 시작점으로 간주해야 합니다.

1. Docker Compose를 설치하고 공식 배포 파일을 다운로드하세요.

Docker 패키지 저장소를 통해 Debian 또는 Ubuntu에 Docker Engine이 이미 설치되어 있는 경우 다음 명령으로 Compose 플러그인을 설치하십시오.

sudo apt-get update
sudo apt-get install docker-compose-plugin
docker compose version

다른 Linux 배포판의 경우 해당 배포판에 대한 Docker의 최신 설치 지침을 따르십시오. 현재 플러그인은 간격이 있는 명령어를 사용합니다 docker compose. 이전의 독립 실행형 명령어는 docker-compose하위 호환성을 위해 유지 관리되며 여기에 표시된 ONLYOFFICE Enterprise 명령어에서 사용하는 경로가 아닙니다.

ONLYOFFICE 저장소를 복제하고 해당 디렉터리로 이동합니다. 변경 관리 정책에 따라 고정 버전이 필요한 경우, 복제 후 파일을 편집하기 전에 승인된 릴리스 태그를 체크아웃하십시오.

git clone https://github.com/ONLYOFFICE/Docker-DocumentServer.git
cd Docker-DocumentServer
# Optional: select the approved release tag for your deployment
git checkout <release-tag>

체크아웃한 리비전에 가 포함되어 있는지 확인하십시오 . 이 저장소에 있는 커뮤니티 에디션 Compose 파일인 로 docker-compose.enterprise.yml대체하지 마십시오 .docker-compose.yml

2. 비밀 키, 데이터 저장 위치 및 라이선스를 준비하십시오.

처음 시작하기 전에 설정을 확인하십시오 docker-compose.enterprise.yml. 현재 공식 파일에서 애플리케이션과 PostgreSQL 서비스는 샘플 데이터베이스 암호를 사용하고 있으며, JWT 관련 줄은 주석 처리되어 있습니다. 애플리케이션 DB_PWD설정과 PostgreSQL 설정 모두에서 샘플 데이터베이스 암호를 강력한 값으로 교체하십시오 POSTGRES_PASSWORD. 두 암호는 일치해야 합니다. 주석 처리를 해제하거나 추가하고 JWT_ENABLED=true길고 고유한 JWT 암호를 설정하십시오 JWT_SECRET. Docs와 통합될 애플리케이션 또는 커넥터에 동일한 JWT 암호를 사용하십시오.

로그인 암호를 재사용하는 대신 비밀 키를 생성하세요. 예를 들어, 명령어를 실행 openssl rand -hex 32하고 그 결과를 개인 환경 파일에 저장한 다음, Compose 파일에서 해당 파일을 참조하여 `<secret>` 및 `<secret>` ${JWT_SECRET}과 같이 ${DB_PASSWORD}사용하세요. 환경 파일은 다른 호스트 사용자가 접근할 수 없도록 보호하고 Git에 커밋하지 마세요. 핵심 설정은 개념적으로 다음과 같습니다.

# In a private .env file beside the Compose file
JWT_SECRET=replace_with_a_long_random_value
DB_PASSWORD=replace_with_a_different_long_random_value

데이터베이스 암호 항목을 모두 업데이트하여 참조하도록 하고 ${DB_PASSWORD}, 서버 환경 변수를 JWT_ENABLED=true및 로 설정하십시오 JWT_SECRET=${JWT_SECRET}. 상위 Compose 파일에는 이미 내부 PostgreSQL, RabbitMQ 및 Redis 서비스가 정의되어 있으므로, 해당 파일을 사용자 지정하는 경우 관련 서비스 이름과 종속성을 함께 유지하십시오.

중요 애플리케이션 데이터를 호스트에 영구적으로 저장하십시오. 서비스에서 onlyoffice-documentserver익명 볼륨 항목을 다음 /var/www/onlyoffice/Data과 /var/log/onlyoffice같은 바인드 마운트로 바꾸십시오.

volumes:
  - ./data:/var/www/onlyoffice/Data
  - ./logs:/var/log/onlyoffice

공식 파일에 정의된 다른 볼륨 항목과 명명된 PostgreSQL 볼륨은 변경해야 할 타당한 이유가 없는 한 그대로 유지하십시오. 호스트 디렉터리를 생성하고 받은 라이선스를 마운트된 데이터 디렉터리에 복사하십시오.

mkdir -p data logs
cp /secure/path/license.lic data/license.lic

컨테이너가 라이선스를 읽고 데이터 및 로그 경로에 쓸 수 있는지 확인하십시오. 파일 소유권 요구 사항은 이미지와 호스트에 따라 다를 수 있습니다. 권한 오류가 발생하는 경우, 포괄적인 권한을 적용하기보다는 실행 중인 컨테이너의 사용자와 공식 저장소의 지침을 확인하십시오. 라이선스와 비밀 키는 공개 웹 루트 및 소스 코드 관리 시스템에 저장하지 마십시오.

3. 엔터프라이즈 서비스를 검증하고 시작합니다.

리포지토리 디렉터리에서 Compose 구성을 검증한 다음 엔터프라이즈 스택을 실행합니다.

docker compose -f docker-compose.enterprise.yml config
docker compose -f docker-compose.enterprise.yml up -d

첫 번째 명령은 Compose가 파일을 구문 분석하고 변수를 해석할 수 있는지 확인합니다. 해석된 비밀 키를 출력할 수 있으므로 개인 터미널에서 실행하고 출력 결과를 공개 로그나 지원 스레드에 붙여넣지 마십시오. 두 번째 명령은 Enterprise 파일에 설명된 서비스를 빌드하거나 시작합니다. 공식 정의에는 문서 서버와 PostgreSQL, RabbitMQ, Redis 종속성이 포함됩니다.

서비스 상태 및 최근 메시지를 확인하세요:

docker compose -f docker-compose.enterprise.yml ps
docker compose -f docker-compose.enterprise.yml logs --tail=100 onlyoffice-documentserver

컨테이너가 재시작 중이거나 비정상적인 상태로 남아 있는 경우, 데이터베이스 인증 실패, 라이선스 메시지 누락 또는 권한 오류가 발생하는지 확인하십시오. 서비스가 "실행 중"으로 표시된 것은 해당 컨테이너 프로세스가 실행 중임을 나타내는 유용한 증거이지만, 이것만으로는 브라우저 편집이나 외부 통합이 제대로 작동함을 증명할 수는 없습니다.

4. 서비스를 HTTPS 뒤에 배치하고 접근을 제한하십시오.

실제 운영 환경에 배포할 경우, DNS 이름을 docs.example.com서버로 연결하고 사용 중인 인증서 방식(신뢰할 수 있는 역방향 프록시 또는 ONLYOFFICE에서 제공하는 인증서 설정)을 사용하여 HTTPS를 제공하십시오. 명령 및 통합 설정에서 샘플 호스트 이름을 실제 호스트 이름으로 업데이트하십시오. 일반적인 사용을 위해 일반 HTTP 편집기 엔드포인트를 공용 인터넷에 노출하지 마십시오.

공식 Enterprise Compose 파일은 문서 서버에 대해 80번 포트와 443번 포트를 공개합니다. 데이터베이스, Redis 및 RabbitMQ 서비스는 내부 종속성이므로 공용 네트워크에 노출되어서는 안 됩니다. 방화벽 및 클라우드 보안 그룹을 검토하여 필요한 인바운드 트래픽만 호스트에 도달하도록 설정하십시오. 다른 리버스 프록시가 이미 80번 포트와 443번 포트를 사용하고 있는 경우, Compose 포트 매핑을 호스트 전용 포트 또는 사용되지 않는 포트로 변경하고 프록시가 해당 로컬 엔드포인트로 포워딩하도록 구성하십시오. 프록시는 문서 편집에 사용되는 WebSocket 트래픽을 지원해야 합니다.

HTTPS와 JWT는 서로 다른 기능을 보호합니다. HTTPS는 클라이언트와 서버 간의 트래픽을 암호화하고, JWT는 Docs와 연결된 플랫폼 간에 주고받는 요청을 검증합니다. JWT를 활성화한 상태를 유지하고 커넥터 또는 플랫폼에 동일한 비밀 키를 설정하십시오. 통합 테스트를 통과시키기 위해 JWT를 비활성화하지 말고, 일치하지 않는 비밀 키, 헤더 또는 URL을 수정하십시오.

5. 서비스를 검증한 후 통합 테스트를 진행합니다.

공식 Compose 파일은 http://localhost:8000/info/info.jsonDocument Server 컨테이너 내부의 상태 확인을 정의합니다. `statement.health` 명령어를 사용하여 서비스가 정상인지 확인하십시오 docker compose ... ps. 브라우저를 사용하여 공개 HTTPS 호스트 이름을 열어볼 수도 있습니다. Docs 환영 페이지가 실행 중이면 웹 서비스가 응답하고 있음을 나타내지만, 이는 스토리지 플랫폼에서 전송되는 문서 콜백을 테스트하는 것은 아닙니다.

확인을 완료하려면 공개 Docs URL과 동일한 JWT 비밀 키를 사용하여 호환되는 플랫폼에 연결하세요. 테스트 DOCX 파일을 열고 간단히 편집한 후 저장하고 플랫폼에서 다시 엽니다. 이렇게 하면 플랫폼이 Docs에 연결할 수 있고 Docs가 저장된 변경 사항을 스토리지 서비스로 반환할 수 있는지 확인할 수 있습니다. 페이지는 로드되지만 편집기가 열리지 않으면 브라우저 콘솔, 프록시 WebSocket 구성, JWT 계약 및 서버 로그를 검사하세요. 테스트 문서는 일회용으로 관리하고 초기 설정 시에는 민감한 자료를 사용하지 마세요.

운영 및 문제 해결 참고 사항

• 라이선스가 감지되지 않았습니다.license.lic 호스트 디렉터리에 실제로 마운트되어 있는지 확인한 /var/www/onlyoffice/Data후 컨테이너 로그를 확인하십시오.
• JWT 오류: 서버와 커넥터의 비밀 키, 헤더 및 URL을 비교하십시오. 재시작 시 비밀 키를 동일하게 유지하십시오.
• 데이터베이스 시작 실패: PostgreSQL과 문서 서버 환경 모두에서 데이터베이스 암호가 일치하는지 확인하십시오.
• 데이터가 재구성 후 사라지는 경우: Enterprise Compose 파일이 데이터에 대해 바인드 마운트를 계속 사용하고 명명된 PostgreSQL 볼륨을 유지하는지 확인하십시오. 업그레이드 전에 두 가지 모두 백업하십시오.
• 편집기가 열리지만 저장할 수 없습니다. Docs 컨테이너에서 플랫폼의 콜백 URL에 접근할 수 있는지, 그리고 프록시가 WebSocket 연결을 제대로 전달하는지 확인하십시오.

이미지 버전을 변경하기 전에 엔터프라이즈별 업데이트 경로를 사용하고 릴리스 노트를 검토하십시오. docker compose down -vCompose로 관리되는 볼륨을 제거하려는 경우가 아니면 이미지 버전 변경을 피하십시오. 해당 옵션을 사용하면 지정된 PostgreSQL 데이터 볼륨이 삭제될 수 있습니다. 업그레이드하기 전에 데이터 디렉터리, 필요한 경우 로그 및 데이터베이스를 백업하십시오.

공식 참고 자료

버전별 세부 정보는 ONLYOFFICE의 엔터프라이즈 Docker 설치 가이드 , 라이선스 활성화 지침 및 공식 엔터프라이즈 Compose 파일을 참조하십시오 . 저장소의 README 파일에는 Compose 명령 및 컨테이너 매개변수에 대한 설명이 있습니다. Docker의 Compose 플러그인 설치 가이드는 Linux 설치를 다루고 있으며, Docker가 설치되어 있지 않은 경우 사용 중인 배포판에 맞는 Docker Engine 설치 지침을 따르십시오.