runbooks/incus-meilisearch-manual.md

Incus에서 Meilisearch 실행 매뉴얼

목차

1. 기본 실행
2. 환경변수 설정
3. 포트 포워딩
4. 볼륨 마운트
5. Docker Compose 변환
6. 컨테이너 관리
7. 문제 해결

---

1. 기본 실행

간단한 실행

incus launch docker.io/getmeili/meilisearch meilisearch-container

리소스 제한과 함께 실행

incus launch docker.io/getmeili/meilisearch meilisearch-container \
  --config limits.cpu=2 \
  --config limits.memory=1GB

---

2. 환경변수 설정

컨테이너 생성 시 환경변수 설정

incus launch docker.io/getmeili/meilisearch meilisearch-container \
  --config environment.MEILI_MASTER_KEY=your-secret-key \
  --config environment.MEILI_ENV=production \
  --config environment.MEILI_DB_PATH=/data.ms

실행 중인 컨테이너에 환경변수 추가

# 컨테이너 중지
incus stop meilisearch-container

# 환경변수 설정
incus config set meilisearch-container environment.MEILI_MASTER_KEY=your-secret-key
incus config set meilisearch-container environment.MEILI_ENV=production
incus config set meilisearch-container environment.MEILI_DB_PATH=/data.ms

# 또는 한 번에 여러 개 설정
incus config set meilisearch-container \
  environment.MEILI_MASTER_KEY=your-secret-key \
  environment.MEILI_ENV=production \
  environment.MEILI_DB_PATH=/data.ms

# 컨테이너 재시작
incus restart meilisearch-container

환경변수 확인 및 삭제

# 모든 설정 확인
incus config show meilisearch-container

# 특정 환경변수 확인
incus config get meilisearch-container environment.MEILI_MASTER_KEY

# 환경변수 삭제
incus config unset meilisearch-container environment.MEILI_MASTER_KEY

---

3. 포트 포워딩

포트 7700 포워딩

incus config device add meilisearch-container http proxy \
  listen=tcp:0.0.0.0:7700 \
  connect=tcp:127.0.0.1:7700

여러 포트 포워딩

# HTTP 포트
incus config device add meilisearch-container http proxy \
  listen=tcp:0.0.0.0:7700 \
  connect=tcp:127.0.0.1:7700

# 추가 포트 (예: metrics)
incus config device add meilisearch-container metrics proxy \
  listen=tcp:0.0.0.0:8080 \
  connect=tcp:127.0.0.1:8080

포트 포워딩 확인

incus config device show meilisearch-container

---

4. 볼륨 마운트

데이터 디렉토리 마운트

# 호스트 디렉토리를 컨테이너에 마운트
incus config device add meilisearch-container data disk \
  source=/home/user/meilisearch-data \
  path=/data.ms

스토리지 풀 사용

# 스토리지 풀 생성
incus storage create meilisearch-pool dir

# 볼륨 생성
incus storage volume create meilisearch-pool meilisearch-data

# 볼륨 연결
incus config device add meilisearch-container data disk \
  pool=meilisearch-pool \
  source=meilisearch-data \
  path=/data.ms

---

5. Docker Compose 변환

Docker Compose 예시

version: '3'
services:
  meilisearch:
    image: getmeili/meilisearch:latest
    environment:
      - MEILI_MASTER_KEY=masterKey
      - MEILI_ENV=production
      - MEILI_DB_PATH=/data.ms
    ports:
      - "7700:7700"
    volumes:
      - ./data:/data.ms
    restart: always

Incus 명령어로 변환

#!/bin/bash
# meilisearch-setup.sh

# 1. 컨테이너 생성 및 환경변수 설정
incus launch docker.io/getmeili/meilisearch:latest meilisearch \
  --config environment.MEILI_MASTER_KEY=masterKey \
  --config environment.MEILI_ENV=production \
  --config environment.MEILI_DB_PATH=/data.ms

# 2. 포트 포워딩 설정
incus config device add meilisearch http proxy \
  listen=tcp:0.0.0.0:7700 \
  connect=tcp:127.0.0.1:7700

# 3. 볼륨 마운트
incus config device add meilisearch data disk \
  source=$(pwd)/data \
  path=/data.ms

# 4. 자동 재시작 설정
incus config set meilisearch boot.autostart=true

---

6. 컨테이너 관리

기본 명령어

# 시작
incus start meilisearch-container

# 중지
incus stop meilisearch-container

# 재시작
incus restart meilisearch-container

# 삭제
incus delete meilisearch-container --force

# 상태 확인
incus list meilisearch-container

로그 및 모니터링

# 로그 확인
incus logs meilisearch-container

# 실시간 로그
incus logs meilisearch-container --follow

# 컨테이너 접속
incus exec meilisearch-container -- /bin/bash

# 프로세스 확인
incus exec meilisearch-container -- ps aux

리소스 모니터링

# CPU/메모리 사용량
incus info meilisearch-container

# 상세 정보
incus config show meilisearch-container

---

7. 문제 해결

포트 접속 안 될 때

# 포트 포워딩 확인
incus config device show meilisearch-container

# 컨테이너 내부에서 서비스 확인
incus exec meilisearch-container -- netstat -tlnp

# 방화벽 확인 (호스트)
sudo ufw status

환경변수 적용 안 될 때

# 환경변수 확인
incus exec meilisearch-container -- env | grep MEILI

# 재시작
incus restart meilisearch-container

데이터 영속성 문제

# 마운트 확인
incus config device show meilisearch-container

# 권한 확인
incus exec meilisearch-container -- ls -la /data.ms

---

실전 예제

Production 환경 설정

#!/bin/bash

# 변수 설정
CONTAINER_NAME="meilisearch-prod"
MASTER_KEY="$(openssl rand -base64 32)"
DATA_PATH="/var/lib/meilisearch"

# 데이터 디렉토리 생성
sudo mkdir -p $DATA_PATH

# 컨테이너 생성
incus launch docker.io/getmeili/meilisearch:latest $CONTAINER_NAME \
  --config limits.cpu=4 \
  --config limits.memory=4GB \
  --config environment.MEILI_MASTER_KEY=$MASTER_KEY \
  --config environment.MEILI_ENV=production \
  --config environment.MEILI_DB_PATH=/data.ms \
  --config environment.MEILI_LOG_LEVEL=INFO

# 포트 설정
incus config device add $CONTAINER_NAME http proxy \
  listen=tcp:0.0.0.0:7700 \
  connect=tcp:127.0.0.1:7700

# 볼륨 마운트
incus config device add $CONTAINER_NAME data disk \
  source=$DATA_PATH \
  path=/data.ms

# 자동 시작 설정
incus config set $CONTAINER_NAME boot.autostart=true

echo "Meilisearch Master Key: $MASTER_KEY"
echo "Access URL: http://localhost:7700"

---

8. 프로덕션 보안 설정

Master Key 요구사항

Master Key는 최소 16바이트(128비트) 이상 권장. 짧은 키는 보안 취약점.

# 안전한 Master Key 생성 (32바이트)
openssl rand -base64 32

# 또는 hex 형식 (64자)
openssl rand -hex 32

프로덕션 설정 파일

/etc/meilisearch/config.toml 또는 환경변수로 설정:

# 프로덕션 모드 (필수)
env = "production"

# 강력한 Master Key (필수, 최소 16자 이상)
master_key = "your-secure-master-key-here"

# 데이터 경로
db_path = "/var/lib/meilisearch/data"
dump_dir = "/var/lib/meilisearch/dumps"
snapshot_dir = "/var/lib/meilisearch/snapshots"

# 스냅샷 자동 생성 (백업용)
schedule_snapshot = true
snapshot_interval_sec = 86400  # 24시간마다

# 로깅
log_level = "INFO"

# 성능 설정
max_indexing_memory = "2 GiB"
max_indexing_threads = 4

Incus 환경변수로 프로덕션 설정

incus config set meilisearch-prod \
  environment.MEILI_ENV=production \
  environment.MEILI_MASTER_KEY="$(openssl rand -base64 32)" \
  environment.MEILI_DB_PATH=/data.ms \
  environment.MEILI_DUMP_DIR=/data.ms/dumps \
  environment.MEILI_SNAPSHOT_DIR=/data.ms/snapshots \
  environment.MEILI_SCHEDULE_SNAPSHOT=true \
  environment.MEILI_SNAPSHOT_INTERVAL_SEC=86400 \
  environment.MEILI_LOG_LEVEL=INFO \
  environment.MEILI_MAX_INDEXING_MEMORY="2 GiB"

---

9. API 키 관리

Master Key는 절대 클라이언트에 노출하지 말 것. Admin/Search 키 분리 사용 필수.

키 유형

키 유형	권한	용도
Master Key	전체 권한	서버 관리자만 사용, 절대 노출 금지
Admin Key	인덱스 관리	백엔드 서버에서 데이터 인덱싱
Search Key	검색만	프론트엔드/클라이언트 검색

기본 API 키 조회

# Master Key로 API 키 목록 조회
curl -X GET 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY'

응답 예시

{
  "results": [
    {
      "name": "Default Search API Key",
      "key": "d0552b...",
      "actions": ["search"],
      "indexes": ["*"],
      "expiresAt": null
    },
    {
      "name": "Default Admin API Key",
      "key": "380689...",
      "actions": ["*"],
      "indexes": ["*"],
      "expiresAt": null
    }
  ]
}

커스텀 API 키 생성

# 특정 인덱스만 검색 가능한 키 생성
curl -X POST 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "name": "Products Search Key",
    "description": "Search products index only",
    "actions": ["search"],
    "indexes": ["products"],
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

클라이언트 사용 예시

// 프론트엔드: Search Key만 사용 (노출 OK)
const client = new MeiliSearch({
  host: 'https://search.example.com',
  apiKey: 'search-only-key-here'  // Search Key
});

// 검색만 가능
const results = await client.index('products').search('query');

# 백엔드: Admin Key 사용 (환경변수로 관리)
import os
from meilisearch import Client

client = Client(
    'http://localhost:7700',
    os.environ['MEILI_ADMIN_KEY']  # Admin Key
)

# 인덱싱 가능
client.index('products').add_documents(documents)

---

10. 백업 및 복구

스냅샷 (자동 백업)

# 스냅샷 수동 생성
curl -X POST 'http://localhost:7700/snapshots' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY'

# 스냅샷 파일 위치
ls /var/lib/meilisearch/snapshots/

덤프 (이식 가능한 백업)

# 덤프 생성 (JSON 형식, 버전 간 호환)
curl -X POST 'http://localhost:7700/dumps' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY'

# 덤프 상태 확인
curl -X GET 'http://localhost:7700/tasks?types=dumpCreation' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY'

덤프에서 복구

# 새 인스턴스에서 덤프 복구
incus launch docker.io/getmeili/meilisearch meilisearch-restore \
  --config environment.MEILI_MASTER_KEY=your-key \
  --config environment.MEILI_IMPORT_DUMP=/dumps/20260116-123456.dump

---

참고 사항

• Meilisearch 기본 포트: 7700
• 프로덕션 모드: MEILI_ENV=production 필수 (개발 모드는 Master Key 없이 실행됨)
• Master Key: 최소 16바이트 이상, 32바이트 권장
• API 키 분리: Master Key 노출 금지, Admin/Search 키 분리 사용
• 데이터 영속성을 위해 볼륨 마운트 권장
• 리소스 제한 설정으로 시스템 안정성 확보
• 백업 전략: 스냅샷(빠른 복구) + 덤프(버전 간 호환) 병행

---

추가 리소스

• Meilisearch 공식 문서
• Incus 공식 문서
• Docker Hub - Meilisearch