121 lines
4.2 KiB
Markdown
121 lines
4.2 KiB
Markdown
# 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}}"
|