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"

---

참고 사항

• Meilisearch 기본 포트: 7700
• 프로덕션 환경에서는 반드시 MEILI_MASTER_KEY 설정
• 데이터 영속성을 위해 볼륨 마운트 권장
• 리소스 제한 설정으로 시스템 안정성 확보
• 정기적인 백업 필요 (데이터 디렉토리 백업)

---

추가 리소스

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