Alfresco와 ONLYOFFICE 통합 가이드

개요

Alfresco Share는 Alfresco의 ECM 저장소를 기반으로 하는 협업형 콘텐츠 관리 솔루션입니다. 이 문서는 Alfresco Share에 ONLYOFFICE 편집기를 통합해 사용자가 웹에서 직접 문서를 공동 편집하도록 설정하는 방법을 단계별로 설명합니다.

중요: 프로덕션 환경에서는 먼저 테스트 환경에서 모든 단계를 검증한 뒤 적용하세요.

주요 사용 사례 (Primary intent)

• Alfresco Share에서 실시간 공동 편집 활성화

관련 검색어: Alfresco ONLYOFFICE 통합, ONLYOFFICE Alfresco 플러그인 설치, ONLYOFFICE Document Server 설치, alfresco-amp-plugin, Alfresco Share 공동편집

요구사항

• ONLYOFFICE Document Server
• Java 7 SDK 이상(권장: Oracle Java 8)
• Gradle

참고: Docker 기반의 ONLYOFFICE Document Server를 사용하면 종속성 문제를 줄일 수 있습니다. 아래 ‘대안 접근법’ 섹션을 확인하세요.

설치 및 설정 단계

아래 단계는 순서대로 진행합니다. 각 단계 끝에 확인 체크리스트를 두어 누락을 방지합니다.

1. ONLYOFFICE Document Server 설치

ONLYOFFICE Document Server를 설치하거나 Docker 이미지를 사용하세요. Docker 사용 시 포트, 방화벽, SSL 설정을 미리 계획합니다.

중요: Document Server URL은 나중에 alfresco-global.properties에 onlyoffice.url로 등록됩니다.

2. Gradle 설치

Gradle 저장소를 추가하고 패키지를 업데이트한 뒤 Gradle을 설치합니다.

sudo add-apt-repository ppa:cwchien/gradle
sudo apt-get update
sudo apt-get install gradle

기존 Gradle이 이미 설치되어 있으면 먼저 제거합니다:

sudo apt-get remove gradle

확인: gradle –version 명령으로 설치 여부와 버전을 확인하세요.

3. Oracle Java 8 설치

Oracle Java 8을 설치하려면 아래 명령을 실행합니다.

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

확인: java -version 및 javac -version으로 자바 버전을 확인하세요.

4. 대체(java alternatives) 전환

시스템의 기본 java를 Oracle Java로 설정합니다.

sudo update-alternatives --config java
sudo update-alternatives --config javac
sudo update-alternatives --config javaws

중요: 여러 자바 버전이 있는 환경에서는 이 설정을 통해 빌드 도구가 올바른 JDK를 사용하도록 합니다.

5. 필요한 종속성 빌드

Git에서 alfresco 플러그인을 클론하고 빌드합니다.

git clone https://github.com/yeyan/alfresco-amp-plugin.git

cd amp-plugin
gradle publish

확인: 빌드가 성공하면 ./build/amp 아래에 .amp 패키지가 생성됩니다.

6. onlyoffice-alfresco 플러그인 복사

플러그인 소스를 클론합니다.

cd ..
git clone https://github.com/cetra3/onlyoffice-alfresco.git

7. share 및 repo 디렉터리에서 gradle amp 실행

각 모듈(share, repo)에서 gradle amp를 실행해 AMP 패키지를 빌드합니다. (프로젝트 구조에 따라 명령이 다를 수 있습니다.)

확인: 빌드 후 ./build/amp에 생성된 패키지 파일들을 확인하세요.

8. alfresco-global.properties에 onlyoffice.url 추가

Alfresco의 설정 파일(alfr esco-global.properties)에 아래 항목을 추가합니다. onlyoffice.url은 Document Server의 공개 접근 URL입니다.

예:

onlyoffice.url=http://onlyoffice.example.com

중요: HTTPS를 사용하는 경우 SSL 인증서가 유효한지, Alfresco와 Document Server 간 통신에 필요한 포트가 열려 있는지 확인하세요.

9. 생성된 AMP 패키지를 Alfresco 설치 디렉터리에 복사

./build/amp 아래의 패키지를 Alfresco 설치의 amps/ 및 amps_share/ 디렉터리에 각각 복사합니다.

확인: 파일 권한과 소유자가 Alfresco 프로세스가 읽을 수 있도록 설정되었는지 확인하세요.

10. apply_amps.sh 스크립트 실행

Alfresco 설치 디렉터리에서 bin/apply_amps.sh를 실행합니다. 설치 도중 두 개의 모듈이 설치되었다는 메시지가 나오며 Enter 키를 눌러 완료합니다.

완료 후: Alfresco 문서 라이브러리에서 ‘Edit in Onlyoffice’ 액션이 생성되어 있는지 확인합니다.

검증 및 테스트 체크리스트 (관리자용)

• ONLYOFFICE Document Server가 접근 가능하고 정상 응답
• alfresco-global.properties에 onlyoffice.url이 정확히 설정됨
• AMP 패키지들이 amps/ 및 amps_share/에 배포됨
• Alfresco 재시작 후 ‘Edit in Onlyoffice’ 버튼 노출 확인
• 공동 편집(동시 편집) 시 충돌 없이 동작 확인

대안 접근법

• Docker 사용: ONLYOFFICE Document Server는 공식 Docker 이미지를 제공합니다. Docker Compose로 Alfresco와 Document Server를 함께 구성하면 종속성 관리를 간소화할 수 있습니다.
• 리버스 프록시: Nginx 또는 Apache를 이용해 SSL 종료와 로드밸런싱을 구성하세요. 특히 외부 접근 환경에서는 HTTPS 및 적절한 헤더(예: X-Forwarded-For)를 설정해야 합니다.

문제 해결 및 롤백(Incident runbook)

1. 편집 버튼이 보이지 않을 때
   • alfresco-global.properties의 onlyoffice.url 확인
   • Alfresco 로그(alfresco.log)에서 플러그인 로드 오류 확인
2. Document Server에 접속 실패
   • Document Server가 실행 중인지 확인
   • 방화벽/포트(기본 80/443) 확인
3. 동시 편집 시 충돌
   • Document Server 버전 호환성 확인
   • 브라우저 캐시 및 확장 프로그램 차단 후 재확인

롤백 절차:

• amps/ 및 amps_share/에 복사한 .amp 파일을 제거
• Alfresco를 안전 모드로 재시작하거나, apply_amps.sh로 이전 상태를 복원

호환성 및 마이그레이션 팁

• Alfresco 및 ONLYOFFICE 버전 호환성을 항상 확인하세요. 각 플러그인의 README나 GitHub 이슈 페이지에서 확인할 수 있습니다.
• 테스트 환경에서 먼저 플러그인을 적용하고 성능·동시 접속 테스트를 수행하세요.

역할별 간단 체크리스트

• 시스템 관리자: Java, Gradle, 서버 접근성, 방화벽, SSL 설정
• Alfresco 관리자: alfresco-global.properties 편집, AMP 배포, Alfresco 재시작
• 개발자/통합 담당자: 플러그인 빌드(gradle publish), 로그 모니터링, 문제 재현

1줄 용어집

• AMP: Alfresco Module Package, Alfresco에 추가 기능을 배포하는 패키지 형식
• ONLYOFFICE Document Server: ONLYOFFICE의 웹 기반 문서 편집 엔진

추가 리소스

• Alfresco 공식 웹사이트: https://www.alfresco.com/
• ONLYOFFICE 공식 웹사이트: http://www.onlyoffice.com/
• onlyoffice-alfresco 플러그인(GitHub): https://github.com/cetra3/onlyoffice-alfresco

요약

• ONLYOFFICE와 Alfresco 통합은 Document Server 설치, Java/Gradle 환경, AMP 빌드 및 배포, alfresco-global.properties 설정의 순서로 진행됩니다.
• 프로덕션 적용 전 테스트 환경에서 모든 단계를 검증하세요.

중요: 운영 환경에서 SSL, 방화벽, 인증(SSO 등) 요구사항을 반드시 검토하고 적용하세요.