sungro815/giftcon_dev

Fork 0

sungro815 0010cc69be 관리자 로그인

2026-02-04 16:55:00 +09:00

4.2 KiB

Raw Blame History

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 컨테이너 상태 확인

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

4.2 KiB Raw Blame History