Windows 설치 (상세 절차)

이 페이지에서는 Windows 환경에 Fess 를 설치하는 절차를 설명합니다. ZIP 패키지를 사용한 설치 방법에 대해 기재하고 있습니다.

경고

운영 환경에서는 내장 OpenSearch를 사용한 운영을 권장하지 않습니다. 반드시 외부 OpenSearch 서버를 구축하시기 바랍니다.

전제 조건

시스템 요구사항 에 기재된 시스템 요구사항을 충족할 것
Java 21이 설치되어 있을 것
OpenSearch 3.7.0을 사용 가능한 상태로 할 것(또는 신규 설치)
Windows 환경 변수 JAVA_HOME 이 적절히 설정되어 있을 것

Java 설치 확인

명령 프롬프트 또는 PowerShell을 열고 다음 명령으로 Java 버전을 확인합니다.

명령 프롬프트의 경우:

PowerShell의 경우:

Java 21 이상이 표시되는지 확인하십시오.

환경 변수 설정

JAVA_HOME 환경 변수 설정

Java가 설치된 디렉터리를 JAVA_HOME 으로 설정합니다.

예:
```
JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot
```
PATH 환경 변수에 추가

%JAVA_HOME%\bin 을 PATH 환경 변수에 추가합니다.

팁

환경 변수 설정 방법:

“시작” 메뉴에서 “설정” 열기
“시스템”→”정보”→”고급 시스템 설정” 클릭
“환경 변수” 버튼 클릭
“시스템 환경 변수” 또는 “사용자 환경 변수”에서 설정

단계 1: OpenSearch 설치

OpenSearch 다운로드

Download OpenSearch 에서 Windows용 ZIP 패키지를 다운로드합니다.
다운로드한 ZIP 파일을 임의의 디렉터리에 압축 해제합니다.

예:
```
C:\opensearch-3.7.0
```
참고

경로에 한국어나 공백 문자가 포함되지 않은 디렉터리를 선택할 것을 권장합니다.

OpenSearch 플러그인 설치

명령 프롬프트를 관리자 권한으로 열고 다음 명령을 실행합니다.

C:\> cd C:\opensearch-3.7.0
C:\opensearch-3.7.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0
C:\opensearch-3.7.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0
C:\opensearch-3.7.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0
C:\opensearch-3.7.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0

중요

플러그인 버전은 OpenSearch 버전과 일치시켜야 합니다. 위의 예제에서는 모두 3.7.0을 지정하고 있습니다.

OpenSearch 설정

config\opensearch.yml 을 텍스트 편집기로 열고 다음 설정을 추가합니다.

# 설정 동기화용 경로(절대 경로로 지정)
configsync.config_path: C:/opensearch-3.7.0/data/config/

# 보안 플러그인 비활성화(개발 환경 전용)
plugins.security.disabled: true

경고

보안 관련 중요 주의사항

plugins.security.disabled: true 는 개발 환경이나 테스트 환경에서만 사용하십시오. 운영 환경에서는 OpenSearch의 보안 플러그인을 활성화하고 적절한 인증·권한 설정을 수행하십시오. 자세한 내용은 보안 설정 를 참조하십시오.

참고

Windows의 경우 경로 구분 문자는 \ 가 아닌 / 를 사용하십시오. C:\opensearch-3.7.0\data\config\ 가 아니라 C:/opensearch-3.7.0/data/config/ 로 기술합니다.

팁

기타 권장 설정:

팁

OpenSearch의 힙 크기는 config\jvm.options 의 -Xms / -Xmx 로 설정합니다. 사용 가능한 물리 메모리의 절반 이하이며 32GB 미만을 기준으로, -Xms 와 -Xmx 에는 동일한 값을 지정할 것을 권장합니다.

단계 2: Fess 설치

Fess 다운로드

다운로드 사이트 에서 Windows용 ZIP 패키지를 다운로드합니다.
다운로드한 ZIP 파일을 임의의 디렉터리에 압축 해제합니다.

예:
```
C:\fess-15.7.0
```
참고

경로에 한국어나 공백 문자가 포함되지 않은 디렉터리를 선택할 것을 권장합니다.

Fess 설정

bin\fess.in.bat 을 텍스트 편집기로 엽니다. 이 파일의 끝부분 근처에는 외부 OpenSearch 클러스터에 연결하기 위한 설정이 미리 주석 처리된 상태로 준비되어 있습니다.

변경 전(기본 상태):

REM External opensearch cluster
REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200
REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=%SEARCH_ENGINE_HOME%/config/

아래 2행의 행 시작 부분에 있는 REM `` 을 삭제하여 주석을 해제하고, ``fess.dictionary.path 의 값을 OpenSearch의 설정 동기화용 경로로 변경합니다.

변경 후:

REM External opensearch cluster
set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200
set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.7.0/data/config/

참고

fess.dictionary.path 에는 OpenSearch의 opensearch.yml 에서 지정한 configsync.config_path 와 동일한 경로를 설정하십시오.
OpenSearch를 다른 호스트에서 실행하는 경우 fess.search_engine.http_address 의 호스트 이름 또는 IP 주소를 적절한 값으로 변경하십시오.
경로 구분 문자는 / 를 사용하십시오.
새로 set FESS_JAVA_OPTS=... 행을 추가하는 것이 아니라 기존 주석 행을 해제하여 편집하십시오. 동일한 옵션을 중복하여 지정하면 의도하지 않은 동작의 원인이 될 수 있습니다.

팁

Fess 의 힙 크기를 변경하려면 bin\fess.in.bat 의 FESS_MIN_MEM (기본값: 256m) 과 FESS_MAX_MEM (기본값: 1g) 을 편집하거나 환경 변수 FESS_HEAP_SIZE 를 설정하십시오.

설치 확인

설정 파일이 올바르게 편집되었는지 확인합니다.

명령 프롬프트에서:

단계 3: 시작

시작 절차는 시작, 중지, 초기 설정 을 참조하십시오.

Windows 서비스로 등록(옵션)

Fess 를 Windows 서비스로 등록하면 시스템 시작 시 자동으로 시작되도록 설정할 수 있습니다.

Fess 에는 Windows 서비스를 등록하기 위한 bin\service.bat 가 동봉되어 있습니다. 이 스크립트는 Apache Commons Daemon (procrun)을 이용하고 있으므로 NSSM 등의 서드파티 도구를 별도로 준비할 필요가 없습니다.

참고

service.bat 를 실행하기 전에 환경 변수 JAVA_HOME 이 올바르게 설정되어 있는지 확인하십시오.

Fess 서비스 등록

명령 프롬프트를 관리자 권한으로 열고 다음 명령을 실행합니다.

서비스 등록:
```
C:\> cd C:\fess-15.7.0
C:\fess-15.7.0> bin\service.bat install
```
기본적으로 64비트 환경에서는 fess-service-x64, 32비트 환경에서는 fess-service-x86 이라는 서비스 ID로 등록됩니다. 서비스 ID를 명시적으로 지정하는 경우 bin\service.bat install <서비스ID> 와 같이 인수로 지정합니다.

서비스 시작·중지:

서비스 설정 확인·변경 (GUI):

서비스 삭제:
```
C:\fess-15.7.0> bin\service.bat remove
```

참고

service.bat 는 내부에서 bin\fess.in.bat 를 읽어 들이므로 “Fess 설정”에서 수행한 외부 OpenSearch 연결 설정이 서비스에도 반영됩니다.
기본 시작 유형은 “수동”입니다. 시스템 시작 시 자동으로 시작하려면 서비스 등록 전에 환경 변수 FESS_START_TYPE 을 auto 로 설정하거나, 등록 후 “서비스” 관리 도구(services.msc)에서 시작 유형을 “자동”으로 변경하십시오.
service.bat 로 등록할 수 있는 것은 Fess 서비스뿐입니다. OpenSearch를 서비스로 등록하는 경우에는 OpenSearch가 제공하는 절차를 참조하십시오.

방화벽 설정

Windows Defender 방화벽에서 필요한 포트를 개방합니다.

“제어판”→”Windows Defender 방화벽”→”고급 설정” 열기
“인바운드 규칙”에서 새 규칙 만들기
- 규칙 유형: 포트
- 프로토콜 및 포트: TCP, 8080
- 작업: 연결 허용
- 이름: Fess Web Interface

또는 PowerShell에서 실행:

문제 해결

포트 번호 충돌

포트 8080 또는 9200이 이미 사용 중인 경우 다음 명령으로 확인할 수 있습니다:

사용 중인 포트 번호를 변경하거나 충돌하는 프로세스를 중지하십시오.

경로 길이 제한

Windows에서는 경로 길이에 제한이 있습니다. 가능한 한 짧은 경로에 설치할 것을 권장합니다.

예:

Java가 인식되지 않음

java -version 명령에서 오류가 표시되는 경우:

JAVA_HOME 환경 변수가 올바르게 설정되어 있는지 확인
PATH 환경 변수에 %JAVA_HOME%\bin 이 포함되어 있는지 확인
명령 프롬프트를 재시작하여 설정 반영

다음 단계

설치가 완료되면 다음 문서를 참조하십시오:

시작, 중지, 초기 설정 - Fess 시작 및 초기 설정
보안 설정 - 운영 환경의 보안 설정
문제 해결 - 문제 해결

자주 묻는 질문

Q: Windows Server에서의 운영이 권장됩니까?

A: 예, Windows Server에서의 운영이 가능합니다. Windows Server에서 운영하는 경우 Windows 서비스로 등록하고 적절한 모니터링을 설정하십시오.

Q: 64비트 버전과 32비트 버전의 차이는?

A: Fess 및 OpenSearch는 64비트 버전만 지원합니다. 32비트 버전의 Windows에서는 작동하지 않습니다.

Q: 경로에 한국어가 포함된 경우 대처 방법은?

A: 가능한 한 한국어나 공백 문자가 포함되지 않은 경로에 설치하십시오. 어쩔 수 없이 한국어 경로를 사용해야 하는 경우 설정 파일에서 경로를 적절히 이스케이프해야 합니다.