기준 문서: KTB4-3rd-CLOUD Wiki

이 문서는 모여타 V1의 애플리케이션 이미지, Compose 실행 환경, CI/CD를 세 개의 마일스톤으로 나누어 정의한다. 각 마일스톤은 독립적인 완료 조건과 산출물을 가지며, 앞 단계의 계약이 확인된 뒤 다음 단계로 진행한다.

운영 기준은 Dev EC2와 Prod EC2를 분리한 단일 호스트 Docker Compose다. 고가용성이나 무중단 배포보다 환경 일관성, 장애 영향 범위 축소, 빠른 복구와 운영 단순성을 우선한다.

M1은 애플리케이션 저장소에 Dockerfile을 제공하는 단계다. 애플리케이션 소스를 CLOUD 저장소로 복사하거나 CLOUD가 Dockerfile을 대신 소유하지 않는다.

사용자
  │ HTTPS / WebSocket
  ▼
Nginx
  ├── /        → frontend:3000
  ├── /api/*   → backend:8080
  ├── /ws/*    → backend:8080 (HTTP/1.1 Upgrade)
  └── /ai/*    → ai:8000 (선택 기능)

• moyeota-app-APP_ENV: Nginx, frontend, backend, 선택적인 ai 연결
• moyeota-db-APP_ENV: backend와 mysql만 연결
• MySQL 데이터는 moyeota-mysql-APP_ENV named volume에 저장
• 앱 컨테이너 교체와 DB 데이터 생명주기를 분리
• 인증서와 Secret은 이미지에 넣지 않고 서버의 제한된 경로에서 read-only로 주입

위 값은 운영 보장값이 아닌 부하 테스트 시작점이다. OOM, CPU throttling, GC pause, WebSocket 연결 수, DB connection 대기와 p95/p99 응답 시간을 측정해 조정한다.

이미지는 이동 태그가 아니라 Registry가 반환한 Digest를 배포 식별자로 사용한다.

dev-<sha7>
rc-v<version>-<sha7>
prod-v<version>-<sha7>

Dev에서 검증한 이미지 Digest와 Prod에서 실행하는 이미지 Digest는 동일해야 한다. latest, dev, prod 같은 이동 태그는 조회 편의를 위해서만 사용한다.

각 애플리케이션이 동일한 Linux 런타임에서 재현 가능하게 빌드되고, 실행에 필요한 파일만 포함한 production image로 동작하도록 만든다.

빌드 도구와 테스트 의존성은 builder stage에만 두고, runtime stage는 일반 사용자로 실행한다. Secret, 운영 .env, 인증서 개인 키, 로컬 빌드 결과는 이미지에 포함하지 않는다.

• package-lock.json을 기준으로 npm ci 실행
• npm run test --if-present 후 npm run build
• next.config에 output: standalone 설정
• runtime image에는 .next/standalone, .next/static, public만 복사
• node 사용자로 포트 3000 실행

• 저장소의 Gradle Wrapper로 dependencies, test, bootJar 실행
• JDK image와 JRE image 분리
• plain JAR가 아닌 실행 JAR만 runtime image에 복사
• Actuator readiness endpoint를 healthcheck으로 사용
• 전용 non-root 사용자로 포트 8080 실행

• requirements.txt 또는 프로젝트 lock file을 기준으로 의존성 설치
• 개발용 reload를 사용하지 않음
• app.main:app import 경로와 /health endpoint를 애플리케이션 계약으로 고정
• 모델 파일은 이미지 포함, named volume, 외부 저장소 중 하나를 별도 결정
• V1 Compose에서는 기본적으로 배포하지 않고 profile로 선택

1. 애플리케이션별 lock file, build command, 실행 포트, health endpoint 확정
2. Dockerfile과 .dockerignore 작성
3. 로컬 또는 CI runner에서 unit test와 production image build 실행
4. 컨테이너를 non-root로 실행하고 healthcheck 확인
5. 이미지 metadata에 source repository와 commit SHA 기록
6. Buildx로 EC2 대상 플랫폼 이미지 생성
7. Dev에서 사용할 ECR Digest를 release manifest에 기록

• FE, BE, AI 각 저장소에 production Dockerfile이 있다.
• 각 저장소에 .dockerignore가 있고 .env, .git, build cache가 제외된다.
• 깨끗한 CI runner에서 테스트와 이미지 빌드가 재현된다.
• runtime stage가 root가 아닌 사용자로 실행된다.
• 이미지에 Secret과 인증서 개인 키가 없다.
• FE SSR, BE HTTP/WebSocket, AI 핵심 endpoint가 독립적으로 동작한다.
• 세 이미지의 healthcheck가 제한 시간 안에 통과한다.
• 배포 대상 EC2 플랫폼에서 실행 가능하다.

M1은 애플리케이션 소스와 lock file이 존재해야 실제 build 검증을 완료할 수 있다. 저장소가 비어 있는 동안에는 Dockerfile 문법과 정적 정책 검사까지만 수행한다.

동일한 Compose 정의를 Dev와 Prod에서 사용하고, 환경별 값과 Secret만 서버 파일로 분리한다. 외부 요청은 Nginx만 수신하며, 내부 서비스와 MySQL은 호스트 포트를 공개하지 않는다.

compose.yaml
compose.ai.yaml
nginx/
  Dockerfile
  nginx.conf
  conf.d/
deploy/
  runtime.env.example
  release.env.example
  README.md
scripts/
  deploy.sh
  rollback.sh
  smoke-test.sh
  backup-mysql.sh

compose.ai.yaml은 AI를 실제로 사용할 때만 overlay로 적용한다. 기본 V1 실행은 COMPOSE_AI_ENABLED=false로 두고, AI가 필요한 릴리스에서만 profile을 활성화한다.

• 모든 서비스에 restart: unless-stopped 적용
• MySQL health 통과 후 migration과 backend 기동
• backend와 frontend health 통과 후 Nginx 기동
• Compose service_healthy와 애플리케이션 자체 timeout을 함께 사용
• 로그는 컨테이너 stdout/stderr로 내보내고 rotation 적용
• no-new-privileges, read-only Secret mount, 최소 Linux capability를 기본값으로 사용

권장 기동 순서는 다음과 같다.

mysql healthy
  → migration
  → backend ready
  → frontend ready
  → nginx
  → HTTP/WebSocket smoke test

/opt/moyeota/
├── compose.yaml
├── compose.ai.yaml
├── nginx/
├── runtime.env       # 환경별 Secret, 권한 600
├── release.env       # 이미지 Digest, 권한 600
└── scripts/

runtime.env에는 DB 비밀번호, JWT Secret, 외부 API 키를 저장하고 Git에 commit하지 않는다. release.env에는 서비스별 immutable ECR reference만 저장한다.

• docker compose config가 Dev와 Prod에서 모두 성공한다.
• 호스트에는 Nginx 80/443만 공개된다.
• MySQL volume이 컨테이너 교체 후에도 유지된다.
• MySQL, backend, frontend healthcheck가 통과한다.
• /, /api, /ws 라우팅과 WebSocket Upgrade가 동작한다.
• AI profile을 비활성화한 기본 V1 실행이 가능하다.
• CPU·메모리 제한과 log rotation이 실제 컨테이너에 적용된다.
• 인증서와 Secret이 image layer 또는 Git history에 남지 않는다.
• docker compose down 후 down -v 없이 데이터가 보존된다.

애플리케이션 저장소는 검증과 이미지 publish를 담당하고, CLOUD 저장소는 Compose release와 EC2 배포를 담당한다. Dev는 자동 배포하고 Prod는 승인 후 동일한 Digest를 승격한다.

1. lock file 기반 의존성 설치
2. lint와 정적 분석
3. unit test 및 필요한 integration test
4. production Docker image build
5. Secret 포함 여부와 non-root 정책 검사
6. 결과를 required check로 보고

PR에서는 ECR push와 EC2 배포를 하지 않는다.

1. PR 검증 재실행
2. 대상 플랫폼 이미지 build
3. ECR에 dev- tag push
4. Registry Digest와 source commit 기록
5. CLOUD 배포 workflow에 dev-image-published event 전달
6. Dev EC2에서 release manifest 갱신 후 Compose deploy
7. readiness와 smoke test 통과 여부 기록

1. Dev에서 검증한 Digest를 RC manifest로 고정
2. rc-v- tag와 Digest 기록
3. QA 완료 후 GitHub Environment 승인 요청
4. 승인 시 Prod EC2에 동일 Digest 배포
5. Prod readiness와 smoke test 결과 보관

단일 EC2와 Docker Compose 운영에서는 Recreate 전략을 사용한다. 컨테이너를 교체하는 짧은 중단과 기존 WebSocket 연결 종료를 운영상 허용하고, 대신 readiness와 rollback을 배포 게이트로 둔다.

release manifest 검증
  → ECR login
  → 이미지 pull
  → (Prod) MySQL backup
  → migration hook
  → docker compose up -d --wait
  → readiness / smoke
  ├── 성공: release 기록
  └── 실패: 이전 manifest로 rollback

배포는 EC2에 SSH로 임의 명령을 실행하는 대신 SSM Run Command를 우선 사용한다. Dev에서만 임시 SSH 접근을 허용할 수 있으나, 운영 배포 경로는 SSM으로 통일한다.

RELEASE_ID=prod-v1.0.0-abcdef1
FRONTEND_IMAGE=000000000000.dkr.ecr.ap-northeast-2.amazonaws.com/moyeota/fe@sha256:<digest>
BACKEND_IMAGE=000000000000.dkr.ecr.ap-northeast-2.amazonaws.com/moyeota/be@sha256:<digest>
NGINX_IMAGE=000000000000.dkr.ecr.ap-northeast-2.amazonaws.com/moyeota/nginx@sha256:<digest>
AI_IMAGE=000000000000.dkr.ecr.ap-northeast-2.amazonaws.com/moyeota/ai@sha256:<digest>

배포 스크립트는 mutable tag를 거부하고, 허용된 ECR repository와 sha256 Digest 형식만 통과시킨다. Release manifest가 가리키는 서비스 버전을 임의로 섞지 않는다.

• migration은 애플리케이션 release와 분리된 명시적인 hook으로 실행한다.
• backward-compatible schema를 먼저 배포하고, 애플리케이션 교체 후 구 스키마를 제거한다.
• 애플리케이션 rollback이 DB schema rollback을 의미하지 않는다.
• Prod 배포 전 transactional dump를 S3에 업로드하고 보존 기간을 적용한다.
• migration 실패 시 새 애플리케이션을 기동하지 않고 이전 release를 유지한다.

애플리케이션과 Nginx 로그는 CloudWatch Logs로 전달한다. 배포마다 release ID, source commit, image Digest, health 결과, rollback 여부를 남긴다.

• PR에서 테스트와 production image build가 실행된다.
• dev merge 시 ECR immutable image와 Digest가 생성된다.
• Dev 배포가 repository_dispatch와 SSM으로 자동 실행된다.
• Prod는 GitHub Environment 승인 없이는 배포되지 않는다.
• Dev 검증 Digest와 Prod 배포 Digest가 동일하다.
• 배포 전 release manifest와 runtime env 검증이 실행된다.
• readiness와 HTTP/WebSocket smoke test가 배포 게이트로 동작한다.
• Prod 배포 전 MySQL backup이 S3에 생성된다.
• 실패 시 이전 application image로 rollback할 수 있다.
• migration 실패 시 DB와 애플리케이션을 무분별하게 함께 rollback하지 않는다.
• 배포 결과와 로그가 추적 가능하다.

M1 Dockerfile / 이미지 계약
  ↓
M2 Compose / health / 네트워크 / 데이터 영속성
  ↓
M3 ECR publish / SSM deploy / 승인 / rollback

현재 문서는 설계와 완료 조건을 정의한 로컬 문서다. 애플리케이션 저장소의 실제 소스와 lock file이 준비되지 않은 상태에서는 M1의 Dockerfile 문법·정책 검사만 가능하며, 실제 image build와 health 검증은 소스 반영 후 수행한다.

다음 작업은 아래 순서로 진행한다.

1. FE/BE/AI 저장소에 애플리케이션 소스와 lock file 반영
2. M1 Dockerfile을 저장소별로 작성하고 검증
3. M2 Compose 환경 변수와 ECR Digest를 Dev 서버에 주입
4. Dev 배포와 smoke test 수행
5. QA 승인 후 M3 Prod pipeline 활성화

브랜치에 직접 파일을 추가하거나 commit/push하는 작업은 담당자의 사전 승인을 받은 뒤 수행한다. 승인 전에는 문서 초안과 로컬 검증만 진행한다.