2026년 9월 18일

Docker로 설치하기

Docker를 사용하면 호스트 운영체제와 분리된 환경에서 스페이스빌더를 실행할 수 있습니다. 컨테이너를 다시 생성해도 데이터가 유지되도록 저장 경로를 반드시 호스트 볼륨에 연결하세요.

시작하기 전에

Docker 명령을 실행할 수 있는 권한
Windows와 macOS는 Docker Desktop, Linux는 Docker Engine
서비스 데이터와 향후 업로드할 파일을 저장할 충분한 디스크 공간

호스트에 별도 라이브러리를 설치해야 하나요?

아니요. Docker를 사용하는 경우 OCR과 문서 변환에 필요한 패키지는 호스트가 아니라 컨테이너 이미지 안에 설치되어야 합니다. 호스트에는 Docker Engine 또는 Docker Desktop만 있으면 됩니다.

다음과 같은 긴 apt-get install 명령을 Docker 호스트에서 실행할 필요는 없습니다.

sudo apt-get install -y \
  tesseract-ocr poppler-utils mupdf-tools libreoffice pandoc \
  libtesseract-dev libleptonica-dev libvips-tools \
  libheif1 libheif-plugin-libde265 libwebp7 libjpeg8 \
  libpng16-16t64 libopenjp2-7 libtiff6

이 목록에는 실행용 패키지와 소스 빌드용 개발 패키지가 섞여 있습니다.

구분	패키지	필요 조건
기본 이미지 처리	`libvips`, `libvips-tools`, `libheif1`, `libheif-plugin-libde265`, `libglib2.0-0` 계열 런타임	공식 이미지에 포함되어야 함
OCR	`tesseract-ocr`, 필요한 언어팩	로컬 OCR 기능을 사용할 때 권장
PDF 처리	`poppler-utils`, `mupdf-tools`	PDF 텍스트 추출과 OCR 전처리에 권장
오피스 문서 변환	`libreoffice`, `pandoc`	문서 미리보기와 형식 변환에 권장
소스 빌드	`libtesseract-dev`, `libleptonica-dev`, 기타 `*-dev`	컨테이너 안에서 직접 빌드할 때만 필요

공식 이미지에는 기본 런타임과 권장 기능 패키지가 포함되어야 합니다. 컨테이너 시작 후 apt-get으로 패키지를 추가하는 방식은 권장하지 않습니다. 컨테이너를 다시 만들면 수동으로 설치한 내용이 사라지기 때문입니다.

Docker 이미지 가져오기

SetFN 스페이스빌더 Docker 이미지를 가져옵니다.

docker pull setfn/space-builder:latest

컨테이너 실행

다음 명령으로 스페이스빌더 컨테이너를 실행합니다.

docker run -d \
  --name setfn-space-builder \
  -p 8510:8510 \
  -v /path/to/space-home:/space-home \
  setfn/space-builder:latest

옵션	설명
`-d`	백그라운드 실행
`--name`	컨테이너 이름 지정
`-p 8510:8510`	호스트의 `8510` 포트를 컨테이너의 `8510` 포트에 연결
`-v /path/to/space-home:/space-home`	호스트 저장 경로를 컨테이너에 마운트

/path/to/space-home은 실제 데이터를 저장할 호스트의 절대 경로로 변경하세요. 이 경로를 마운트하지 않으면 컨테이너를 삭제할 때 서비스 데이터도 함께 사라질 수 있습니다.

호스트의 8510 포트가 이미 사용 중이면 왼쪽 포트만 변경할 수 있습니다. 예를 들어 -p 8511:8510으로 실행한 경우 접속 주소는 http://localhost:8511입니다.

컨테이너가 실행되면 브라우저에서 http://localhost:8510에 접속합니다. 초기 설정 화면이 나타나면 초기 설정으로 이동해 관리자 계정과 서비스 환경을 구성하세요.

← Previous

Linux에 설치하기

Windows에 설치하기