ITAM-test/doc_readme2.md

# ITAM 도커라이징 최종 재현 가이드

## 1. 문서 목적

이 문서는 현재 Git 저장소에 올라간 파일만 가지고, 지금과 동일한 수준으로 ITAM 시스템을 도커라이징하고 실행하는 절차를 처음부터 끝까지 정리한 최종 가이드다.

이 문서만 읽어도 아래 목표를 달성할 수 있게 작성한다.

1. 현재 저장소 구조를 이해한다.
2. 왜 이렇게 도커라이징했는지 판단 근거를 안다.
3. WSL2 기반으로 실제 스택을 기동한다.
4. 외부 MySQL에서 내부 MySQL 컨테이너로 초기 데이터를 bootstrap 한다.
5. 프런트 8080과 백엔드 3000이 모두 정상 동작하는지 검증한다.
6. 재초기화, 재기동, 장애 확인까지 수행한다.

이 문서는 최종 성공 구조 기준이다. 실패 기록은 `doc_readme.md`를 본다.

---

## 2. 최종 목표 구조

현재 최종 구조는 아래 4개 서비스/역할로 나뉜다.

1. `frontend`: Vite 개발 서버 컨테이너, 포트 8080
2. `backend`: Express API 서버 컨테이너, 포트 3000
3. `db`: MySQL 8 컨테이너, 포트 3306
4. `db-bootstrap`: 외부 MySQL -> 내부 MySQL로 1회성 복제 수행 후 종료되는 도우미 컨테이너

논리 흐름은 다음과 같다.

```text
브라우저 -> frontend:8080 -> Vite proxy -> backend:3000 -> db:3306
                                      \
                                       -> /uploads -> backend 정적 경로

초기 1회 기동 시
외부 MySQL(.env) -> db-bootstrap -> 내부 MySQL(db)
```

---

## 3. 왜 이 구조를 선택했는가

이 저장소는 처음부터 운영형 정적 배포 앱이 아니었다. 실제 구조는 다음과 같았다.

1. 프런트는 Vite 개발 서버가 따로 돈다.
2. 백엔드는 Express API가 따로 돈다.
3. 프런트는 상대 경로 `/api`를 호출한다.
4. 백엔드는 프런트의 `dist`를 서빙하지 않는다.

따라서 내일 바로 시연 가능한 수준까지 빠르게 안정화하려면 아래 전략이 가장 맞다.

1. 프런트를 Vite dev server 그대로 컨테이너화한다.
2. 백엔드를 별도 컨테이너로 유지한다.
3. DB는 MySQL 8 컨테이너로 묶되, 초기 데이터는 외부 DB에서 복제한다.
4. 프런트 프록시는 컨테이너 네트워크 서비스명 `backend`로 붙게 한다.

즉, 현재 구조는 "개발형 구조를 Docker로 재현한 시연/개발용 Compose"다.

---

## 4. 저장소 내 최종 관련 파일 목록

현재 도커라이징과 직접 관련된 핵심 파일은 아래와 같다.

1. `.dockerignore`
2. `Dockerfile.frontend`
3. `Dockerfile.backend`
4. `docker-compose.yaml`
5. `start_docker_wsl.ps1`
6. `stop_docker_wsl.ps1`
7. `start_docker_wsl.bat`
8. `stop_docker_wsl.bat`
9. `docker/mysql/init/README.md`
10. `server.js`
11. `vite.config.ts`

각 파일 역할은 다음과 같다.

### 4.1 `.dockerignore`

Docker build context에서 제외할 파일을 정의한다.

주요 제외 대상은 다음과 같다.

1. `node_modules`
2. `dist`
3. `build`
4. `.git`
5. `.env`
6. `uploads`
7. `*.xlsx`
8. `*.log`

### 4.2 `Dockerfile.frontend`

프런트 컨테이너 이미지 정의다.

```dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 8080

CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
```

이 이미지는 Vite dev server를 컨테이너에서 띄우기 위한 것이다.

### 4.3 `Dockerfile.backend`

백엔드 컨테이너 이미지 정의다.

```dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 3000

CMD ["npm", "run", "server"]
```

### 4.4 `docker-compose.yaml`

전체 스택의 핵심 파일이다.

현재 최종 구성은 다음 논리를 가진다.

1. `db`는 MySQL 8 내부 DB다.
2. `db-bootstrap`은 외부 DB 데이터를 내부 DB로 1회 복제한다.
3. `backend`는 내부 `db`에 붙는다.
4. `frontend`는 `backend` 서비스명으로 프록시한다.

### 4.5 `start_docker_wsl.ps1`

Windows에서 WSL 경유로 Docker Compose를 안전하게 기동하는 진입점이다.

핵심은 다음 두 가지다.

1. 프로젝트 Windows 경로를 `wslpath`로 WSL 경로로 바꾼다.
2. 그 경로로 이동한 뒤 `docker compose up --build -d`를 수행한다.

### 4.6 `stop_docker_wsl.ps1`

같은 방식으로 WSL 내부에서 `docker compose down`을 수행해 스택을 안전하게 내린다.

### 4.7 `start_docker_wsl.bat`, `stop_docker_wsl.bat`

더블클릭 또는 간단 실행용 래퍼다. 내부적으로 PowerShell 스크립트를 호출한다.

### 4.8 `server.js`

중요 포인트는 다음 두 가지다.

1. `dotenv.config();`를 사용한다.
2. `dotenv.config({ override: true })`를 사용하지 않는다.

이 차이로 Compose 환경변수 `DB_HOST=db`가 `.env`보다 우선하도록 보장한다.

### 4.9 `vite.config.ts`

현재 프록시는 환경변수 기반으로 동작한다.

```ts
const proxyTarget = process.env.VITE_DEV_PROXY_TARGET || 'http://localhost:3000';
```

로컬 PC에서 직접 Vite를 띄우면 기본값 `http://localhost:3000`을 쓴다.
컨테이너에서는 Compose가 `http://backend:3000`을 주입한다.

---

## 5. 현재 최종 `docker-compose.yaml` 구조 설명

아래는 실제 동작 관점에서 읽어야 할 핵심 내용이다.

### 5.1 `db` 서비스

역할:

1. 내부 MySQL 데이터 저장소
2. 앱이 최종적으로 붙는 DB

핵심 설정:

1. 이미지: `mysql:8.0`
2. DB 이름: `itam`
3. 앱 계정: `itam_admin`
4. 데이터 볼륨: `itam_mysql_data`
5. healthcheck 사용

healthcheck는 `mysqladmin ping`으로 동작하며, `backend`와 `db-bootstrap`은 이 상태를 기다린다.

### 5.2 `db-bootstrap` 서비스

역할:

1. 외부 원본 DB에서 내부 `db`로 초기 데이터 복제
2. 1회성 작업 후 종료

핵심 포인트:

1. `.env`를 읽어 외부 DB 접속 정보를 가져온다.
2. 내부 `db`에 `asset_core` 테이블이 이미 존재하면 아무 것도 하지 않고 종료한다.
3. 그렇지 않으면 `mysqldump | mysql` 파이프라인으로 복제한다.
4. `restart: "no"` 이므로 정상 종료 후 반복 실행하지 않는다.

또한 source DB와 target DB 변수는 분리돼 있다.

1. source: `SOURCE_DB_*`
2. target: `TARGET_DB_*`

이 구조로 외부 원본 DB 자격증명과 내부 컨테이너 DB 자격증명이 섞이지 않는다.

### 5.3 `backend` 서비스

역할:

1. Express API 제공
2. 내부 `db`에 연결
3. `/uploads` 정적 제공

핵심 포인트:

1. `env_file: .env`를 유지하지만,
2. Compose `environment`에서 `DB_HOST=db`, `DB_PORT=3306`, `DB_USER=itam_admin`, `DB_PASS=itam1234`, `DB_NAME=itam`를 다시 지정한다.
3. `depends_on`은 `db` healthy와 `db-bootstrap` 성공 종료를 모두 기다린다.

즉, 백엔드는 DB bootstrap이 끝난 뒤 시작한다.

### 5.4 `frontend` 서비스

역할:

1. Vite dev server 제공
2. 브라우저 요청 `/api`, `/uploads`를 `backend`로 프록시

핵심 포인트:

1. `VITE_DEV_PROXY_TARGET: http://backend:3000`
2. `CHOKIDAR_USEPOLLING: "true"`
3. `npm run dev -- --host 0.0.0.0`

중요한 이유는 컨테이너 안의 `localhost`가 호스트의 `localhost`가 아니기 때문이다.

---

## 6. 사전 준비 조건

이 저장소를 지금처럼 기동하려면 다음 전제가 필요하다.

### 6.1 운영체제와 런타임

1. Windows
2. WSL2 Ubuntu 설치 및 실행 중
3. Docker CLI가 WSL 내부에서 동작 가능

권장 확인 명령:

```powershell
wsl -l -v
wsl sh -lc "docker --version"
```

### 6.2 `.env` 파일

현재 최종 구조는 "첫 기동 시 외부 DB에서 내부 DB로 bootstrap" 하는 방식이므로 `.env`가 반드시 필요하다.

최소한 다음 값은 외부 원본 DB를 가리켜야 한다.

```env
DB_HOST=<external-mysql-host>
DB_PORT=3306
DB_USER=<external-db-user>
DB_PASS=<external-db-password>
DB_NAME=itam
```

주의:

1. `.env`는 `db-bootstrap`이 외부 원본 DB에 접속할 때 사용한다.
2. `backend`는 최종적으로 내부 `db` 컨테이너를 쓰므로, 런타임에서는 Compose `environment`가 우선한다.

### 6.3 한글 경로 주의

현재 프로젝트 경로는 한글과 공백을 포함한다.

```text
c:\Users\user\Desktop\안건 파일\itam
```

이 때문에 Docker 관련 명령은 수동으로 경로를 조립하지 말고, `start_docker_wsl.ps1` / `stop_docker_wsl.ps1`을 우선 사용해야 한다.

---

## 7. 첫 기동 절차

이 절차는 "Git에서 소스를 받은 뒤 처음 올리는 경우" 기준이다.

### 7.1 저장소 준비

1. 저장소를 받는다.
2. `.env`가 올바른 외부 원본 DB를 가리키는지 확인한다.
3. WSL이 켜져 있는지 확인한다.

### 7.2 권장 실행 방법

Windows PowerShell에서 프로젝트 루트로 이동한 뒤 아래 중 하나를 사용한다.

방법 A:

```powershell
.\start_docker_wsl.ps1
```

방법 B:

```powershell
.\start_docker_wsl.bat
```

### 7.3 내부 실행 순서

스크립트는 내부적으로 다음 순서로 동작한다.

1. 현재 Windows 경로를 WSL 경로로 변환한다.
2. WSL 동작 여부를 확인한다.
3. WSL 내부 Docker 사용 가능 여부를 확인한다.
4. `docker compose up --build -d`를 수행한다.

### 7.4 기대되는 컨테이너 순서

정상이라면 다음 순서로 올라온다.

1. `itam-db`
2. `itam-db-bootstrap`
3. `itam-backend`
4. `itam-frontend`

`itam-db-bootstrap`은 정상이라면 최종 상태가 `Exited (0)`이어야 한다.

---

## 8. 첫 기동 후 검증 절차

기동 후에는 반드시 아래 검증을 수행한다.

### 8.1 컨테이너 상태 확인

```powershell
wsl sh -lc "docker ps -a --format 'table {{.Names}}\t{{.Status}}' | grep itam"
```

정상 기대 상태:

1. `itam-db` -> `Up ... (healthy)`
2. `itam-db-bootstrap` -> `Exited (0)`
3. `itam-backend` -> `Up`
4. `itam-frontend` -> `Up`

### 8.2 백엔드 API 직접 확인

```powershell
Invoke-WebRequest -Uri http://localhost:3000/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
```

정상 기대값:

1. `200`

### 8.3 프런트 경유 API 확인

```powershell
Invoke-WebRequest -Uri http://localhost:8080/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
```

정상 기대값:

1. `200`

### 8.4 데이터가 실제로 들어왔는지 확인

```powershell
wsl sh -lc "docker exec itam-db mysql -uitam_admin -pitam1234 -D itam -e 'SHOW TABLES' | head -n 20"
```

정상이라면 아래와 같은 테이블들이 보여야 한다.

1. `asset_core`
2. `asset_remote`
3. `asset_spec`
4. `asset_location`
5. `asset_history`
6. `asset_software_perpetual`
7. `asset_software_subscription`
8. `hardware_components_master`
9. `job_spec_standards`

### 8.5 브라우저 화면 확인

브라우저에서 아래 주소를 연다.

```text
http://localhost:8080
```

목록/대시보드 데이터가 보이면 화면까지 정상 연결된 것이다.

---

## 9. 재기동 절차

코드만 수정됐고 DB는 유지하고 싶다면 다음처럼 하면 된다.

### 9.1 스택 종료

```powershell
.\stop_docker_wsl.ps1
```

또는

```powershell
.\stop_docker_wsl.bat
```

### 9.2 스택 재기동

```powershell
.\start_docker_wsl.ps1
```

이 경우 `itam_mysql_data` 볼륨이 유지되므로, `db-bootstrap`은 내부 DB에 `asset_core`가 이미 있음을 감지하고 빠르게 종료한다.

---

## 10. DB를 완전히 다시 초기화하는 절차

외부 원본 DB에서 다시 처음부터 내부 DB를 복제하고 싶다면, MySQL 볼륨을 제거해야 한다.

### 10.1 스택 중지

```powershell
.\stop_docker_wsl.ps1
```

### 10.2 MySQL 데이터 볼륨 삭제

```powershell
wsl sh -lc "docker volume rm -f itam_itam_mysql_data"
```

### 10.3 다시 시작

```powershell
.\start_docker_wsl.ps1
```

이때 `db-bootstrap`이 외부 DB에서 내부 DB로 전체를 다시 복제한다.

---

## 11. 현재 구조에서 꼭 알아야 할 설계 포인트

### 11.1 `server.js`의 `dotenv.config()` 변경 이유

백엔드가 내부 DB로 붙게 하려면 Compose가 준 환경변수가 `.env`보다 우선해야 한다.

만약 아래처럼 `override: true`를 쓰면 안 된다.

```js
dotenv.config({ override: true });
```

이렇게 되면 내부 `db`가 아니라 `.env`의 외부 DB로 다시 붙을 수 있다.

현재는 아래가 맞다.

```js
dotenv.config();
```

### 11.2 왜 `docker-entrypoint-initdb.d` 기반 dump 파일을 안 쓰는가

처음에는 이 방식을 시도했지만, 실제 데이터의 긴 문자열/깨진 텍스트 때문에 import가 line 97에서 중단됐다.

그래서 현재는 더 안정적인 아래 방식을 쓴다.

1. 외부 DB에서 `mysqldump`
2. 파이프로 내부 `db`에 즉시 `mysql` import

즉, 파일 중간 생성물을 신뢰하지 않는 구조다.

### 11.3 왜 프런트 프록시 타깃을 환경변수화했는가

로컬 직접 실행과 컨테이너 실행의 네트워크 기준이 다르기 때문이다.

1. 로컬 직접 실행: `localhost:3000`이 맞다.
2. 컨테이너 내부 실행: `backend:3000`이 맞다.

그래서 `vite.config.ts`는 둘 다 수용할 수 있게 작성됐다.

---

## 12. 문제 발생 시 진단 순서

이 프로젝트에서는 문제를 아래 순서로 자르면 가장 빠르다.

### 12.1 브라우저 화면에 데이터가 없을 때

먼저 다음 둘을 분리해서 본다.

1. `http://localhost:3000/api/assets/master`
2. `http://localhost:8080/api/assets/master`

판단 기준:

1. `3000`은 200이고 `8080`만 실패면 프런트 프록시 문제다.
2. 둘 다 실패면 백엔드 또는 DB 문제다.

### 12.2 DB bootstrap이 성공했는지 확인할 때

```powershell
wsl sh -lc "docker ps -a --format 'table {{.Names}}\t{{.Status}}' | grep itam"
```

여기서 `itam-db-bootstrap`이 `Exited (0)`인지 본다.

### 12.3 내부 DB에 실제 데이터가 있는지 확인할 때

```powershell
wsl sh -lc "docker exec itam-db mysql -uitam_admin -pitam1234 -D itam -e 'SHOW TABLES'"
```

### 12.4 백엔드 로그 확인

```powershell
wsl sh -lc "docker logs --tail=200 itam-backend"
```

### 12.5 DB 로그 확인

```powershell
wsl sh -lc "docker logs --tail=200 itam-db"
```

### 12.6 프런트 로그 확인

```powershell
wsl sh -lc "docker logs --tail=200 itam-frontend"
```

---

## 13. 자주 나올 수 있는 장애와 해석

### 13.1 `docker` 명령이 PowerShell에서 안 보임

의미:

1. Windows 셸이 아니라 WSL에서 Docker를 쓰는 환경이다.

대응:

1. `start_docker_wsl.ps1` 사용

### 13.2 `asset_core` 테이블 없음

의미:

1. 내부 DB 초기화가 안 됐거나 bootstrap이 안 끝났다.

대응:

1. `db-bootstrap` 상태 확인
2. `.env` 외부 DB 접속 정보 확인
3. 필요하면 볼륨 삭제 후 재초기화

### 13.3 `3000` API는 되는데 화면은 비어 있음

의미:

1. DB는 정상이고 프런트 프록시 또는 화면 렌더링 문제다.

대응:

1. `8080/api/assets/master` 상태 먼저 확인

### 13.4 `db-bootstrap`가 실패 종료함

의미 후보:

1. `.env` 외부 DB 접속 정보 오류
2. 외부 DB 네트워크 접근 불가
3. 외부 계정 권한 문제

대응:

1. `docker logs itam-db-bootstrap` 확인

---

## 14. 현재 최종 검증 완료 상태

이 저장소는 아래 상태까지 검증이 완료됐다.

1. WSL2 Ubuntu에서 Docker 실행 가능
2. `start_docker_wsl.ps1`로 전체 스택 기동 가능
3. `db` 컨테이너 healthcheck 통과
4. `db-bootstrap`가 외부 DB에서 내부 DB로 데이터 복제 후 `Exited (0)` 종료
5. `backend`가 내부 `db`를 사용해 API 응답 가능
6. `frontend`가 `backend`를 프록시해 8080 기준 화면/API 동작 가능
7. 내부 MySQL에 실데이터 적재 확인

즉, 현재 Git에 올라간 상태만으로도 WSL2와 외부 원본 DB 정보만 있으면 지금과 같은 수준의 Docker 실행 재현이 가능하다.

---

## 15. 현재 구조의 한계와 다음 단계

현재 구조는 충분히 시연 가능하고 개발 재현도 가능하지만, 다음은 아직 별도 작업이 필요하다.

1. 운영형 정적 배포 구조 전환
2. 외부 DB 없이도 완전 독립 실행 가능한 정식 dump/backup 체계
3. `.env.example` 정리
4. DB bootstrap 전용 계정/권한 최소화
5. 장기적으로 `map_config.json` 파일 저장 정책 정리

하지만 "현재 저장소만으로 지금과 같은 Docker 실행 상태 재현"이라는 목표는 이미 충족한다.

---

## 16. 빠른 실행 요약

가장 짧게 요약하면 다음 순서다.

1. `.env`에 외부 원본 MySQL 접속 정보를 넣는다.
2. WSL2 Ubuntu와 WSL 내부 Docker가 살아 있는지 확인한다.
3. `start_docker_wsl.ps1`를 실행한다.
4. `itam-db-bootstrap`가 `Exited (0)`인지 확인한다.
5. `http://localhost:3000/api/assets/master`와 `http://localhost:8080/api/assets/master`가 모두 200인지 확인한다.
6. 브라우저에서 `http://localhost:8080`을 열어 데이터가 보이는지 확인한다.

이 순서대로 진행하면 현재 저장소 기준 Dockerized ITAM 시연 환경을 재현할 수 있다.

---

## 17. 2026-06-16 최신 정정

이 문서의 상단 본문은 한동안 사용했던 `내부 db + db-bootstrap` 구조를 기준으로 작성됐다. 하지만 오늘 기준 현재 저장소의 실제 `docker-compose.yaml`은 다시 `무상태 앱 컨테이너 + 외부 DB` 구조로 되돌아가 있다.

따라서 현재 시점의 정답 아키텍처는 아래다.

1. `backend` 컨테이너
2. `frontend` 컨테이너
3. 외부 MySQL DB

현재는 더 이상 아래 항목이 없다.

1. `db` 서비스 없음
2. `db-bootstrap` 서비스 없음
3. `itam_mysql_data` 볼륨 없음

### 17.1 현재 실제 `docker-compose.yaml` 기준 backend 동작

현재 backend는 `.env`의 외부 DB 접속 정보를 그대로 사용한다.

즉, 아래 환경변수 매핑이 현재 기준이다.

1. `DB_HOST: ${DB_HOST}`
2. `DB_PORT: ${DB_PORT}`
3. `DB_USER: ${DB_USER}`
4. `DB_PASS: ${DB_PASS}`
5. `DB_NAME: ${DB_NAME}`

`PORT: 3000`만 Compose에서 고정한다.

### 17.2 현재 실제 기동 구조

현재 스택 기동 순서는 단순하다.

1. `backend` 기동
2. `frontend` 기동
3. backend는 외부 DB에 직접 접속
4. frontend는 `http://backend:3000`으로 프록시

즉, 현재는 DB 컨테이너 초기화 단계나 bootstrap 단계가 존재하지 않는다.

### 17.3 현재 기준 첫 실행 체크리스트

오늘 기준으로는 아래 순서가 맞다.

1. `.env`에 외부 DB 접속 정보 입력
2. `start_docker_wsl.ps1` 또는 `start_docker_wsl.bat` 실행
3. `http://localhost:3000/api/assets/master`가 200인지 확인
4. `http://localhost:8080/api/assets/master`가 200인지 확인
5. 브라우저에서 `http://localhost:8080` 접속 후 데이터 표시 확인

### 17.4 이 문서에서 현재 유효한 부분과 과거 이력 부분

현재도 그대로 유효한 내용은 아래다.

1. WSL2 기반 실행 방식
2. `start_docker_wsl.ps1` / `stop_docker_wsl.ps1` 사용 방식
3. `server.js`에서 Compose 환경변수가 `.env`보다 우선되도록 `dotenv.config()`를 유지해야 한다는 점
4. `vite.config.ts`에서 프록시 타깃을 환경변수화해야 한다는 점

현재는 과거 이력으로만 읽어야 하는 내용은 아래다.

1. 내부 `db` 서비스 설명
2. `db-bootstrap` 설명
3. `itam_mysql_data` 볼륨 설명
4. 내부 DB 재초기화 절차
5. 내부 테이블 확인 절차

### 17.5 현재 최종 한 줄 요약

오늘 날짜 기준 현재 저장소의 실사용 Compose 구조는 `frontend + backend + external DB`이며, 이전의 내부 DB/bootstrap 구조는 역사적으로 한 번 사용했던 임시 해결책으로만 남아 있다.