python-api/docs/DEPLOYMENT.md

배포 가이드

1. 전제 조건

호스트에 직접 설치 (Docker 외부)

• MariaDB 10.6+ — 관계형 데이터 저장
• MongoDB 7.0+ — 문서 데이터 저장

Docker로 관리

• Docker 24.0+
• Docker Compose v2

---

2. 최초 설정

2.1 환경변수

cp .env.example .env

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

# 보안 키 (반드시 변경)
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 준비

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 준비

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

---

3. 개발 환경

3.1 로컬 실행

# 의존성 설치
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 전체 스택

docker-compose up -d

서비스 확인:

• API: http://localhost:8000/docs
• Flower: http://localhost:5555

---

4. 프로덕션 배포

4.1 Docker Compose

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 환경변수 (프로덕션 추가)

APP_ENV=production
DEBUG=false
LOG_LEVEL=WARNING

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

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

4.3 리버스 프록시 (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. 헬스체크

# 기본 헬스체크
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

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

---

8. 백업

MariaDB

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

MongoDB

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