248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
# 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회 스테이징 환경에서 전체 배포 절차 테스트를 수행한다.
|