[PostgreSQL] Docker에 MeCab 설치하기 (Mac M4 pro 기준)

최근 프로젝트에서 챗봇에 간단한 실시간 정보를 넣어야 하는 태스크를 맡았는데, 최소한의 자원으로 시작하기 위해 PostgreSQL의 FTS(Full-Text Search)를 테스트해야 했습니다.

 

이미 Docker로 DB는 잘 돌아가는 중이어서, 실행 중인 Docker 컨테이너 내부에 MeCab 형태소 분석기를 설치하는 게 주 목표였습니다. 다른 여러 블로그들이 도움이 되었지만 대부분 리눅스에 직접 설치하는 글이어서 저처럼 Docker 내부에 바로 설치하고 싶은 사람들을 위한 글은 찾기 어려웠습니다.

 

그 과정에서 온갖 에러를 만났기 때문에, 비슷한 문제를 겪는 분들께 도움이 될까 싶어 과정을 공유합니다.

---

Docker 안에서 한국어 FTS (Full-Text Search)쓰기

• 이미 실행 중인 PostgreSQL Docker 컨테이너에 MeCab과 한국어 사전을 설치합니다.
• PostgreSQL에서 MeCab을 사용하기 위한 textsearch_ko 확장을 설정합니다.
• 설치 과정에서 흔히 발생하는 주요 오류(libmecab.so.2, contrib-global.mk 등)를 해결합니다.
• 최종적으로 한국어 형태소 분석이 잘 동작하는지 확인합니다.

---

사전 확인

우선 작업 대상인 PostgreSQL Docker 컨테이너가 실행 중인지 확인해야 합니다. 아래 명령어로 컨테이너 이름을 확인해두세요. 이 글에서는 제 컨테이너 이름인 postgres-pgvector를 기준으로 설명하겠습니다.

docker ps

---

전체 설치 스크립트

전체 과정을 담은 셸 스크립트입니다. 급하신 분들은 이 스크립트의 CONTAINER_NAME 변수만 본인의 컨테이너 이름으로 바꾸고 install_mecab.sh 같은 파일로 저장해서 실행하시면 됩니다. 각 단계에 대한 자세한 설명과 제가 겪었던 에러 해결법은 스크립트 아래에 정리해 두었습니다.

#!/bin/bash

# 실행 중인 PostgreSQL 컨테이너에 MeCab을 설치하는 스크립트

echo "🔧 실행 중인 PostgreSQL 컨테이너에 MeCab 설치를 시작합니다."
echo "================================================================"

# 1. 대상 컨테이너 설정
# ❗️ 본인의 PostgreSQL 컨테이너 이름으로 꼭 변경해주세요!
CONTAINER_NAME="postgres-pgvector" 

# 컨테이너 실행 여부 확인
echo "1. 실행 중인 PostgreSQL 컨테이너를 확인합니다..."
if ! docker ps | grep -q $CONTAINER_NAME; then
    echo "❌ '${CONTAINER_NAME}' 컨테이너가 실행 중이지 않습니다."
    exit 1
fi
echo "✅ PostgreSQL 컨테이너 발견: ${CONTAINER_NAME}"

# 2. 필수 빌드 도구 설치
echo "2. 컴파일을 위한 필수 빌드 도구를 설치합니다..."
docker exec $CONTAINER_NAME bash -c "
    apt-get update && \
    apt-get install -y build-essential autotools-dev automake autoconf libtool curl wget unzip postgresql-server-dev-all
"
if [ $? -ne 0 ]; then echo "❌ 빌드 도구 설치 실패"; exit 1; fi
echo "✅ 빌드 도구 설치 완료"

# 3. MeCab-ko (형태소 분석기 엔진) 설치
echo "3. MeCab-ko (형태소 분석기 엔진)를 설치합니다..."
docker exec $CONTAINER_NAME bash -c "
    cd /tmp && \
    curl -LO https://bitbucket.org/eunjeon/mecab-ko/downloads/mecab-0.996-ko-0.9.2.tar.gz && \
    tar zxfv mecab-0.996-ko-0.9.2.tar.gz && \
    cd mecab-0.996-ko-0.9.2 && \
    ./configure && \
    make && \
    make install
"
# 참고: Apple Silicon (M1, M2 등) 환경의 Docker라면 ./configure 대신 아래처럼 아키텍처를 명시해야 합니다.
# ./configure --build=aarch64-unknown-linux-gnu && \
if [ $? -ne 0 ]; then echo "❌ MeCab-ko 설치 실패"; exit 1; fi
echo "✅ MeCab-ko 설치 완료"

# 4. MeCab-ko-dic (한국어 사전) 설치
echo "4. MeCab-ko-dic (한국어 사전)을 설치합니다..."
docker exec $CONTAINER_NAME bash -c "
    cd /tmp && \
    curl -LO https://bitbucket.org/eunjeon/mecab-ko-dic/downloads/mecab-ko-dic-2.1.1-20180720.tar.gz && \
    tar -zxvf mecab-ko-dic-2.1.1-20180720.tar.gz && \
    cd mecab-ko-dic-2.1.1-20180720 && \
    ./autogen.sh && \
    ./configure && \
    make && \
    sh -c 'echo \"dicdir=/usr/local/lib/mecab/dic/mecab-ko-dic\" > /usr/local/etc/mecabrc' && \
    make install
"
if [ $? -ne 0 ]; then echo "❌ MeCab-ko-dic 설치 실패"; exit 1; fi
echo "✅ MeCab-ko-dic 설치 완료"

# 5. textsearch_ko (PostgreSQL 확장) 설치
echo "5. textsearch_ko PostgreSQL 확장을 설치합니다..."
docker exec $CONTAINER_NAME bash -c "
    cd /tmp && \
    wget https://github.com/i0seph/textsearch_ko/archive/master.zip -O textsearch_ko.zip && \
    unzip -o textsearch_ko.zip && \
    cd textsearch_ko-master && \
    USE_PGXS=1 make && \
    USE_PGXS=1 make install
"
if [ $? -ne 0 ]; then echo "❌ textsearch_ko 설치 실패"; exit 1; fi
echo "✅ textsearch_ko PostgreSQL 확장 설치 완료"

# 6. 공유 라이브러리 경로 설정 및 캐시 업데이트
echo "6. 공유 라이브러리 경로를 설정하고 캐시를 업데이트합니다..."
docker exec $CONTAINER_NAME bash -c "
    echo '/usr/local/lib' >> /etc/ld.so.conf && \
    ldconfig
"
echo "✅ 라이브러리 설정 완료"

# 7. PostgreSQL에서 확장 활성화
echo "7. PostgreSQL에서 textsearch_ko 확장을 활성화합니다..."
docker exec $CONTAINER_NAME psql -U postgres -d postgres -c "
    CREATE EXTENSION IF NOT EXISTS textsearch_ko;
    DROP TEXT SEARCH DICTIONARY IF EXISTS mecabko;
    CREATE TEXT SEARCH DICTIONARY mecabko (TEMPLATE = mecabko_template);
    DROP TEXT SEARCH CONFIGURATION IF EXISTS korean_mecab;
    CREATE TEXT SEARCH CONFIGURATION korean_mecab (PARSER = default);
    ALTER TEXT SEARCH CONFIGURATION korean_mecab
        ADD MAPPING FOR n, N, np, v, va, vx, vcp, vcn, adv, a, ad, j, m, i, uf, u, x, p, sf, se, ss, sp, so, sw, e, f
        WITH mecabko;
"
if [ $? -ne 0 ]; then echo "❌ PostgreSQL 확장 활성화 실패"; exit 1; fi
echo "✅ PostgreSQL 확장 활성화 완료"

# 8. 최종 테스트
echo "8. MeCab 형태소 분석 테스트를 실행합니다..."
docker exec $CONTAINER_NAME psql -U postgres -d postgres -c "
    SELECT to_tsvector('korean_mecab', '서울시 성동구 답십리동 티스토리 입니다');
"
if [ $? -ne 0 ]; then echo "❌ MeCab 형태소 분석 테스트 실패"; exit 1; fi
echo "✅ MeCab 형태소 분석 테스트 완료"

# 9. 정리
echo "9. 임시 설치 파일들을 정리합니다..."
docker exec $CONTAINER_NAME bash -c "rm -rf /tmp/mecab-* /tmp/textsearch_ko*"
echo "✅ 정리 완료"

echo ""
echo "🎉 모든 설치 과정이 성공적으로 완료되었습니다!"

---

단계별 설명 및 에러 해결 가이드

스크립트가 한 번에 잘 돌면 좋겠지만 ㅜㅜ 그렇진 않더라구요. 참고했던 블로그들은 아래에 적어놓겠습니다.

1. 필수 빌드 도구 설치

MeCab은 소스 코드를 직접 컴파일해서 설치하는 방식이라 관련 도구들이 필요합니다. build-essential, make 같은 기본적인 것들과 함께 postgresql-server-dev-all 패키지를 꼭 설치해야 합니다.

• 에러: make: *** No rule to make target '/contrib/contrib-global.mk'. Stop.
• 원인과 해결: 이 에러는 PostgreSQL 확장 모듈을 빌드하는 데 필요한 파일이 없어서 발생합니다. postgresql-server-dev-all 패키지를 설치하면 필요한 파일들이 모두 준비되기 때문에 이 문제를 해결할 수 있습니다. 스크립트 2번 단계가 바로 이 역할을 합니다.

2. MeCab-ko와 사전 설치

MeCab 엔진과 한국어 사전을 차례대로 설치합니다. 여기서 중요한 점은 실행 환경의 아키텍처입니다.

• 에러: 제 로컬 환경은 Apple Silicon(M4 Pro)인데, 이 때문에 컴파일 과정에서 오류가 발생했습니다.
• 원인과 해결: Docker 컨테이너의 아키텍처와 로컬 환경이 다를 수 있기 때문입니다. 특히 ./configure를 실행할 때 --build=aarch64-unknown-linux-gnu 같은 옵션을 명시적으로 추가해줘야 했습니다. 일반적인 Intel, AMD CPU 환경에서는 그냥 ./configure만 실행해도 문제없을 겁니다.

3. textsearch_ko 확장 설치 및 라이브러리 경로 설정

MeCab을 PostgreSQL과 연결해주는 textsearch_ko를 설치하고, 시스템이 MeCab 라이브러리를 찾을 수 있도록 경로를 알려주는 단계입니다. 

• 에러: error while loading shared libraries: libmecab.so.2: cannot open shared object file: No such file or directory
• 원인과 해결: MeCab 라이브러리 파일(libmecab.so.2)은 /usr/local/lib에 설치되는데, 시스템이 이 경로를 기본적으로 참고하지 않아서 파일을 못 찾는다는 의미입니다. 해결책은 이 경로를 시스템에 등록해주는 겁니다. 스크립트 6번의 echo '/usr/local/lib' >> /etc/ld.so.conf 명령어로 경로를 추가하고, ldconfig 명령어로 시스템 캐시를 갱신하면 PostgreSQL이 라이브러리를 정상적으로 찾을 수 있습니다.

4. PostgreSQL 확장 활성화

마지막으로 DB에 접속해서 textsearch_ko를 활성화하고, korean_mecab이라는 이름으로 한국어 FTS 설정을 만들어주면 됩니다.

• 에러: ERROR: function "ts_mecabko_start" already exists with same argument types
• 원인과 해결: CREATE EXTENSION을 실행했으니 korean_mecab 같은 설정이 자동으로 생길 줄 알았는데 없더라구요. 설치를 여러 번 시도하다 보면 이전에 만들었던 설정이 DB에 그대로 남아있어서 발생하는 문제입니다. 스크립트를 재실행해도 문제가 없도록, 스크립트 7번 단계에서는 CREATE 전에 DROP ... IF EXISTS 구문을 넣어 기존 설정을 깨끗하게 지우고 새로 만들도록 구성했습니다.

 

/* 1. MeCab 도구(확장)를 현재 데이터베이스에 등록 */
CREATE EXTENSION IF NOT EXISTS textsearch_ko;

/* 2. mecabko라는 이름의 '사전' 만들기 */
-- 이전에 만들었던 설정이 있다면 삭제 (스크립트를 여러 번 실행해도 안전하게)
DROP TEXT SEARCH DICTIONARY IF EXISTS mecabko; 
-- textsearch_ko가 제공하는 'mecabko_template'을 사용해서 mecabko 사전을 생성
CREATE TEXT SEARCH DICTIONARY mecabko (TEMPLATE = mecabko_template);

/* 3. korean_mecab이라는 이름의 '검색 설정' 만들기 */
-- 기존 설정이 있다면 삭제
DROP TEXT SEARCH CONFIGURATION IF EXISTS korean_mecab;
-- 'korean_mecab'이라는 이름으로 비어있는 검색 설정을 생성 (기본 파서 사용)
CREATE TEXT SEARCH CONFIGURATION korean_mecab (PARSER = default);

/* 4. '검색 설정'에 '사전'을 연결하는 규칙 추가 */
-- korean_mecab 설정에서 특정 품사(명사, 동사 등)들을 어떻게 처리할지 지정
ALTER TEXT SEARCH CONFIGURATION korean_mecab
    ADD MAPPING FOR n, N, np, v, va, vx, vcp, vcn, adv, a, ad, j, m, i, uf, u, x, p, sf, se, ss, sp, so, sw, e, f
    WITH mecabko; -- 이 품사들은 위에서 만든 'mecabko 사전'을 사용해 분석하라고 지정

---

최종 확인

docker exec으로 내부에서 psql을 실행하거나, 다른 방법으로 sql으로 테스트하면 아래와 같이 사용할 수 있습니다.

 

postgres=# SELECT to_tsvector('korean_mecab', '안녕하세요. 어떤 테스트를 해볼까요?');

 

 

실제 검색 쿼리의 예시

 

-- 'content' 컬럼에 한국어 FTS 인덱스 생성
CREATE INDEX idx_fts_content ON documents USING gin(to_tsvector('korean_mecab', content));

-- '자연어'와 '처리'가 모두 포함된 문서 검색
SELECT * FROM documents WHERE to_tsvector('korean_mecab', content) @@ to_tsquery('korean_mecab', '자연어&처리');

 

 

참고 블로그

가장 많이 참고한 글: https://kingsurvival.tistory.com/76#google_vignette

형태소 분석기 설치 및 적용

 

postgres의 기본 내장 FTS에 대한 글: https://overcome-the-limits.tistory.com/856

프로젝트 삽질기16 (feat PostgreSQL 검색)

 

에러 처리 중 참고: https://uiandwe.tistory.com/1367

lambda docker 이미지에 mecab 설치

 

에러 처리 중 참고2: https://acdongpgm.tistory.com/289#google_vignette

[error]. arm64 에서 Mecab 설치시 에러 해결법