# 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: 네트워킹 및 보안 (우선순위: 높음)

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

5. ✅ **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

6. ✅ **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` 배포 파일 작성됨

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

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

---

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

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

9. ✅ **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 표시

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

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

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

---

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

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

13. ✅ **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`
    - 완료 기준: 수동 빌드/푸시 스크립트 작동 확인, 이미지 태그 정책 확정

14. ✅ **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: 절차 및 문서화 (우선순위: 중간)

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

15. ✅ **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 완료 권장)

5. Provide Nginx reverse-proxy and frontend static config
6. Externalize and secure environment variables
7. Define TLS certificate handling strategy
8. Security review: non-root users, image scan, secret rotation

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

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

9. Add healthcheck and readiness endpoint in backend
10. Add logging and log rotation guidance
11. Document backup and restore procedures
12. Add smoke tests and post-deploy checks

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

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

13. Prepare CI/CD build & push scripts
14. Create deploy directory with compose.prod and nginx configs
15. 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회 스테이징 환경에서 전체 배포 절차 테스트를 수행한다.