Windows에 설치하기

시작하기 전에

• Windows 10(버전 2004 이상) 또는 Windows 11
• 관리자 권한으로 PowerShell을 실행할 수 있는 계정
• 서비스 데이터와 앞으로 업로드할 파일을 저장할 디스크 공간

WSL과 Ubuntu 설치

WSL이 이미 설치되어 있다면 이 단계를 건너뛰고 스페이스빌더 설치로 이동하세요.

1. PowerShell을 관리자 권한으로 실행합니다.
   Windows 검색에서 PowerShell을 검색하고 마우스 오른쪽 버튼을 눌러 관리자 권한으로 실행을 선택합니다.
   
2. PowerShell 창이 열리면 다음 명령을 입력합니다.
   

   wsl --install
   

   
   이 명령은 WSL2와 기본 배포판인 Ubuntu를 함께 설치합니다.
3. 설치가 끝나면 컴퓨터를 재시작합니다.
4. 재시작 후 Ubuntu 터미널이 자동으로 열리면 사용할 사용자 이름과 비밀번호를 입력해 Ubuntu 계정을 만듭니다.
   터미널에는 다음과 같이 표시됩니다.

   Installing, this may take a few minutes...
   Please create a default UNIX user account. The username does not need to match your Windows username.
   For more information visit: https://aka.ms/wslusers
   Enter new UNIX username:
   

   
   사용자 이름을 입력하고 Enter를 누르면 비밀번호(New password:)와 비밀번호 확인(Retype new password:)을 차례로 묻습니다. 완료되면 Installation successful! 메시지와 함께 Ubuntu 셸 프롬프트(사용자이름@PC이름:~$)가 나타납니다.
   Ubuntu 터미널은 이후 단계에서 계속 사용하므로 닫지 않습니다.

Linux 확인하기

파일 탐색기에서도 설치 결과를 확인할 수 있습니다. 파일 탐색기 왼쪽 탐색 창의 아래쪽에 Linux 항목이 추가됩니다.

Linux > Ubuntu > home으로 이동하면 앞에서 만든 사용자 이름의 폴더가 있습니다.

설치 파일 다운로드 및 옮기기

1. 다운로드 페이지에서 Linux용 설치 파일(setfn-spacebuilder)을 다운로드합니다.
2. 파일 탐색기에서 Linux > Ubuntu > home > <사용자 이름> 폴더로 이동한 뒤, 다운로드한 파일을 이 폴더로 옮깁니다.
   

스페이스빌더 설치

WSL의 Ubuntu에서는 일반 Linux와 같은 방법으로 설치합니다. 먼저 Ubuntu 터미널에서 설치 파일에 실행 권한을 부여합니다.

chmod +x ~/setfn-spacebuilder

필수 라이브러리 설치

스페이스빌더는 이미지 분석과 미리보기 생성에 시스템 라이브러리를 사용합니다. Ubuntu 24.04 이상에서는 다음 패키지를 먼저 설치합니다.

sudo apt update
sudo apt install -y \
  libvips42t64 libvips-tools \
  libheif1 libheif-plugin-libde265 \
  libglib2.0-0

권장 기능 패키지 설치

스페이스빌더 서버는 업로드된 파일의 OCR, PDF 분석, 문서 미리보기와 형식 변환을 직접 처리합니다. 다음 패키지가 없어도 서버는 실행되지만, 해당 기능이 제한되거나 사용할 수 있는 변환 엔진이 줄어듭니다. OCR과 문서 변환 기능을 모두 사용하려면 함께 설치하세요.

sudo apt install -y \
  tesseract-ocr tesseract-ocr-kor tesseract-ocr-jpn \
  poppler-utils \
  libreoffice pandoc

설치 결과는 다음 명령으로 확인합니다.

vips --version
vips list classes | grep -i heif
tesseract --version
tesseract --list-langs
pdftotext -v
libreoffice --version
pandoc --version

설치 프로그램 실행

설치 파일을 실행합니다.

./setfn-spacebuilder

설치 프로그램은 기본적으로 18510 포트에서 초기 설정 페이지를 엽니다. 이 포트를 다른 프로그램이 사용 중이면 다음 빈 포트를 자동으로 선택하므로, 터미널에 출력된 주소로 접속합니다.

Windows 브라우저에서 접속하기

WSL2는 Windows와 네트워크를 공유하므로, Ubuntu에서 실행 중인 스페이스빌더에 Windows의 Chrome, Edge 같은 브라우저로 http://localhost:18510에 접속할 수 있습니다. 포트가 다르면 Ubuntu 터미널에 출력된 주소를 사용합니다.

초기 설정 페이지가 열리면 이용 약관에 동의한 뒤 관리자 계정과 서비스 환경을 설정합니다. 입력 항목은 초기 설정을 참고하세요.

알아두기

• Ubuntu 터미널을 닫으면 스페이스빌더도 종료됩니다. 터미널을 닫아도 계속 실행하려면 자동으로 시작하기를 참고해 systemd 자동 시작을 설정하세요. WSL에서 systemd를 사용하려면 /etc/wsl.conf의 [boot] 항목에 systemd=true가 설정되어 있어야 합니다.
• Windows를 종료하거나 재시작하면 WSL도 종료됩니다. systemd 자동 시작을 설정해도 Windows가 WSL을 자동으로 다시 켜지 않으므로, 재시작 후에는 Ubuntu 터미널을 열어야 스페이스빌더가 다시 시작됩니다.
• 같은 네트워크의 다른 기기에서 접속하려면 WSL 네트워크 설정과 Windows 방화벽 규칙도 확인해야 합니다.

Windows 재시작 후 WSL 자동으로 켜기

Windows에 로그온할 때 WSL이 실행되도록 작업 스케줄러에 등록하면, 재시작 후 Ubuntu 터미널을 열지 않아도 스페이스빌더가 다시 시작됩니다. systemd 자동 시작이 먼저 설정되어 있어야 합니다.

1. Windows 검색에서 taskschd.msc(또는 작업 스케줄러)를 검색해 실행합니다.
2. 작업 만들기를 선택합니다. 기본 작업 만들기에서는 세부 옵션을 설정할 수 없습니다.
3. 트리거 탭에서 새로 만들기를 선택하고, 작업 시작을 로그온할 때로 지정한 뒤 사용할 사용자 계정을 선택합니다.
4. 동작 탭에서 새로 만들기를 선택하고, 프로그램/스크립트에 wsl.exe를, 인수 추가에 다음 값을 입력합니다.

   -d Ubuntu -u <사용자 이름> -- true
   

<사용자 이름>은 Ubuntu 계정을 만들 때 정한 사용자 이름으로 바꾸세요. 이 명령은 WSL을 부팅해 systemd를 실행하는 역할만 합니다. 이후 자동 시작으로 등록한 스페이스빌더 서비스가 시작됩니다.

관련 문서

• Linux에 설치하기
• 초기 설정