sungro815/giftcon_dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
giftcon_dev/docs/ops/docker-runbook.md

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://myworld.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}}"