Neo4j 로컬 환경(Docker 또는 독립형 실행) 환경변수 설정 방법 플러그인(APOC 등) 설치 방법

1. Neo4j 환경변수(Environment Variables) 설정

Neo4j의 설정은 주로 neo4j.conf 파일에서 관리하지만, Docker를 사용하거나 서버를 띄울 때는 환경변수(-e 옵션 또는 시스템 환경변수)로 간편하게 주입할 수 있습니다. 주요 환경변수 규칙과 핵심 설정은 다음과 같습니다.

환경변수 명명 규칙: Neo4j 설정 항목은 대문자로 바꾸고, 계층 구조는 언더바(_)로 연결하며 앞에 NEO4J_를 붙입니다. (예: dbms.memory.heap.initial_size $\rightarrow$ NEO4J_dbms_memory_heap_initial__size)

핵심 환경변수 목록

Bash

# 1. 초기 인증 설정 (최초 실행 시 비밀번호 설정, 또는 보안 해제)
NEO4J_AUTH=neo4j/your_strong_password

# 2. 프로시저 플러그인 허용 및 파일 import/export 권한 개방 (Graph RAG 구축 시 필수)
NEO4J_apoc_export_file_enabled=true
NEO4J_apoc_import_file_enabled=true
NEO4J_dbms_security_procedures_unrestricted=apoc.*,gds.*

# 3. 플러그인 자동 다운로드 및 설치 (Docker 실행 시)
NEO4J_PLUGINS='["apoc", "graph-data-science"]'

2. Neo4j 플러그인(Plugin) 설치 방법

Graph RAG나 대규모 데이터 연산을 수행할 때는 유틸리티 모음인 APOC(Awesome Procedures On Cypher) 플러그인이 필수입니다. 운영 환경과 설치 방식에 따라 아래 방법 중 선택할 수 있습니다.

① Docker 컨테이너로 실행할 때 (가장 간편한 방법)

Docker로 Neo4j를 띄울 때 NEO4J_PLUGINS 환경변수를 지정하면 컨테이너가 실행되면서 자동으로 플러그인을 다운로드하고 활성화합니다.

Bash

docker run \
  -p 7474:7474 -p 7687:7687 \
  --name neo4j-saju-rag \
  -e NEO4J_AUTH=neo4j/your_password \
  -e NEO4J_PLUGINS='["apoc"]' \
  -e NEO4J_dbms_security_procedures_unrestricted=apoc.* \
  neo4j:latest

② Neo4j Desktop을 사용할 때 (로컬 개발용 GUI)

Neo4j Desktop 앱을 실행하고 프로젝트 내의 Database 카드를 선택합니다.
하단의 Plugins 탭을 클릭합니다.
APOC 항목에서 Install 버튼을 누르면 자동으로 설치됩니다.
설치 후 데이터베이스를 Start 하면 즉시 적용됩니다.

③ 수동 설치 (Tarball / 독립형 서버)

Neo4j 공식 홈페이지나 GitHub에서 사용하는 Neo4j 버전과 정확히 일치하는 버전의 APOC .jar 파일을 다운로드합니다 (예: Neo4j 5.x 대라면 APOC 5.x 최신 패치 버전).
다운로드한 .jar 파일을 Neo4j 설치 경로 내의 plugins/ 폴더에 집어넣습니다.
conf/neo4j.conf 파일을 열어 아래 설정을 추가하여 보안 권한을 풀어줍니다.

Plaintext

dbms.security.procedures.unrestricted=apoc.*
apoc.export.file.enabled=true
apoc.import.file.enabled=true

Neo4j 서버를 재시작합니다.

3. 설치 확인 방법

Neo4j Browser(웹 UI, 대개 http://localhost:7474)에 접속한 뒤, 아래 쿼리를 실행하여 정상 작동 여부를 확인할 수 있습니다.

Cypher

RETURN apoc.version() AS version;

버전 정보(예: 5.x.x)가 정상적으로 출력된다면 APOC 플러그인과 환경 설정이 완벽하게 완료된 것입니다.

BUGAF