시작, 중지, 초기 설정

이 페이지에서는 Fess 서버의 시작, 중지 및 초기 설정 절차에 대해 설명합니다.

중요

Fess 를 시작하기 전에 반드시 OpenSearch를 시작하십시오. OpenSearch가 시작되어 있지 않은 경우 Fess 는 올바르게 작동하지 않습니다.

시작 방법

설치 방법에 따라 시작 절차가 다릅니다.

ZIP 버전의 경우

OpenSearch 시작

$ cd /path/to/opensearch-3.9.0
$ ./bin/opensearch

백그라운드에서 시작하는 경우:

$ ./bin/opensearch -d

참고

bin/fess-setup install opensearch 로 설치한 OpenSearch 는 Fess 디렉터리의 opensearch/opensearch-3.9.0 에 있습니다.

중요

OpenSearch 는 일반 사용자로 시작하십시오. root 로 시작하면 can not run opensearch as root 를 표시하고 종료합니다. 거부된 시작에서도 config/opensearch.keystore 등의 파일이 root 소유로 남으며, 다음에 일반 사용자로 시작하면 AccessDeniedException 으로 실패합니다. 다시 시작하기 전에 OpenSearch 디렉터리의 소유자를 그 사용자로 되돌리십시오. 예:

$ sudo chown -R <user> /path/to/opensearch-3.9.0

Fess 시작

$ cd /path/to/fess-15.9.0
$ ./bin/fess

백그라운드에서 시작하는 경우:

$ ./bin/fess -d

참고

시작에는 몇 분 정도 소요될 수 있습니다. logs/ 디렉터리의 로그 파일에서 시작 상태를 확인할 수 있습니다. fess.log 에는 Fess 자체의 메시지가, server_0.log 에는 내장 Tomcat의 메시지(시작 완료 메시지 포함)가 출력됩니다.

ZIP 버전의 경우(Windows)

OpenSearch 시작

1. OpenSearch 설치 디렉터리를 엽니다

2. bin 폴더 내의 opensearch.bat 을 더블클릭합니다

또는 명령 프롬프트에서:

C:\> cd C:\opensearch-3.9.0
C:\opensearch-3.9.0> bin\opensearch.bat

Fess 시작

1. Fess 설치 디렉터리를 엽니다

2. bin 폴더 내의 fess.bat 을 더블클릭합니다

또는 명령 프롬프트에서:

C:\> cd C:\fess-15.9.0
C:\fess-15.9.0> bin\fess.bat

RPM/DEB 버전의 경우 (chkconfig)

OpenSearch 시작:

$ sudo service opensearch start

Fess 시작:

$ sudo service fess start

시작 상태 확인:

$ sudo service fess status

RPM/DEB 버전의 경우 (systemd)

OpenSearch 시작:

$ sudo systemctl start opensearch.service

Fess 시작:

$ sudo systemctl start fess.service

시작 상태 확인:

$ sudo systemctl status fess.service

서비스 자동 시작 활성화:

$ sudo systemctl enable opensearch.service
$ sudo systemctl enable fess.service

Docker 버전의 경우

참고

compose.yaml 및 compose-opensearch3.yaml 은 Fess 자체에 포함되어 있지 않습니다. 이 파일들은 docker-fess 프로젝트(https://github.com/codelibs/docker-fess)에서 제공됩니다. 해당 리포지터리를 취득하여 compose 디렉터리 안에서 다음 명령을 실행하십시오.

Docker Compose를 사용하여 시작:

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

시작 상태 확인:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml ps

로그 확인:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01

시작 확인

Fess 가 정상적으로 시작되었는지 확인합니다.

헬스 체크

브라우저 또는 curl 명령으로 다음 URL에 액세스합니다:

http://localhost:8080/

정상적으로 시작된 경우 Fess의 검색 화면이 표시됩니다.

명령줄에서 확인:

$ curl -I http://localhost:8080/

HTTP/1.1 200 OK 가 반환되면 정상적으로 시작된 것입니다.

로그 확인

시작 로그를 확인하여 오류가 없는지 확인합니다.

ZIP 버전:

$ tail -f /path/to/fess-15.9.0/logs/fess.log

RPM/DEB 버전:

$ sudo tail -f /var/log/fess/fess.log

또는 journalctl 사용:

$ sudo journalctl -u fess.service -f

Docker 버전:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01

팁

시작이 정상적으로 완료되면 다음과 같은 시작 완료 메시지가 로그 디렉터리(ZIP 버전은 logs/, RPM/DEB 버전은 /var/log/fess/)의 server_0.log 에 출력됩니다. 콘솔에도 fess.log 에도 출력되지 않습니다:

...Booting the Tomcat: port=8080 contextPath=
...
Boot successful: url -> http://localhost:8080

브라우저에서 액세스

다음 URL에 액세스하여 웹 인터페이스를 확인합니다.

검색 화면

URL: http://localhost:8080/

Fess의 검색 화면이 표시됩니다. 초기 상태에서는 크롤 설정이 수행되지 않았기 때문에 검색 결과가 표시되지 않습니다.

검색 화면은 Fess 에 번들된 정적 테마 bootstrap 입니다. 외관을 변경하려면 관리 화면의 “시스템” > “테마”에서 또는 bin/fess-setup install theme <name> 으로 다른 테마를 설치하거나( fess-setup 명령 참조), 번들 테마를 복사하여 그 복사본을 변경하십시오( 번들 테마 커스터마이징 참조).

관리 화면

URL: http://localhost:8080/admin

기본 관리자 계정:

• 사용자 이름: admin

• 비밀번호: admin

경고

보안 관련 중요 주의사항

기본 비밀번호는 반드시 변경하십시오. 특히 운영 환경에서는 최초 로그인 후 즉시 비밀번호를 변경할 것을 강력히 권장합니다.

초기 설정

관리 화면에 로그인한 후 다음 초기 설정을 수행합니다.

단계 1: 관리자 비밀번호 변경

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

2. 왼쪽 메뉴에서 “사용자”→”사용자” 클릭

3. admin 사용자 클릭

4. 「비밀번호」 필드에 새 비밀번호를 입력합니다

5. 「비밀번호(확인)」 필드에 같은 비밀번호를 다시 입력합니다

6. 「갱신」 버튼을 클릭합니다

중요

비밀번호는 다음 조건을 충족할 것을 권장합니다:

• 8자 이상(password.min.length 로 설정된 최소 길이)

• 영문 대문자, 영문 소문자, 숫자, 기호를 조합

• 추측하기 어려운 것

기본적으로 최소 길이(8자) 조건만 적용되며, 문자 종류의 조합은 강제되지 않습니다. password.require.uppercase 등의 설정을 사용하여 문자 종류 조건을 활성화할 수 있습니다.

단계 2: 크롤 설정 생성

검색 대상 사이트나 파일 시스템을 크롤링하는 설정을 생성합니다.

1. 왼쪽 메뉴에서 “크롤러”→”웹” 클릭

2. “새로 만들기” 버튼 클릭

3. 필요한 정보 입력:

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

   • URL: 크롤 대상 URL(예: https://www.example.com/). 여러 URL을 지정하려면 한 줄에 하나씩 입력하십시오

   • 최대 액세스 수: 크롤할 문서 수의 상한(선택 사항)

   • 간격: 각 액세스 간의 대기 시간(밀리초. 기본값: 10000)

   참고

   위 항목 이외의 설정(사용자 에이전트, 스레드 수, 깊이 등)은 미입력 시 기본값이 사용됩니다.

4. “생성” 버튼 클릭

단계 3: 크롤 실행

1. 왼쪽 메뉴에서 [시스템] → [스케줄러] 클릭

2. [Default Crawler] 작업을 열고 “지금 시작” 버튼을 클릭합니다

3. 크롤이 완료될 때까지 기다립니다(진행 상황은 대시보드에서 확인 가능)

단계 4: 검색 확인

1. 검색 화면(http://localhost:8080/)에 액세스

2. 검색 키워드 입력

3. 검색 결과가 표시되는지 확인

참고

크롤에는 시간이 소요될 수 있습니다. 대규모 사이트의 경우 수 시간에서 수일이 걸릴 수도 있습니다.

기타 권장 설정

운영 환경에서 운용하는 경우 다음 설정도 검토하십시오.

환경 변수를 통한 주요 설정

포트 번호, JVM 힙 크기, OpenSearch 연결 URL 등의 설정은 환경 변수를 통해 변경할 수 있습니다. ZIP 버전은 bin/fess.in.sh, RPM 버전은 /etc/sysconfig/fess, DEB 버전은 /etc/default/fess 를 편집하십시오. 변경 후 Fess 를 재시작할 필요가 있습니다.

환경 변수	기본값	설명
FESS_PORT	8080	Fess 가 수신 대기하는 HTTP 포트입니다.
FESS_HEAP_SIZE	(미설정)	JVM 힙 크기입니다. 최솟값과 최댓값에 동일한 값을 설정합니다. 미설정 시 최솟값 256m, 최댓값 2g 가 사용되며(Windows ZIP 버전은 최댓값 1g), RPM/DEB 버전은 512m 이 사용됩니다.
SEARCH_ENGINE_HTTP_URL	http://localhost:9200	접속할 OpenSearch의 URL입니다. ZIP 버전에서는 bin/fess.in.sh 가 기본적으로 이 값을 설정합니다. OpenSearch를 다른 포트나 호스트에서 실행하는 경우 환경 변수로 설정하거나 bin/fess.in.sh 를 편집하십시오. RPM/DEB 버전은 패키지 환경 설정 파일에서 설정합니다.
FESS_LOG_LEVEL	warn	Fess 의 로그 레벨입니다.
FESS_HEAP_NEWSIZE	(미설정)	JVM 힙의 Young 영역 크기(-Xmn)입니다. 256m 과 같이 지정합니다. 미설정 시 JVM이 결정합니다.
FESS_TEMP_PATH	Fess 디렉터리 안의 temp (RPM/DEB 버전은 /var/tmp/fess)	임시 파일을 저장하는 디렉터리입니다(내장 Tomcat의 작업 디렉터리 포함). Fess 를 실행하는 사용자가 쓸 수 있어야 합니다.
FESS_CONF_PATH	(미설정) (RPM/DEB 버전은 /etc/fess)	설정 파일을 두는 디렉터리입니다. bin/fess 가 이 디렉터리를 클래스패스 맨 앞에 추가하고 -Dfess.conf.path 로 Fess 에 전달합니다. lib/classes 의 tomcat_config.properties 등은 이 디렉터리의 파일이 우선합니다. 다만 ZIP 버전의 웹 애플리케이션은 app/WEB-INF/classes 의 파일을 먼저 참조하므로, 이 디렉터리에 둔 fess_config.properties 로는 app/WEB-INF/classes 의 fess_config.properties 값을 덮어쓸 수 없습니다(크롤러 등 자식 프로세스는 이 디렉터리를 WEB-INF/classes 보다 먼저 참조합니다). ZIP 버전에서 fess_config.properties 를 변경할 때는 app/WEB-INF/classes 의 파일을 편집하십시오. RPM/DEB 버전은 app/WEB-INF/classes 에 fess_config.properties 를 포함하지 않고 /etc/fess 의 파일만 사용합니다.
FESS_USE_IPV4	(미설정)	비어 있지 않은 값을 설정하면 JVM이 IPv4 스택만 사용합니다(-Djava.net.preferIPv4Stack=true).
FESS_USE_GC_LOGGING	(미설정)	비어 있지 않은 값을 설정하면 JVM이 GC 로그를 로그 디렉터리의 gc-fess.log 에 기록합니다(64MB 파일 최대 5개).

참고

Windows ZIP 버전의 bin\fess.in.bat 이 참조하는 환경 변수는 이 표의 항목 중 FESS_HEAP_SIZE, FESS_HEAP_NEWSIZE, FESS_USE_IPV4, FESS_USE_GC_LOGGING 과 표에 없는 다음 환경 변수입니다.

• FESS_MIN_MEM, FESS_MAX_MEM: 최소·최대 힙 크기를 개별적으로 지정합니다(FESS_HEAP_SIZE 를 설정한 경우 무시됩니다).

• FESS_DIRECT_SIZE: 다이렉트 메모리의 상한(-XX:MaxDirectMemorySize)입니다.

• FESS_DICTIONARY_PATH: OpenSearch의 config\dictionary 디렉터리입니다.

• FESS_PROXY_HOST, FESS_PROXY_PORT, FESS_NON_PROXY_HOSTS: 프록시 설정입니다.

• FESS_JAVA_OPTS: 설정된 값 뒤에 fess.in.bat 이 JVM 옵션을 추가합니다.

• PLAYWRIGHT_NODEJS_PATH: Playwright 플러그인이 사용하는 Node.js 실행 파일입니다.

• JAVA_HOME: 필수입니다.

FESS_PORT, FESS_LOG_LEVEL, FESS_TEMP_PATH, FESS_CONF_PATH, SEARCH_ENGINE_HTTP_URL 은 참조되지 않습니다. 이 값들은 파일 안에 직접 기술되어 있으므로, 변경하려면 bin\fess.in.bat 을 직접 편집하십시오.

메일 서버 설정

장애 알림 등을 메일로 수신하려면 SMTP 서버와 알림 수신 주소를 설정합니다.

1. fess_env_web.properties 와 fess_env_crawler.properties 의 mail.smtp.server.main.host.and.port (기본값: localhost:25) 에 SMTP 서버 호스트와 포트를 지정합니다. 파일은 ZIP 패키지의 경우 app/WEB-INF/classes/ 에, RPM/DEB 패키지의 경우 /etc/fess/ 에 있습니다. 앞의 파일은 Fess 웹 프로세스가 읽고, 뒤의 파일은 크롤 완료 메일을 전송하는 크롤러가 읽습니다. fess_env.properties 는 사용되지 않습니다. 변경 후 Fess 를 재시작할 필요가 있습니다.

2. 관리 UI에서 왼쪽 메뉴의 [시스템] → [일반] 을 클릭합니다.

3. [알림 메일] 필드에 수신자 메일 주소를 입력합니다.

4. [갱신] 버튼을 클릭합니다.

5. [테스트 메일 보내기] 버튼으로 메일이 올바르게 발송되는지 확인할 수 있습니다.

시간대 설정

Fess 는 서버(OS / JVM)의 시간대를 사용합니다. 관리 UI에서 시간대를 변경하는 설정은 없습니다. 변경하려면 OS의 시간대 설정을 변경하거나, bin/fess.in.sh (Windows의 경우 bin\fess.in.bat) 의 FESS_JAVA_OPTS 에 JVM 옵션 -Duser.timezone=Asia/Tokyo 를 추가하십시오.

로그 레벨 조정

운영 환경에서는 로그 레벨을 조정하여 디스크 사용량을 억제할 수 있습니다.

Fess 전체의 로그 레벨은 FESS_LOG_LEVEL 환경 변수(기본값: warn)로 변경할 수 있습니다. 개별 로거를 세밀하게 제어하려면 설정 파일 app/WEB-INF/classes/log4j2.xml 을 편집하십시오. 크롤링, 서제스트, 썸네일 생성은 별도 프로세스로 실행되므로, 각각의 로그 레벨을 app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml 에서 개별적으로 설정하십시오.

자세한 내용은 Fess 관리자 가이드 를 참조하십시오.

중지 방법

ZIP 버전의 경우

Fess 중지

프로세스를 kill합니다:

$ ps aux | grep fess
$ kill <PID>

또는 Ctrl+C 로 콘솔에서 중지할 수 있습니다(포어그라운드에서 실행 중인 경우).

OpenSearch 중지:

$ ps aux | grep opensearch
$ kill <PID>

RPM/DEB 버전의 경우 (chkconfig)

Fess 중지:

$ sudo service fess stop

OpenSearch 중지:

$ sudo service opensearch stop

RPM/DEB 버전의 경우 (systemd)

Fess 중지:

$ sudo systemctl stop fess.service

OpenSearch 중지:

$ sudo systemctl stop opensearch.service

Docker 버전의 경우

컨테이너 중지:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop

컨테이너 중지 및 삭제:

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

경고

down 명령으로 볼륨도 삭제하는 경우 -v 옵션을 추가합니다. 이 경우 모든 데이터가 삭제되므로 주의하십시오.

재시작 방법

ZIP 버전의 경우

중지한 후 시작합니다.

RPM/DEB 버전의 경우

chkconfig:

$ sudo service fess restart

systemd:

$ sudo systemctl restart fess.service

Docker 버전의 경우

$ docker compose -f compose.yaml -f compose-opensearch3.yaml restart

문제 해결

시작되지 않는 경우

1. OpenSearch가 시작되어 있는지 확인

   $ curl http://localhost:9200/
   

   OpenSearch가 시작되어 있지 않은 경우 먼저 OpenSearch를 시작하십시오.

2. 포트 번호 충돌 확인

   $ sudo ss -tuln | grep 8080
   

   net-tools 가 설치되어 있는 환경에서는 sudo netstat -tuln | grep 8080 으로도 같은 내용을 확인할 수 있습니다.

   포트 8080이 이미 사용되고 있는 경우 포트 번호를 변경하십시오.

   • ZIP 버전: bin/fess.in.sh 의 FESS_PORT 를 변경합니다

   • ZIP 버전(Windows): bin\fess.in.bat 에서 -Dfess.port=8080 을 직접 편집합니다

   • RPM 버전: /etc/sysconfig/fess 의 FESS_PORT 를 변경합니다

   • DEB 버전: /etc/default/fess 의 FESS_PORT 를 변경합니다

3. 로그 확인

   오류 메시지를 확인하여 문제를 특정합니다.

4. Java 버전 확인

   $ java -version
   

   Java 21 이상이 설치되어 있는지 확인하십시오.

자세한 문제 해결에 대해서는 문제 해결 을 참조하십시오.

다음 단계

Fess 가 정상적으로 시작되면 다음 문서를 참조하여 운용을 시작하십시오:

• Fess 관리자 가이드 - 크롤 설정, 검색 설정, 시스템 설정의 상세

• 보안 설정 - 운영 환경의 보안 설정

• 문제 해결 - 일반적인 문제 및 해결 방법

• 업그레이드 절차 - 버전 업그레이드 절차

• 제거 절차 - 제거 절차