빠른 구축 가이드

시작하기

Fess는 웹사이트와 파일 서버를 대상으로 크롤(순회)하고, 수집한 콘텐츠를 횡단 검색할 수 있는 오픈소스 전문 검색 서버입니다.

여기에서의 설명은 빠르게 Fess를 경험해보고 싶은 분을 위한 것으로, Fess를 이용하기 위한 최소한의 절차를 설명합니다.

어떤 방법을 사용할까요?

Docker (권장) ZIP 패키지
사전 준비 Docker와 Docker Compose Java 21 (OpenSearch는 fess-setup 명령으로 설치)
시작의 간편함 ◎ 명령 몇 줄만으로 가능 △ Java 설치 후 몇 가지 설정 명령 실행
이런 분에게 먼저 시도해보고 싶은 분 Docker를 사용할 수 없는 환경의 분

Docker로 빠른 시작 (권장)

소요 시간 목표: 초회 5〜10분 정도 (Docker 이미지 다운로드 시간 포함)

Docker는 Fess를 가장 빠르고 안정적으로 실행하는 방법을 제공합니다. 모든 의존성이 포함되어 있으므로 별도로 설치할 것이 없습니다.

Step 1: Docker Compose 파일 다운로드

mkdir fess-docker && cd fess-docker
curl -OL https://raw.githubusercontent.com/codelibs/docker-fess/main/compose/compose.yaml
curl -OL https://raw.githubusercontent.com/codelibs/docker-fess/main/compose/compose-opensearch3.yaml

Step 2: 컨테이너 시작

docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

Step 3: 시작 확인

서비스가 초기화될 때까지 몇 분 정도 기다린 후 브라우저에서 접속합니다:

경고

보안 안내: 첫 로그인 후 기본 관리자 비밀번호를 즉시 변경하세요.

Step 4: 중지

docker compose -f compose.yaml -f compose-opensearch3.yaml down

고급 Docker 설정(커스텀 설정, 외부 OpenSearch, Kubernetes)에 대해서는 Docker 설치 가이드 를 참조하세요.

ZIP 패키지로 시작

소요 시간 목표: 초회 20〜30분 정도 (Java 설치 및 OpenSearch 다운로드 시간 포함)

Docker를 사용하지 않는 경우 ZIP 패키지에서 직접 Fess를 실행할 수 있습니다. Fess에는 검색 엔진이 포함되어 있지 않으므로, ZIP 패키지에 포함된 fess-setup 명령으로 OpenSearch를 다운로드하고 Fess에 필요한 플러그인을 설치합니다.

참고

이 방법은 시험용 시작 방법이므로 운용 환경 구축 절차는 Docker를 이용하는 설치 절차 등을 참조하세요. (이 절차로 시작한 Fess는 간단한 동작 확인용으로서의 이용을 상정하고 있으며 이 환경의 운용은 권장하지 않습니다)

사전 준비

시작하기 전에 Java 21을 설치해두세요. Java 21은 Eclipse Temurin 을 권장합니다. OpenSearch는 미리 설치할 필요가 없습니다. Step 2에서 설치합니다.

참고

OpenSearch는 Linux와 Windows용 공식 빌드만 공개하고 있습니다. macOS에서는 fess-setup install opensearch 가 오류로 종료되므로 Docker(방법 1)를 이용하거나, Homebrew로 OpenSearch를 설치하는 방법은 Linux 설치 (상세 절차) 를 참조하세요.

Step 1: 다운로드 및 압축 해제

GitHub 릴리스 사이트 에서 최신 Fess의 ZIP 패키지를 다운로드하고 압축을 해제한 후 해당 디렉터리로 이동합니다:

unzip fess-x.y.z.zip
cd fess-x.y.z

Step 2: OpenSearch 설치

fess-setup 은 root 가 아닌 일반 사용자로 실행하세요. OpenSearch는 root 로는 시작되지 않습니다.

# Linux
bin/fess-setup install opensearch

# Windows
bin\fess-setup.bat install opensearch

이 명령은 이 Fess가 지원하는 버전의 OpenSearch를 Fess 디렉터리 아래의 opensearch/ 에 다운로드하고, Fess에 필요한 플러그인 4개를 설치하며, Fess에 필요한 설정을 config/opensearch.yml 에 추가합니다. bin/fess 는 이 OpenSearch를 자동으로 찾으므로, OpenSearch가 같은 호스트에서 실행되는 한 설정 파일을 편집할 필요가 없습니다.

경고

이 명령은 plugins.security.disabled: true 를 설정하므로 OpenSearch는 인증 없이 요청을 받아들입니다. 기본적으로 루프백 주소에서만 수신하지만 네트워크에 공개하지 마세요. 프로덕션 환경의 설정은 보안 설정 를 참조하세요.

모든 명령(Node.js 및 플러그인 설치, check)에 대해서는 fess-setup 명령 를 참조하세요.

Step 3: OpenSearch와 Fess 시작

먼저 OpenSearch를 시작한 후 Fess를 시작합니다:

# Linux
opensearch/opensearch-3.9.0/bin/opensearch -d
bin/fess

:: Windows (각각 별도의 명령 프롬프트에서 실행)
opensearch\opensearch-3.9.0\bin\opensearch.bat
bin\fess.bat

약 30초 후 다음 주소에 접속할 수 있습니다:

설치를 확인하려면 bin/fess-setup check (Windows에서는 bin\fess-setup.bat check)를 실행하세요. OpenSearch에 접속할 수 있는지, Fess에 필요한 플러그인이 있는지를 보고합니다.

경고

기본 비밀번호는 반드시 변경하세요. 프로덕션 환경에서는 첫 로그인 후 즉시 비밀번호를 변경하는 것을 강력히 권장합니다.

Fess 정지 (ZIP)

Ctrl-C나 kill 명령 등으로 fess 프로세스를 정지합니다. 이어서 OpenSearch도 같은 방법으로 정지합니다 (프로세스를 kill 하거나, 포그라운드에서 실행 중이면 Ctrl+C).

크롤 설정과 검색

1. 크롤 설정 작성

  1. 관리 화면(http://localhost:8080/admin)에 로그인합니다

  2. 왼쪽 메뉴의 크롤러 > 웹 을 클릭합니다

  3. 신규 작성 버튼을 클릭합니다

  4. 다음 정보를 입력하세요:

    • 이름: 크롤 설정 이름(예: 회사 웹사이트)

    • URL: 크롤 대상 URL(예: https://www.example.com/)

    • 최대 접속 수: 10 (처음에는 작은 값을 권장)

    • 간격: 10000 (밀리초, 기본값 10000 ms를 권장)

  5. 작성 을 클릭하여 저장합니다

경고

최대 접속 수를 너무 크게 설정하면 대상 사이트에 과도한 부하를 줄 수 있습니다. 동작 확인 시에는 반드시 작은 값(10~100 정도)부터 시작하세요. 자신이 관리하지 않는 사이트를 크롤할 경우 robots.txt 설정에 따라 주세요.

2. 크롤 실행

  1. 시스템 > 스케줄러 를 클릭합니다

  2. Default Crawler 를 찾습니다

  3. 지금 시작 버튼을 클릭합니다

  4. 시스템 > 크롤 정보 에서 진행 상황을 확인합니다

정기 실행의 경우 Default Crawler 를 선택하여 스케줄을 설정합니다. 시작 시간이 오전 10:35이면 35 10 * * ? 를 입력합니다 (형식: 분 시 일 월 요일).

3. 검색

크롤이 완료되면 (세션 정보에 WebIndexSize가 표시됩니다):

http://localhost:8080/ 에 접속하여 검색어를 입력하면 검색 결과가 표시됩니다.

더 자세히 알려면