Docker 기반 GSMSV 운영 배포 환경 구성

[exijn]

✨ 작업 내용

GSMSV 학교 VM에서 PR #33 병합 이후 MUDDA를 최초 수동 배포할 수 있도록 Docker 기반 운영 파일과 배포 문서를 추가했습니다.

• Java 21 멀티 스테이지 Dockerfile
• 비 root 실행, Gradle Wrapper 캐시, JVM 메모리 옵션, graceful shutdown
• 운영 전용 docker-compose.prod.yml
• App·PostgreSQL/PostGIS·Redis 구성 및 healthcheck
• PostgreSQL·Redis 외부 포트 비공개, App 8080만 publish
• PostgreSQL·Redis 영구 볼륨, 재시작 정책, JSON 로그 회전
• application-prod.yaml, .env.production.example 및 Secret 제외 규칙
• GSMSV 수동 배포 안내 문서

---

🔍 리뷰 시 참고사항

운영 환경

• GSMSV Project Owner VM: Ubuntu 22.04.5 LTS, x86_64, 2 vCPU, RAM 7.9GB, 디스크 40GB
• GSMSV HTTPS Reverse Proxy → app:8080 → 내부 postgres:5432 / redis:6379
• 예상 주소: https://mudda-api.https.gsmsv.site
• Nginx·Certbot은 사용하지 않음
• 운영 시간대: Asia/Seoul

주요 설계

• 기존 로컬 개발용 docker-compose.yml은 유지하고 운영용 Compose를 분리했습니다.
• PostgreSQL은 postgis/postgis:16-3.5-alpine을 사용하며, 초기화 SQL은 PostGIS 확장만 활성화하고 스키마는 Flyway가 관리합니다.
• Redis는 refresh token과 token blacklist TTL 상태 보존을 위해 AOF와 영구 볼륨을 사용합니다.
• Redis는 외부 포트가 없고 internal 네트워크에만 연결되므로 이번 범위에서는 비밀번호를 추가하지 않았습니다. 인증 추가는 Spring 설정·Redis command·healthcheck·Secret 전달을 함께 변경하는 후속 작업입니다.
• App readiness는 readinessState, db, redis를 포함하며 /actuator/health/**만 인증 없이 허용합니다. 다른 Actuator Endpoint는 외부에 노출하지 않습니다.
• MUDDA_MASTER_KEY 생성·별도 백업·분실 주의사항을 운영 문서에 명시했습니다.

문서

• docs/GSMSV_MANUAL_DEPLOYMENT.md
• Docker 설치 전제, 운영 .env 준비, Firebase credential 배치, 이미지 빌드와 Compose 실행
• Flyway·컨테이너·Actuator·로그·볼륨·포트·재시작·graceful shutdown 확인 방법
• GSMSV HTTPS 설정값과 Secret 커밋 금지
• PostgreSQL 백업, CD, Discord 알림은 후속 작업이라는 범위

검증 결과

• ./gradlew test --tests 'team.cklob.mudda.global.config.SecurityConfigTest' -Dorg.gradle.java.home=... 통과
• ./gradlew build -x test -Dorg.gradle.java.home=... 통과
• git diff --check 통과
• docker compose --env-file .env.production -f docker-compose.prod.yml config --quiet 통과 (실제 Secret이 아닌 임시 검증 값 사용)
• Secret·Firebase credential·빌드 산출물 미포함 확인
• Dockerfile·Compose·Profile·SecurityConfig·문서 자체 리뷰 2회 완료
• ./gradlew test 전체 통과
• ./gradlew check 전체 통과
• Docker 이미지 빌드 및 Compose 통합 기동
• 실제 App/PostgreSQL/Redis Health·볼륨·재시작·외부 포트 검증

전체 Gradle test/check는 298개 중 11개가 Testcontainers 초기화 단계에서 실패했습니다. Docker Desktop Linux Engine이 실행되지 않아 DockerClientProviderStrategy가 Docker 데몬을 찾지 못한 환경 제한입니다. Docker 이미지 빌드와 Compose 통합 기동도 같은 이유로 실행하지 못했습니다. 코드 컴파일과 non-integration 테스트는 통과했습니다.

자체 코드 리뷰

1차 리뷰에서 Docker 빌드 시 plain JAR까지 매칭될 수 있는 문제를 발견해 실행 JAR 하나만 복사하도록 수정했고, 운영 Compose에 PostGIS 초기화 SQL을 연결했습니다. readiness 경로 인증 허용도 테스트로 고정했습니다.

2차 리뷰에서 AGENTS.md·CLAUDE.md 준수, 운영 파일 범위, 로컬 Compose 보존, 기존 Flyway 보존, CD·Discord 제외, Secret·임시 산출물 미포함, 문서 명령 일치 여부를 재확인했습니다.

제외 범위 및 후속 작업

• GSMSV VM 최초 실제 배포
• PostgreSQL 백업 구성
• develop 기반 GitHub Actions CD 및 GHCR 배포
• Discord 웹훅 임베드 알림
• Nginx·Certbot, 자동 롤백, Blue-Green, Kubernetes, 모니터링 스택
• Redis 인증 추가

---

✅ 체크리스트

• 문서(README, .env.example 등) 변경이 필요한 경우 작성 또는 수정했나요?
• 작업한 코드가 정상적으로 동작하는 것을 직접 확인했나요? (컴파일 및 가능한 단위·설정 검증 완료, Docker 데몬 부재로 Testcontainers·Docker 통합 검증은 미실행)
• 필요한 경우 테스트 코드를 작성하거나 수정했나요?
• Merge 대상 브랜치를 올바르게 설정했나요?
• PR에 관련 없는 작업이 포함되지 않았나요?
• 적절한 라벨과 리뷰어를 설정했나요?

---

📎 관련 이슈(선택)

• Close Docker 기반 운영 배포 환경 구성 #34