"Docker 실전 — 개발자를 위한 컨테이너 가이드"

## 실전 스택 구성

```
클라이언트
    ↓ HTTPS
  Nginx (리버스 프록시, 정적 파일)
    ↓
  FastAPI (API 서버, 여러 인스턴스 가능)
    ↓         ↓
PostgreSQL   Redis (캐싱, 세션, 큐)
```

---

## 완성형 docker-compose.yml

```yaml
version: '3.9'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
      - static_files:/app/static:ro
    depends_on:
      - api

api:
    build:
      context: .
      target: runner       # 멀티 스테이지 타겟
    env_file: .env
    volumes:
      - static_files:/app/static
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped
    deploy:
      replicas: 2          # 스케일아웃

db:
    image: postgres:15-alpine
    env_file: .env
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

cache:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redisdata:/data
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:
  static_files:
```

---

## .env 파일 구조

```bash
# .env (로컬 개발용 — .gitignore에 추가!)
POSTGRES_USER=devuser
POSTGRES_PASSWORD=devpass
POSTGRES_DB=myapp
DATABASE_URL=postgresql://devuser:devpass@db:5432/myapp

REDIS_PASSWORD=devredis
REDIS_URL=redis://:devredis@cache:6379/0

SECRET_KEY=local-dev-key-change-in-prod
```

프로덕션은 `.env.prod` 별도 관리:
```bash
docker compose --env-file .env.prod up -d
```

---

## 개발 vs 프로덕션 분리

```yaml
# docker-compose.override.yml (자동 merge, 개발 전용)
services:
  api:
    build:
      target: builder      # 개발 스테이지 (소스 마운트)
    volumes:
      - .:/app             # 핫 리로드
    command: uvicorn main:app --reload --host 0.0.0.0 --port 8000
    ports:
      - "8000:8000"        # 직접 접근 (Nginx 우회)

db:
    ports:
      - "5432:5432"        # DBeaver 등 직접 접속용
```

```bash
# 개발 (override 자동 적용)
docker compose up -d

# 프로덕션 (override 제외)
docker compose -f docker-compose.yml up -d
```

---

## 유용한 운영 명령

```bash
# 특정 서비스만 재빌드
docker compose up -d --build api

# 스케일 조정
docker compose up -d --scale api=3

# DB 마이그레이션 (일회성 실행)
docker compose run --rm api alembic upgrade head

# 백업
docker compose exec db pg_dump -U devuser myapp > backup.sql

# 로그 (최근 100줄 + 실시간)
docker compose logs --tail=100 -f api
```

---

## 헬스체크 패턴

```yaml
# FastAPI 헬스체크
api:
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s  # 시작 시간 여유
```

```python
# main.py
@app.get("/health")
async def health():
    return {"status": "ok"}
```

---

## 정리: 로컬 개발 워크플로우

```bash
# 1. 처음 시작
docker compose up -d --build

# 2. 코드 수정 → 자동 리로드 (override 덕분)

# 3. 의존성 추가 시
docker compose up -d --build api

# 4. DB 초기화
docker compose down -v && docker compose up -d

# 5. 종료
docker compose down
```

"Compose 실전 스택"

// COMMENTS

ON THIS PAGE