Taehoon/ITAM
2
0
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/docker-deploy
ITAM/production_deploy_roadmap.md

11 KiB
Raw Permalink Blame History

ITAM 운영 배포 작업 로드맵

1. 문서 목적

이 문서는 ITAM 저장소를 Windows/WSL 시범 구동 상태에서 Linux 운영 서버 배포 상태로 전환하기 위한 구체적인 작업 목록과 우선순위를 정리한 로드맵이다.

현재 상태: 개발/시범용 Docker 구조 (Vite dev server + bind mount + external DB)
목표 상태: 운영 배포 구조 (정적 빌드 + 영속 스토리지 분리 + reverse proxy + external DB)

2. 작업 페이즈 분류

2.1 Phase 1: 핵심 배포 파일 (우선순위: 높음)

운영 환경에서 실제 배포를 가능하게 하는 기초 작업이다.

  1. ✅ Add production compose file (docker-compose.prod.yaml)

    • 목표: 운영 서버 기준 최종 compose 파일 작성
    • 범위: backend, frontend, nginx 서비스 정의
    • 입력: 외부 .env, 호스트 경로 마운트 정의
    • 출력: /deploy/docker-compose.prod.yaml
    • 완료 기준: docker compose -f docker-compose.prod.yaml config 성공

  2. ✅ Create production frontend Dockerfile (multi-stage build)

    • 목표: 정적 자산 기반 프런트엔드 이미지 생성
    • 범위: Stage 1 = 빌드 (Node.js + npm build), Stage 2 = 정적 서빙 (Nginx)
    • 입력: 현재 Dockerfile.frontend 참고, npm run build 검증
    • 출력: Dockerfile.frontend.prod 또는 분기 처리
    • 완료 기준: 로컬에서 npm run build 성공, 이미지 빌드 성공, 정적 파일 8080 서빙 확인

  3. ✅ Harden backend Dockerfile for production

    • 목표: production 환경 최적화된 백엔드 이미지
    • 범위: NODE_ENV=production, production 의존성만, 비루트 사용자, health check 추가
    • 입력: 현재 Dockerfile.backend, server.js 검토
    • 출력: 수정된 Dockerfile.backend 또는 .prod 버전
    • 완료 기준: 이미지 빌드 성공, 시작 후 health endpoint 응답 200

  4. ✅ Define host paths and named volumes for persistence

    • 목표: Linux 서버의 운영 디렉터리 구조 정의
    • 범위: /srv/itam/{app,env,config,uploads,logs,deploy} 마운트 정책 확정
    • 입력: doc_readme3.md 섹션 7 참고
    • 출력: docker-compose.prod.yaml에 적용, 볼륨 마운트 확인
    • 완료 기준: compose 파일에 경로 마운트 명시, 영속성 테스트 (컨테이너 재시작 후 데이터 유지)

2.2 Phase 2: 네트워킹 및 보안 (우선순위: 높음)

외부 접근 경로와 보안을 담당하는 작업이다.

  1. ✅ Provide Nginx reverse-proxy and frontend static config

    • 목표: Nginx 설정파일 작성 (frontend 정적 서빙 + API 프록시)
    • 범위: / → frontend, /api/ → backend:3000, 기본 보안 헤더, gzip
    • 입력: doc_readme3.md 섹션 12 참고 (예시 개념)
    • 출력: /deploy/nginx/default.conf
    • 완료 기준: docker compose -f docker-compose.prod.yaml up -d 후 http://localhost/api/assets/master 응답 200

  2. ✅ Externalize and secure environment variables (.env.example + secrets guidance)

    • 목표: 민감정보 보호 기준 문서화
    • 범위: .env.example 생성, Git 제외 확인, 운영 환경 분리 지침
    • 입력: 현재 .env 파일, .gitignore 점검
    • 출력: .env.example, env 관리 가이드 추가 (doc_readme3.md 또는 SECURITY.md)
    • 완료 기준: .env가 .gitignore에 등록, .env.example 배포 파일 작성됨

  3. ✅ Define TLS certificate handling strategy (Let's Encrypt / mount certs)

    • 목표: HTTPS 인증서 관리 정책 확정
    • 범위: 자동 갱신 (certbot + Let's Encrypt) 또는 마운트 기반 수동 관리 선택
    • 입력: 사내 정책 확인, 운영 도메인 확인
    • 출력: deploy/nginx/tls-strategy.md 또는 compose 파일 주석으로 정리
    • 완료 기준: 선택 방식 문서화, nginx 설정 적용 준비

  4. ✅ Security review: non-root users, image scan, secret rotation

    • 목표: 보안 체크리스트 작성 및 초기 적용
    • 범위: Dockerfile non-root 사용자 추가, 이미지 취약점 스캔 지침, 비밀 로테이션 정책
    • 입력: doc_readme3.md 섹션 13.3 (보안) 참고
    • 출력: 수정된 Dockerfile, SECURITY.md 또는 운영 가이드 추가
    • 완료 기준: 백엔드/프런트엔드 모두 비루트 사용자로 실행 확인

2.3 Phase 3: 모니터링 및 운영 준비 (우선순위: 중간)

배포 후 운영을 원활하게 하기 위한 작업이다.

  1. ✅ Add healthcheck and readiness endpoint in backend

    • 목표: backend 헬스 체크 엔드포인트 추가
    • 범위: GET /health 또는 /ready 엔드포인트 추가 (DB 연결 확인)
    • 입력: server.js 현재 코드 검토
    • 출력: backend 에서 health 응답, docker-compose.prod.yaml에 healthcheck 설정
    • 완료 기준: curl http://localhost:3000/health 응답 200, 컨테이너 헬스 상태 healthy 표시

  2. ✅ Add logging and log rotation guidance

    • 목표: 컨테이너 로그 관리 정책 문서화
    • 범위: Docker logging driver 설정, log rotation 정책, 저장소 경로 정의
    • 입력: /srv/itam/logs 마운트 계획
    • 출력: docker-compose.prod.yaml에 로깅 설정, docs에 로그 확인 가이드
    • 완료 기준: 로그 파일이 /srv/itam/logs에 저장됨, rotation 정책 명시

  3. ✅ Document backup and restore procedures for DB and uploads

    • 목표: 운영 데이터 백업/복구 절차 문서화
    • 범위: 외부 MySQL 백업 정책, /srv/itam/uploads 백업, 복구 절차 스크립트 예시
    • 입력: doc_readme3.md 섹션 14 참고
    • 출력: BACKUP_RESTORE.md 또는 운영 가이드 추가 섹션
    • 완료 기준: 백업 스크립트 예시 작성, 복구 절차 테스트 완료

  4. ✅ Add smoke tests and post-deploy checks

    • 목표: 배포 후 빠른 검증 스크립트 작성
    • 범위: 컨테이너 상태 확인, API 응답 테스트, 파일 업로드 테스트, DB 연결 확인
    • 입력: doc_readme3.md 섹션 13 (점검 체크리스트) 참고
    • 출력: scripts/smoke-test.sh 또는 배포 후 확인 스크립트
    • 완료 기준: 스크립트 실행 후 모든 검사 통과

2.4 Phase 4: 자동화 및 CI/CD (우선순위: 중간)

장기 운영을 위한 자동화 작업이다.

  1. ✅ Prepare CI/CD build & push scripts (image registry)

    • 목표: 이미지 빌드 및 레지스트리 푸시 자동화
    • 범위: docker build, docker tag, docker push 스크립트 또는 GitHub Actions/GitLab CI 예시
    • 입력: 이미지 레지스트리 주소 확인 (e.g., registry.example.com, Docker Hub, etc.)
    • 출력: .github/workflows/build.yml 또는 scripts/build-push.sh
    • 완료 기준: 수동 빌드/푸시 스크립트 작동 확인, 이미지 태그 정책 확정

  2. ✅ Create deploy directory with compose.prod and nginx configs

    • 목표: 운영 배포 디렉터리 정리
    • 범위: /deploy/docker-compose.prod.yaml, /deploy/nginx/default.conf, 기타 설정 파일 조직화
    • 입력: Phase 1-3 결과물
    • 출력: 다음 구조로 정리됨: 
      deploy/
  docker-compose.prod.yaml
  nginx/
    default.conf
    tls-strategy.md
  scripts/
    smoke-test.sh
    backup.sh
    • 완료 기준: 디렉터리 구조 확정, 모든 파일 위치 일관성 있음

2.5 Phase 5: 절차 및 문서화 (우선순위: 중간)

운영 절차와 문서를 정리하는 작업이다.

  1. ✅ Write rollout and rollback procedures (steps, checklist)
    • 목표: 배포 및 복구 절차 문서화
    • 범위: 배포 전 체크리스트, 배포 단계별 절차, 장애 시 롤백 절차
    • 입력: doc_readme3.md 섹션 16 참고
    • 출력: DEPLOYMENT_PROCEDURES.md 또는 운영 가이드 통합
    • 완료 기준: 절차 문서 완성, 체크리스트 확인 가능

3. 작업 우선순위 및 권장 순서

3.1 필수 우선 작업 (Phase 1 완료 필수)

  1. Add production compose file
  2. Create production frontend Dockerfile (multi-stage build)
  3. Harden backend Dockerfile for production
  4. Define host paths and named volumes for persistence

목표: 기본 배포 구조 완성, Linux 서버에서 최소 기동 가능 상태

3.2 보안 필수 작업 (Phase 2 완료 권장)

  1. Provide Nginx reverse-proxy and frontend static config
  2. Externalize and secure environment variables
  3. Define TLS certificate handling strategy
  4. Security review: non-root users, image scan, secret rotation

목표: 운영 환경 최소 보안 기준 충족

3.3 운영 안정화 작업 (Phase 3 진행)

  1. Add healthcheck and readiness endpoint in backend
  2. Add logging and log rotation guidance
  3. Document backup and restore procedures
  4. Add smoke tests and post-deploy checks

목표: 배포 후 문제 식별 및 백업/복구 가능 상태

3.4 장기 운영 자동화 (Phase 4-5는 선택)

  1. Prepare CI/CD build & push scripts
  2. Create deploy directory with compose.prod and nginx configs
  3. Write rollout and rollback procedures

목표: 반복 배포 자동화, 절차 표준화

4. 작업 환경 및 검증 기준

4.1 개발/테스트 환경

  • 로컬 Linux VM 또는 WSL에서 Phase 1-2 테스트
  • Docker Desktop or Docker Engine 필수
  • 외부 테스트 MySQL 또는 mock DB

4.2 스테이징 환경

  • 실제 Linux 서버에서 전체 배포 절차 테스트
  • 운영 환경과 동일 아키텍처

4.3 운영 배포

  • 위 모든 Phase 완료 후 진행
  • 백업 확인 후 배포
  • 배포 후 smoke test 자동 실행

5. 진행 추적

진행 상황은 아래 상태로 추적한다.

  • not-started: 아직 시작 안 함
  • in-progress: 현재 진행 중
  • completed: 완료됨

현재 상태는 모두 not-started이며, Phase 1 우선 순위 항목부터 순차적으로 진행한다.

6. 예상 일정

  • Phase 1 (핵심 배포 파일): 1-2일
  • Phase 2 (네트워킹 및 보안): 1-2일
  • Phase 3 (모니터링 및 운영 준비): 1일
  • Phase 4-5 (자동화 및 절차): 1-2일

전체 예상 소요 시간: 4-7일

7. 추가 고려사항

  1. 현재 doc_readme3.md는 가이드 문서이고, 이 로드맵은 구현 작업 목록이다.
  2. Phase 1-2 완료 후 실제 코드 커밋은 Dockerizing 브랜치에만 한다.
  3. 각 Phase 완료 후 관련 문서도 함께 업데이트한다.
  4. 운영 전환 전에 최소 1회 스테이징 환경에서 전체 배포 절차 테스트를 수행한다.
Reference in New Issue View Git Blame Copy Permalink