# Gifticon Platform Docker Runbook (Dev/Prod 통합)

이 문서는 Gifticon Platform의 Docker 기반 실행 환경을 운영/배포 관점에서 정리한 통합 런북이다.

포함 범위:
- 컨테이너 역할/연동 구조
- 프록시(HTTPS terminate) 구조
- 정상 동작 테스트(필수 체크리스트)
- 스케줄/큐/메일/캐시 관련 대표 장애 사례 및 해결
- 배포 절차(운영 권장 루틴)
- 운영 하드닝(보안/안정성) 권장사항
- 데이터 영속성/백업

---

## 0. 아키텍처 개요

### 0.1 컨테이너 구성(대표)
- `gifticon-web` : Nginx (Web 도메인, 정적/라우팅 + PHP-FPM upstream)
- `gifticon-admin` : Nginx (Admin 도메인, 인증/허용 IP 적용 가능)
- `gifticon-app` : PHP-FPM + Laravel (비즈니스 로직)
- `gifticon-worker` : Laravel queue worker (Redis 큐 처리)
- `gifticon-scheduler` : Laravel scheduler (schedule:work 상시 실행)
- `gifticon-db` : MariaDB (개발/임시용. 리얼에서는 RDS 사용 가능)
- `gifticon-redis` : Redis (cache/session/queue)
- (mailpit: 개발용 SMTP 테스트 — 현재 제거 완료)

### 0.2 프록시(NAS/nginx-proxy/CloudFront) 연결
외부에서 HTTPS로 들어오면 프록시가 HTTPS를 terminate 하고 내부 도커는 HTTP로 통신한다.

예시(NAS nginx-proxy):
- `https://four.syye.net`  → `http://<docker-host>:8091` (gifticon-web)
- `https://shot.syye.net` → `http://<docker-host>:8092` (gifticon-admin)

운영에서도:
- CloudFront(HTTPS) → EC2(HTTP) → Docker(gifticon-web/admin) 동일 패턴으로 적용 가능.

프록시에서 전달 헤더:
- `Host`
- `X-Forwarded-Proto=https`
- `X-Forwarded-For`
- `X-Forwarded-Host`

---

## 1. docker-compose 주요 역할/의미

### 1.1 gifticon-web (nginx)
- 역할: Web 도메인용 Nginx
- 포트: 8091:80 (호스트 노출)
- 볼륨:
    - `./src:/var/www/html:ro` (소스 read-only)
    - `./nginx/web/default.conf:/etc/nginx/conf.d/default.conf:ro`

### 1.2 gifticon-admin (nginx)
- 역할: Admin 도메인용 Nginx
- 포트: 8092:80
- 볼륨:
    - `./src:/var/www/html:ro`
    - `./nginx/admin/default.conf:/etc/nginx/conf.d/default.conf:ro`
    - `./nginx/auth:/etc/nginx/auth:ro` (허용 IP, basic auth 등 정책 적용)

### 1.3 gifticon-app (php-fpm + laravel)
- 역할: Laravel 실행
- depends_on: db, redis
- UID/GID 매핑으로 호스트 파일 권한 문제 방지
- 주의: `artisan tinker` 실행 시 PsySH가 HOME 디렉토리에 쓰기를 시도할 수 있음  
  → `docker exec -it -e HOME=/tmp gifticon-app php artisan tinker` 권장

### 1.4 gifticon-worker (queue)
- 역할: Redis 큐 처리
- command: `php artisan queue:work ...`
- 운영 포인트:
    - **Closure Job(익명 함수 dispatch) 금지**: 직렬화/경로 오류 발생 가능
    - 반드시 Job 클래스로 구현

### 1.5 gifticon-scheduler (schedule)
- 역할: `php artisan schedule:work` 상시 실행
- Laravel 12 기준 스케줄 정의는 `routes/console.php`에서 가능
- `withoutOverlapping()` 사용 시 `->name()`을 먼저 지정해야 함  
  (name 없는 상태에서 withoutOverlapping 호출하면 LogicException)

### 1.6 gifticon-db (mariadb)
- 역할: 개발/임시 DB
- 영속성: `db_data` 볼륨 사용 (재시작해도 유지)
- **주의:** `docker compose down -v`는 볼륨 삭제(데이터 삭제)

### 1.7 gifticon-redis
- 역할: cache/session/queue
- 영속성: `redis_data` 볼륨(appendonly) 사용

---

## 2. 운영(리얼) 서버 적용 원칙

### 2.1 APP_ENV / APP_DEBUG
운영 권장:
- `APP_ENV=production`
- `APP_DEBUG=false` (디버그/스택노출 위험)

### 2.2 캐시 전략(운영 배포 후 권장)
운영 배포 직후:
- `php artisan optimize:clear`
- `php artisan config:cache`
- `php artisan route:cache`
- `php artisan view:cache`

> 템플릿 변경 후 메일/뷰가 반영 안 되는 문제는 대부분 view cache 또는 worker 재시작 누락.

### 2.3 secrets 관리
- .env 민감정보(키/비번/SMTP/토큰)는 저장소 커밋 금지
- 운영 서버에서는 `.env` 권한 600 + 배포 파이프라인에서 주입 권장

---

## 3. “정상 동작” 점검 체크리스트 (필수)

### 3.1 컨테이너 상태 확인
```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"