runbooks/incus-meilisearch-manual.md

# Incus에서 Meilisearch 실행 매뉴얼

## 목차
1. [기본 실행](#1-기본-실행)
2. [환경변수 설정](#2-환경변수-설정)
3. [포트 포워딩](#3-포트-포워딩)
4. [볼륨 마운트](#4-볼륨-마운트)
5. [Docker Compose 변환](#5-docker-compose-변환)
6. [컨테이너 관리](#6-컨테이너-관리)
7. [문제 해결](#7-문제-해결)

---

## 1. 기본 실행

### 간단한 실행
```bash
incus launch docker.io/getmeili/meilisearch meilisearch-container
```

### 리소스 제한과 함께 실행
```bash
incus launch docker.io/getmeili/meilisearch meilisearch-container \
  --config limits.cpu=2 \
  --config limits.memory=1GB
```

---

## 2. 환경변수 설정

### 컨테이너 생성 시 환경변수 설정
```bash
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
```

### 실행 중인 컨테이너에 환경변수 추가
```bash
# 컨테이너 중지
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
```

### 환경변수 확인 및 삭제
```bash
# 모든 설정 확인
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 포워딩
```bash
incus config device add meilisearch-container http proxy \
  listen=tcp:0.0.0.0:7700 \
  connect=tcp:127.0.0.1:7700
```

### 여러 포트 포워딩
```bash
# 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
```

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

---

## 4. 볼륨 마운트

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

### 스토리지 풀 사용
```bash
# 스토리지 풀 생성
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 예시
```yaml
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 명령어로 변환
```bash
#!/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. 컨테이너 관리

### 기본 명령어
```bash
# 시작
incus start meilisearch-container

# 중지
incus stop meilisearch-container

# 재시작
incus restart meilisearch-container

# 삭제
incus delete meilisearch-container --force

# 상태 확인
incus list meilisearch-container
```

### 로그 및 모니터링
```bash
# 로그 확인
incus logs meilisearch-container

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

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

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

### 리소스 모니터링
```bash
# CPU/메모리 사용량
incus info meilisearch-container

# 상세 정보
incus config show meilisearch-container
```

---

## 7. 문제 해결

### 포트 접속 안 될 때
```bash
# 포트 포워딩 확인
incus config device show meilisearch-container

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

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

### 환경변수 적용 안 될 때
```bash
# 환경변수 확인
incus exec meilisearch-container -- env | grep MEILI

# 재시작
incus restart meilisearch-container
```

### 데이터 영속성 문제
```bash
# 마운트 확인
incus config device show meilisearch-container

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

---

## 실전 예제

### Production 환경 설정
```bash
#!/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 공식 문서](https://docs.meilisearch.com/)
- [Incus 공식 문서](https://linuxcontainers.org/incus/docs/main/)
- [Docker Hub - Meilisearch](https://hub.docker.com/r/getmeili/meilisearch)