# ITAM 구축 방식 변경 비교 보고서

## 1. 문서 목적

이 문서는 ITAM 시스템의 Docker 기반 구축 방식이 초기 개발/테스트 중심 구조에서 현재 운영 배포 중심 구조로 어떻게 변경되었는지 설명하기 위한 보고용 문서다.

이번 비교의 기준은 아래 두 단계다.

1. 초기 구축 방식: Windows + WSL 환경에서 개발 및 테스트 재현을 목적으로 한 Docker 구조
2. 현재 구축 방식: 정식 운영 배포를 고려하여 production 기준으로 정리한 Docker 구조

즉, 이 문서는 “예전 계획안과 지금 계획안의 차이”가 아니라, “처음 구축했던 개발/테스트용 구조와 현재 운영 배포용 구조의 차이”를 설명하는 문서다.

---

## 2. 한눈에 보는 핵심 변화

초기 구축은 아래 목적에 맞춰져 있었다.

1. Windows PC에서 WSL2를 이용해 빠르게 실행할 수 있어야 한다.
2. 현재 개발 구조를 그대로 Docker 안에서 재현해야 한다.
3. 프런트와 백엔드가 개발용 방식으로 동작하면 된다.

반면 현재 구축은 아래 목적에 맞춰 변경되었다.

1. 실제 운영 배포에 사용할 수 있어야 한다.
2. 프런트는 개발 서버가 아니라 정적 빌드 산출물로 서비스되어야 한다.
3. reverse proxy, health check, 운영용 Dockerfile, 운영용 compose 기준이 정리되어야 한다.
4. 운영 과정에서 경로, 정적 자산, 로그, 환경변수 사용 방식이 명확해야 한다.

즉, 초기에는 “개발 재현”이 목적이었고, 현재는 “운영 배포 가능 상태로 정리”하는 것이 목적이다.

---

## 3. 구조 비교도

### 3.1 초기 구축 구조

```mermaid
flowchart LR
  U["User Browser"] --> FE["Frontend Container Vite Dev 8080"]
  FE -->|api proxy| BE["Backend Container Express 3000"]
  BE --> DB["External MySQL 3306"]
  BE --> UP["./uploads"]
  BE --> CFG["./map_config.json"]
  ENV["./.env"] --> BE
  linkStyle default stroke:#d32f2f,stroke-width:2px;
```

### 3.2 현재 구축 구조

```mermaid
flowchart LR
  U["User Browser"] --> RP["Nginx Reverse Proxy 80"]
  RP --> FE["Frontend Container Static Nginx 80"]
  RP -->|api| BE["Backend Container Node 3000"]
  RP -->|uploads| BE
  BE --> DB["External MySQL 3306"]
  BE --> UP["./uploads"]
  BE --> CFG["./map_config.json"]
  ENV["./.env"] --> BE
  LOGS["./logs/nginx"] --> RP
  linkStyle default stroke:#d32f2f,stroke-width:2px;
```

---

## 4. 비교 요약표

| 구분 | 초기 구축 방식 | 현재 구축 방식 |
|---|---|---|
| 구축 목적 | Windows/WSL 개발 테스트 재현 | 정식 운영 배포 기준 정리 |
| 프런트 실행 방식 | Vite dev server | 빌드된 정적 파일 + Nginx |
| 프런트 포트 | 8080 | 80 |
| 백엔드 | Express API 컨테이너 | Express API 컨테이너 |
| 프록시 구조 | frontend 내부 dev proxy | 외부 nginx reverse proxy |
| 운영용 compose | 없음 또는 개발형 중심 | `docker-compose.prod.yaml` 별도 구성 |
| 테스트용 compose | `docker-compose.yaml` 중심 | `docker-compose.test.yaml` 별도 구성 |
| 정적 자산 처리 | 개발 서버가 직접 참조 | 운영 이미지에 정적 자산 포함 필요 |
| health check | 사실상 없음 | `/health`, `/ready` 기반 포함 |
| 운영 관점 기능 | 낮음 | 높음 |

---

## 5. 초기 구축 방식 설명

초기 구축은 Windows + WSL 환경에서 “지금 돌아가는 개발 구조를 Docker로 그대로 재현”하는 것이 핵심이었다.

주요 특징은 아래와 같다.

1. 프런트는 `Dockerfile.frontend`를 통해 Vite 개발 서버를 컨테이너에서 실행했다.
2. 백엔드는 `Dockerfile.backend`를 통해 Express API 서버를 컨테이너로 실행했다.
3. 프런트는 `VITE_DEV_PROXY_TARGET`을 이용해 `/api` 요청을 `backend:3000`으로 전달했다.
4. 접속 포트는 `http://localhost:8080`이었다.
5. 목적은 운영 배포가 아니라 개발/시연/테스트 재현이었다.

즉, 이 단계에서 중요한 것은 “실제 앱이 개발 환경과 최대한 비슷하게 동작하는가”였다.

---

## 6. 현재 구축 방식 설명

현재 구축은 정식 운영 배포에 맞게 구조를 보강한 상태다.

주요 특징은 아래와 같다.

1. 프런트는 `Dockerfile.frontend.prod`에서 multi-stage build를 통해 정적 파일로 빌드된다.
2. 빌드 산출물은 frontend 컨테이너 내부 Nginx가 서빙한다.
3. 별도의 nginx reverse proxy가 외부 80 포트를 받아 frontend와 backend로 요청을 분기한다.
4. backend는 `Dockerfile.backend.prod`를 사용하며, 비루트 사용자와 health check를 포함한다.
5. 운영용 `docker-compose.prod.yaml`과 검증용 `docker-compose.test.yaml`이 분리되어 있다.
6. 정적 이미지 자산과 로고 파일도 운영 이미지에 포함되도록 보완되었다.

즉, 현재는 단순 개발 재현이 아니라 “운영에 투입 가능한 형태로 구조를 정리”한 상태다.

---

## 7. 주요 변경 포인트 상세

### 7.1 프런트 실행 방식 변경

초기 구축:

1. Vite 개발 서버를 그대로 띄웠다.
2. 코드 수정과 빠른 재확인에 유리했다.
3. 운영 배포용 웹 서버 구조는 아니었다.

현재 구축:

1. `npm run build` 결과물을 사용한다.
2. frontend 컨테이너 내부 Nginx가 정적 파일을 서빙한다.
3. 운영 환경에서 더 안정적인 구조다.

이 차이는 개발 중심 구조에서 운영 중심 구조로 넘어갔다는 것을 가장 잘 보여준다.

### 7.2 프록시 구조 변경

초기 구축:

1. 프런트 컨테이너 내부에서 dev proxy가 `/api`를 backend로 우회했다.
2. 구조가 단순했지만 운영형 reverse proxy는 아니었다.

현재 구축:

1. 외부 nginx가 진입점 역할을 한다.
2. `/`는 frontend, `/api`와 `/uploads`는 backend로 분기한다.
3. 운영형 라우팅 구조를 갖추게 되었다.

### 7.3 compose 구성 분리

초기 구축:

1. 사실상 개발용 compose 중심이었다.
2. 운영 목적과 검증 목적이 명확히 분리되지 않았다.

현재 구축:

1. `docker-compose.test.yaml`은 운영형 구조 검증용
2. `docker-compose.prod.yaml`은 운영 모드 기동용
3. 목적에 따라 compose 파일이 구분된다.

### 7.4 백엔드 운영성 강화

초기 구축:

1. 백엔드는 단순 실행 중심이었다.
2. 운영 상태 확인이나 readiness 기준이 부족했다.

현재 구축:

1. `/health`, `/ready` 엔드포인트 추가
2. `dumb-init` 적용
3. 비루트 계정 실행
4. health check 포함

즉, 장애 확인과 운영 점검이 가능한 상태로 바뀌었다.

### 7.5 정적 자산 보강

초기 구축:

1. 개발 환경에서는 파일이 로컬에 그대로 있어 지도 이미지와 로고가 직접 보였다.
2. 운영 이미지 기준으로는 정적 자산 누락 가능성이 드러나지 않았다.

현재 구축:

1. `img/location_photo/...` 경로의 지도 이미지 포함
2. `/image 92.png` 로고 파일 포함
3. 운영 이미지에서도 실제 화면이 깨지지 않도록 보완 완료

즉, 현재 구축은 운영 화면 품질까지 고려한 상태다.

---

## 8. 왜 이렇게 바뀌었는가

초기 단계에서는 다음이 중요했다.

1. 빠르게 실행되는가
2. 개발 PC에서 재현 가능한가
3. 기존 코드 구조를 크게 안 건드리고 Docker 안에서 띄울 수 있는가

하지만 운영 배포 기준으로는 다음이 추가로 필요했다.

1. 개발 서버가 아니라 정적 배포 구조여야 함
2. reverse proxy가 있어야 함
3. health check와 운영 점검 기준이 있어야 함
4. 정적 자산 누락 없이 화면이 완전하게 떠야 함

따라서 초기 구축은 목적에 충실한 개발/테스트형 구조였고, 현재 구축은 그 위에 운영 요소를 보강한 형태라고 볼 수 있다.

---

## 9. 기대 효과

현재 구축 방식으로 변경되면서 기대되는 효과는 아래와 같다.

1. 운영 배포 적합성 향상
2. 요청 라우팅 구조 명확화
3. 장애 점검 및 상태 확인 가능
4. test와 prod 분리로 검증 절차 명확화
5. 화면 자산 누락 문제 해소

즉, 지금 구조는 단순히 실행되는 수준을 넘어 운영 준비도가 높아진 구조다.

---

## 10. 최종 요약

이번 변경의 본질은 아래와 같이 정리할 수 있다.

“처음에는 Windows/WSL에서 개발과 테스트를 빠르게 재현하는 Docker 구조였다면, 현재는 실제 운영 배포를 염두에 둔 production 기준 구조로 발전시켰다.”

요약하면 아래와 같다.

1. 초기 구축은 개발 재현과 테스트 목적이었다.
2. 현재 구축은 정식 운영 배포 목적이다.
3. 프런트는 dev server에서 정적 배포 구조로 바뀌었다.
4. nginx reverse proxy와 health check가 추가되었다.
5. 운영 이미지 기준 정적 자산까지 보완되었다.

현재 상태는 “개발 테스트용 Docker 재현” 단계를 넘어, “운영 배포가 가능한 Docker 구조”로 정리된 상태라고 설명할 수 있다.