python-api/docs/DEPLOYMENT.md

# 배포 가이드

## 1. 전제 조건

### 호스트에 직접 설치 (Docker 외부)
- **MariaDB** 10.6+ — 관계형 데이터 저장
- **MongoDB** 7.0+ — 문서 데이터 저장

### Docker로 관리
- **Docker** 24.0+
- **Docker Compose** v2

---

## 2. 최초 설정

### 2.1 환경변수

```bash
cp .env.example .env
```

`.env` 파일에서 반드시 변경해야 할 항목:

```bash
# 보안 키 (반드시 변경)
SECRET_KEY=<랜덤 문자열>
JWT_SECRET_KEY=<랜덤 문자열>

# MariaDB 접속 정보
MARIADB_HOST=127.0.0.1
MARIADB_PORT=3306
MARIADB_USER=core_api_user
MARIADB_PASSWORD=<강력한 비밀번호>
MARIADB_DATABASE=core_api

# MongoDB 접속 정보
MONGODB_URL=mongodb://127.0.0.1:27017
MONGODB_DATABASE=core_api
```

### 2.2 MariaDB 준비

```sql
CREATE DATABASE core_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'core_api_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON core_api.* TO 'core_api_user'@'%';
FLUSH PRIVILEGES;
```

### 2.3 MongoDB 준비

```javascript
use core_api
db.createUser({
  user: "core_api_user",
  pwd: "your_password",
  roles: [{ role: "readWrite", db: "core_api" }]
})
```

---

## 3. 개발 환경

### 3.1 로컬 실행

```bash
# 의존성 설치
pip install -e ".[dev]"

# DB 마이그레이션
alembic upgrade head

# 시드 데이터
python -m scripts.init_db

# 관리자 계정 생성
python -m scripts.create_superuser admin@example.com password123

# 인프라 시작 (Redis + Mosquitto)
docker-compose up -d redis mosquitto

# 앱 서버
uvicorn app.asgi:app --reload --host 0.0.0.0 --port 8000

# Celery 워커 (별도 터미널)
celery -A app.tasks.celery_app worker --loglevel=info \
  -Q default,analytics,notifications,devices

# Celery 스케줄러 (별도 터미널)
celery -A app.tasks.celery_app beat --loglevel=info
```

### 3.2 Docker 전체 스택

```bash
docker-compose up -d
```

서비스 확인:
- API: http://localhost:8000/docs
- Flower: http://localhost:5555

---

## 4. 프로덕션 배포

### 4.1 Docker Compose

```bash
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

프로덕션 차이점:
- Uvicorn 워커 4개 (`--workers 4`)
- Celery 동시성 4, Worker 레플리카 2
- Flower 기본 인증 활성화
- 소스 코드 볼륨 마운트 없음 (이미지 내장)
- 로그 레벨 `warning`

### 4.2 환경변수 (프로덕션 추가)

```bash
APP_ENV=production
DEBUG=false
LOG_LEVEL=WARNING

# Flower 인증
FLOWER_USER=admin
FLOWER_PASSWORD=<강력한 비밀번호>

# CORS (실제 도메인)
CORS_ORIGINS=["https://your-domain.com"]
```

### 4.3 리버스 프록시 (Nginx 예시)

```nginx
upstream core_api {
    server 127.0.0.1:8000;
}

server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://core_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /socket.io/ {
        proxy_pass http://core_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

---

## 5. 서비스 구성

```
┌────────────────────────────────────────────────────┐
│                Docker Compose                       │
│                                                    │
│  ┌─────────┐  ┌─────────┐  ┌────────┐  ┌───────┐ │
│  │   App   │  │ Worker  │  │  Beat  │  │Flower │ │
│  │ :8000   │  │ (x2)    │  │        │  │ :5555 │ │
│  └────┬────┘  └────┬────┘  └───┬────┘  └───┬───┘ │
│       │            │           │            │     │
│  ┌────┴────┐  ┌────┴──────────┴────────────┘     │
│  │  Redis  │  │                                   │
│  │ :6379   │  │                                   │
│  └─────────┘  │                                   │
│  ┌────────────┘                                   │
│  │ Mosquitto │                                    │
│  │ :1883     │                                    │
│  └───────────┘                                    │
└────────────────────────────────────────────────────┘
         │                    │
    ┌────┴────┐          ┌───┴────┐
    │ MariaDB │          │MongoDB │
    │ (호스트) │          │(호스트) │
    └─────────┘          └────────┘
```

---

## 6. 헬스체크

```bash
# 기본 헬스체크
curl http://localhost:8000/api/v1/system/health
# → {"status": "ok", "service": "core-api", "version": "0.1.0"}

# 상세 시스템 상태 (인증 필요)
curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/v1/monitoring/health

# Docker 서비스 상태
docker-compose ps

# Celery 워커 상태
docker-compose logs worker

# Celery 활성 태스크
docker-compose exec worker celery -A app.tasks.celery_app inspect active
```

---

## 7. 로그

### 개발 환경
- structlog 콘솔 렌더러 (사람이 읽기 좋은 형식)
- 로그 레벨: DEBUG

### 프로덕션 환경
- structlog JSON 렌더러 (ELK/Grafana 연동)
- 로그 레벨: WARNING

```bash
# 실시간 로그 확인
docker-compose logs -f app
docker-compose logs -f worker
```

---

## 8. 백업

### MariaDB
```bash
mysqldump -u root -p core_api > backup_$(date +%Y%m%d).sql
```

### MongoDB
```bash
mongodump --db core_api --out backup_$(date +%Y%m%d)
```

---

## 9. 트러블슈팅

| 증상 | 원인 | 해결 |
|------|------|------|
| `Cannot connect to MySQL` | MariaDB 미실행 또는 접속 정보 오류 | `.env` 확인, MariaDB 상태 확인 |
| `MongoDB not initialized` | MongoDB 미실행 | MongoDB 서비스 시작 |
| `Redis connection refused` | Redis 미실행 | `docker-compose up -d redis` |
| Celery 태스크 실행 안 됨 | Worker 미실행 또는 큐 불일치 | Worker 로그 확인, 큐 이름 확인 |
| Socket.IO 연결 실패 | CORS 설정 누락 | `CORS_ORIGINS`에 클라이언트 URL 추가 |
| MQTT 연결 실패 | Mosquitto 미실행 | `docker-compose up -d mosquitto` |