Host Storage 어댑터 연결하기
Host Storage 어댑터는 Office가 실행되는 서버의 디렉터리를 문서 저장소로 사용합니다. Docker로 실행한 Office에는 컨테이너 안에서 접근할 수 있는 디렉터리를 지정합니다.
미리 연결된 어댑터 확인하기
Trial과 Free Commercial 컨테이너 이미지에는 문서 열기와 저장을 바로 테스트할 수 있도록 host-storage라는 Host Storage 어댑터를 미리 연결해 두었습니다.
문서 루트 디렉터리는 컨테이너 안의 /home/thinkfree/docs이며, 이미지에 포함된 샘플 문서가 이 폴더에 있습니다. 이 어댑터는 다시 등록할 필요가 없습니다.
Office 관리자 페이지에 로그인한 뒤 외부연동에서 host-storage를 확인합니다.
해당 행의 업데이트 아이콘을 누르면 문서 루트 디렉터리와 스토리지 표시 이름을 확인할 수 있습니다.
미리 연결된 어댑터의 문서 URL 만들기
문서를 여는 URL은 Office 주소, 등록한 어댑터 이름, 문서 루트 아래의 상대 경로를 조합합니다. Word 문서를 편집기로 여는 URL 형식은 다음과 같습니다.
{OFFICE_URL}/cloud-office/api/{ADAPTER_NAME}/{DOCUMENT_PATH}/open?app=WORD_EDITOR&user_id={USER_ID}&docId={DOCUMENT_ID}
ADAPTER_NAME에는 관리자 화면의 이름을 사용합니다.
스토리지 표시 이름은 URL에 사용하지 않습니다.
DOCUMENT_PATH에는 문서 루트 디렉터리를 제외한 상대 경로를 넣습니다.
위 캡처의 어댑터 이름 host-storage와 문서 루트 /home/thinkfree/docs를 사용한 예제입니다. 이 폴더에 sample.docx가 있다면 다음과 같이 연결합니다.
| 항목 | 값 |
|---|---|
| Office 주소 | http://localhost:8080 |
| 어댑터 이름 | host-storage |
| 문서 루트 디렉터리 | /home/thinkfree/docs |
| 컨테이너 안의 파일 | /home/thinkfree/docs/sample.docx |
| URL에 넣을 문서 경로 | sample.docx |
http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=hostsample001
예제의 user_id는 사용할 사용자 식별자로, docId는 Office에서 문서를 구분하는 고유한 ID로 바꿉니다.
Office 접속 주소나 포트가 다르면 URL 앞부분도 변경합니다.
다른 문서 형식의 app 값과 JavaScript로 URL을 생성하는 방법은 문서 URL 생성에서 설명합니다.
문서 폴더 연결하기
앞에서 사용한 /home/thinkfree/docs는 컨테이너 안에 있는 샘플 문서 폴더입니다. Docker를 실행하는 호스트 컴퓨터의 문서 폴더와는 별개의 위치입니다.
호스트 컴퓨터에 저장된 문서를 Office에서 열려면, 문서가 있는 폴더를 컨테이너의 /home/thinkfree/docs에 마운트해야 합니다.
아래는 Linux 사용자의 /home/username/personal-documents 폴더를 연결하는 예제입니다. 이 경로를 실제 문서 폴더의 절대 경로로 바꾸고, 폴더가 존재하며 Office가 읽고 쓸 수 있는지 확인합니다.
컨테이너를 생성할 때 Office 실행 명령에 다음 옵션을 추가합니다.
-v "/home/username/personal-documents:/home/thinkfree/docs"
콜론(:) 왼쪽의 /home/username/personal-documents는 호스트 컴퓨터의 폴더이고, 오른쪽의 /home/thinkfree/docs는 Office가 그 폴더에 접근할 컨테이너 안의 경로입니다.
관리자 화면의 문서 루트 디렉토리는 /home/thinkfree/docs로 유지합니다.
마운트한 동안에는 이 경로에서 호스트 폴더의 문서가 보입니다. 이미지에 포함된 샘플 문서는 호스트 폴더로 자동 복사되지 않으므로, 빈 폴더를 연결하면 샘플 문서도 표시되지 않습니다. Office에서 문서를 편집하고 저장하면 연결한 호스트 폴더의 파일에 반영됩니다.
마운트한 폴더의 문서 URL
위와 같이 마운트하면 호스트 컴퓨터의 /home/username/personal-documents/contracts/Proposal 2026.docx가
컨테이너에서는 /home/thinkfree/docs/contracts/Proposal 2026.docx로 보입니다.
미리 연결된 host-storage를 그대로 사용하므로, URL에는 문서 루트 아래의 contracts/Proposal 2026.docx를 넣습니다.
http://localhost:8080/cloud-office/api/host-storage/contracts/Proposal%202026.docx/open?app=WORD_EDITOR&user_id=local-user&docId=hostproposal001
폴더를 구분하는 /는 유지하고, 공백은 위 예제의 %20처럼 경로 구간별로 URL 인코딩합니다.
호스트 경로인 /home/username/personal-documents나 컨테이너의 문서 루트인 /home/thinkfree/docs는 URL에 넣지 않습니다.
Host Storage 어댑터 더 추가하기
미리 연결된 host-storage에 다른 호스트 문서 폴더를 연결하려면 앞의 예처럼 마운트할 폴더를 바꿉니다.
별도 어댑터로 연결하려면 아래와 같이 폴더를 추가로 마운트하고 새 어댑터를 등록합니다.
이 예제는 호스트 컴퓨터의 /home/username/work-files를 컨테이너의 /home/thinkfree/team-documents에 연결합니다.
왼쪽 경로를 실제 문서 폴더로 바꾸고 Office가 읽고 쓸 수 있는지 확인한 뒤, 컨테이너를 생성할 때 Office 실행 명령에 다음 옵션을 추가합니다.
-v "/home/username/work-files:/home/thinkfree/team-documents"
Host Storage는 Office가 실행되는 서버의 파일과 디렉터리에 접근할 수 있습니다. 보안을 위해 새 Host Storage 어댑터 등록은 기본적으로 비활성화되어 있습니다. 새 어댑터를 등록하려면 Office 실행 명령에 다음 옵션도 추가해야 합니다.
-e TFO_ADAPTER_HOST_STORAGE_ENABLED=true
Office가 실행되면 관리자 페이지에서 다음과 같이 등록합니다.
- 외부연동에서 어댑터 추가를 누릅니다.
- 어댑터 유형에서 호스트 스토리지 어댑터를 선택합니다.
- 다음 항목을 입력합니다.
| 항목 | 입력할 값 |
|---|---|
| 이름 | 문서 URL에 사용할 고유한 어댑터 이름. 예: company-documents |
| 설명 | 어댑터의 용도 |
| 스토리지 표시 이름 | 사용자에게 표시할 저장소 이름. 예: Company documents |
| 문서 루트 디렉토리 | Office가 읽고 쓸 수 있는 컨테이너 안의 절대 경로. 예: /home/thinkfree/team-documents |
- 연결 테스트로 디렉터리에 접근하고 파일 목록을 조회할 수 있는지 확인합니다.
- 성공하면 등록을 누르고 목록에서 어댑터가 실행 중인지 확인합니다.
아래는 예제의 값을 입력하고 연결 테스트에 성공한 화면입니다.
연결 테스트가 실패하면 폴더가 마운트되어 있는지, Office가 해당 폴더에 접근할 수 있는지 확인합니다. 관리자 화면에는 호스트 경로가 아니라 컨테이너 안의 경로를 입력합니다.
다른 디렉터리를 연결한 어댑터의 문서 URL
등록한 company-documents로 문서를 열 때는 새 문서 루트 아래의 상대 경로를 사용합니다.
다음은 호스트 폴더에 reports/Quarterly Report.docx가 있는 경우입니다.
| 항목 | 값 |
|---|---|
| 어댑터 이름 | company-documents |
| 문서 루트 디렉토리 | /home/thinkfree/team-documents |
| 호스트 컴퓨터에 있는 파일 | /home/username/work-files/reports/Quarterly Report.docx |
| URL에 넣을 문서 경로 | reports/Quarterly Report.docx |
http://localhost:8080/cloud-office/api/company-documents/reports/Quarterly%20Report.docx/open?app=WORD_EDITOR&user_id=local-user&docId=companyreport001
전체 URL 옵션은 문서 URL 생성에서 확인합니다.
문서 열기와 저장 확인하기
위의 예제에 따라 실제 파일의 문서 URL을 만들어 브라우저에서 엽니다. 문서를 편집하고 저장한 뒤 다시 열어 변경 내용이 유지되는지 확인합니다.
관리자 화면에서 문서 찾아보기
외부연동의 어댑터 목록에서 company-documents가 실행 중인지 확인합니다.
어댑터 이름 옆의 폴더 모양 파일 찾아보기 버튼을 누릅니다.
파일 브라우저에서 폴더를 선택하면 안으로 이동합니다.
예제의 reports 폴더를 선택하면 Quarterly Report.docx를 확인할 수 있습니다.
Office 문서를 클릭하면 새 탭에서 Office 편집기가 열립니다.