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"
```

---

## 8. 프로덕션 보안 설정

### Master Key 요구사항

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

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

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

### 프로덕션 설정 파일

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

```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 환경변수로 프로덕션 설정

```bash
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 키 조회

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

### 응답 예시

```json
{
  "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 키 생성

```bash
# 특정 인덱스만 검색 가능한 키 생성
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"
  }'
```

### 클라이언트 사용 예시

```javascript
// 프론트엔드: 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');
```

```python
# 백엔드: 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. 백업 및 복구

### 스냅샷 (자동 백업)

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

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

### 덤프 (이식 가능한 백업)

```bash
# 덤프 생성 (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'
```

### 덤프에서 복구

```bash
# 새 인스턴스에서 덤프 복구
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 공식 문서](https://docs.meilisearch.com/)
- [Incus 공식 문서](https://linuxcontainers.org/incus/docs/main/)
- [Docker Hub - Meilisearch](https://hub.docker.com/r/getmeili/meilisearch)