730 lines
18 KiB
Markdown
730 lines
18 KiB
Markdown
# ITAM 도커라이징 실전 가이드
|
|
|
|
## 1. 문서 목적
|
|
|
|
이 문서는 Gitea에 올라가 있는 현재 저장소를 기준으로, 개발 PC에 WSL2와 Ubuntu만 설치되어 있는 상태에서 지금의 Docker 실행 구조를 재현하는 방법을 처음부터 끝까지 설명하는 실전 가이드다.
|
|
|
|
이 문서는 아래 상황을 가정한다.
|
|
|
|
1. 소스 코드는 아직 로컬에 없거나, Gitea에서 막 받아올 예정이다.
|
|
2. Windows에는 WSL2와 Ubuntu는 설치되어 있다.
|
|
3. 그 외 Docker 관련 세팅은 아직 안 되어 있을 수 있다.
|
|
4. 최종 목표는 현재 저장소 기준 `frontend + backend + external DB` 구조를 Docker로 재현하는 것이다.
|
|
|
|
이 문서의 목적은 아래 네 가지다.
|
|
|
|
1. 현재 시스템 구조와 Docker 구조를 먼저 이해하게 한다.
|
|
2. 기존 파일 중 무엇이 새로 추가되었고 무엇이 수정되었는지 정리한다.
|
|
3. 각 단계별로 정확히 어디에서 명령을 실행해야 하는지 명시한다.
|
|
4. Gitea 소스만 받은 상태에서 지금과 같은 Docker 실행 상태까지 도달하게 한다.
|
|
|
|
---
|
|
|
|
## 2. 현재 시스템 구조 개요
|
|
|
|
## 2.1 애플리케이션 원래 구조
|
|
|
|
현재 저장소의 본래 실행 구조는 다음과 같다.
|
|
|
|
1. 프런트엔드: Vite 기반 TypeScript 앱
|
|
2. 백엔드: Express 기반 Node.js API 서버
|
|
3. 데이터베이스: 외부 MySQL 서버
|
|
|
|
즉, 원래부터 MySQL이 Docker 안에 들어 있던 구조가 아니다.
|
|
|
|
프런트와 백엔드는 각각 별도 프로세스로 실행되며, 프런트는 `/api` 상대 경로로 백엔드 API를 호출한다.
|
|
|
|
---
|
|
|
|
## 2.2 현재 Docker 구조
|
|
|
|
현재 최종 Docker 구조는 아래와 같다.
|
|
|
|
1. `frontend` 컨테이너
|
|
2. `backend` 컨테이너
|
|
3. 외부 MySQL DB
|
|
|
|
즉, 지금은 내부 `db` 컨테이너가 없고, 내부 `db-bootstrap` 컨테이너도 없다.
|
|
|
|
현재 구조를 문장으로 풀면 다음과 같다.
|
|
|
|
1. 브라우저는 `http://localhost:8080`으로 `frontend` 컨테이너에 접속한다.
|
|
2. `frontend`는 `/api` 요청을 `backend:3000`으로 프록시한다.
|
|
3. `backend`는 `.env`에 적힌 외부 DB 정보로 외부 MySQL에 직접 접속한다.
|
|
4. 조회 결과 JSON을 프런트가 받아 화면에 렌더링한다.
|
|
|
|
간단한 흐름은 아래와 같다.
|
|
|
|
```text
|
|
Browser
|
|
-> frontend container :8080
|
|
-> Vite proxy (/api)
|
|
-> backend container :3000
|
|
-> external MySQL (.env)
|
|
```
|
|
|
|
---
|
|
|
|
## 2.3 왜 이 구조가 맞는가
|
|
|
|
현재 구조가 적절한 이유는 다음과 같다.
|
|
|
|
1. 원래 시스템도 외부 MySQL을 쓰는 구조였다.
|
|
2. 지금 목표는 운영형 단일 배포가 아니라 현재 개발형 구조를 Docker로 재현하는 것이다.
|
|
3. 프런트는 Vite dev server 기반이라 운영형 nginx 정적 배포 구조로 억지로 바꾸는 것보다, 현 구조를 유지하는 편이 안전하다.
|
|
4. 실무 표준 관점에서도 앱 컨테이너는 무상태로 유지하고, DB는 외부 인프라를 사용하는 구성이 더 일반적이다.
|
|
|
|
---
|
|
|
|
## 3. 이번 도커라이징에서 추가되거나 수정된 파일 정리
|
|
|
|
아래 파일들은 이번 Docker 재현 구조를 위해 새로 추가되었거나 수정된 핵심 파일이다.
|
|
|
|
## 3.1 새로 추가된 파일
|
|
|
|
1. `Dockerfile.frontend`
|
|
2. `Dockerfile.backend`
|
|
3. `.dockerignore`
|
|
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. `docker_task_plan.md`
|
|
11. `doc_readme2.md`
|
|
|
|
---
|
|
|
|
## 3.2 기존 파일 중 수정된 핵심 파일
|
|
|
|
1. `server.js`
|
|
2. `vite.config.ts`
|
|
3. `doc_readme.md`
|
|
|
|
---
|
|
|
|
## 3.3 각 파일의 역할
|
|
|
|
### `Dockerfile.frontend`
|
|
|
|
역할:
|
|
|
|
1. 프런트 Vite 개발 서버 이미지를 만든다.
|
|
2. 컨테이너 내부에서 `npm run dev -- --host 0.0.0.0`를 실행한다.
|
|
|
|
### `Dockerfile.backend`
|
|
|
|
역할:
|
|
|
|
1. 백엔드 Express 서버 이미지를 만든다.
|
|
2. 컨테이너 내부에서 `npm run server`를 실행한다.
|
|
|
|
### `.dockerignore`
|
|
|
|
역할:
|
|
|
|
1. `node_modules`, `build`, `.git`, `.env`, `uploads` 같은 불필요한 파일을 Docker build context에서 제외한다.
|
|
|
|
### `docker-compose.yaml`
|
|
|
|
역할:
|
|
|
|
1. `frontend`, `backend` 두 컨테이너를 동시에 띄운다.
|
|
2. `backend`는 `.env`의 외부 DB를 사용한다.
|
|
3. `frontend`는 `backend:3000`으로 프록시한다.
|
|
|
|
### `start_docker_wsl.ps1`
|
|
|
|
역할:
|
|
|
|
1. Windows 경로를 WSL 경로로 안전하게 바꾼다.
|
|
2. WSL 내부 Docker를 사용해 `docker compose up --build -d`를 실행한다.
|
|
3. 한글 경로와 공백 경로에서도 안정적으로 실행되게 한다.
|
|
|
|
### `stop_docker_wsl.ps1`
|
|
|
|
역할:
|
|
|
|
1. 같은 방식으로 WSL 내부에서 `docker compose down`을 실행한다.
|
|
|
|
### `start_docker_wsl.bat`, `stop_docker_wsl.bat`
|
|
|
|
역할:
|
|
|
|
1. PowerShell 스크립트를 쉽게 실행하는 래퍼 역할을 한다.
|
|
|
|
### `server.js`
|
|
|
|
중요 수정 사항:
|
|
|
|
1. `dotenv.config({ override: true })`가 아니라 `dotenv.config()`를 사용한다.
|
|
|
|
이유:
|
|
|
|
1. Compose나 실행 환경이 주는 환경변수를 `.env`가 덮어써 버리면 안 된다.
|
|
2. 외부 DB 정보와 포트 설정 등 실행 환경 우선 구조를 유지해야 한다.
|
|
|
|
### `vite.config.ts`
|
|
|
|
중요 수정 사항:
|
|
|
|
1. 프록시 타깃을 고정 `localhost:3000`이 아니라 환경변수 기반으로 받도록 바꿨다.
|
|
|
|
현재 구조:
|
|
|
|
```ts
|
|
const proxyTarget = process.env.VITE_DEV_PROXY_TARGET || 'http://localhost:3000';
|
|
```
|
|
|
|
이유:
|
|
|
|
1. 로컬에서 직접 프런트를 띄울 때는 `localhost:3000`이 맞다.
|
|
2. Docker 안에서는 `frontend` 컨테이너에서 보는 `localhost`가 백엔드가 아니므로 `backend:3000`을 써야 한다.
|
|
|
|
---
|
|
|
|
## 4. 현재 `docker-compose.yaml` 기준 실제 동작 구조
|
|
|
|
현재 `docker-compose.yaml`은 아래 구조다.
|
|
|
|
### `backend`
|
|
|
|
1. `Dockerfile.backend`로 이미지를 빌드한다.
|
|
2. `.env`를 읽는다.
|
|
3. DB 관련 변수는 `${DB_HOST}`, `${DB_PORT}`, `${DB_USER}`, `${DB_PASS}`, `${DB_NAME}`를 그대로 사용한다.
|
|
4. 포트 `3000:3000`으로 노출한다.
|
|
5. `uploads`, `map_config.json`을 마운트한다.
|
|
|
|
### `frontend`
|
|
|
|
1. `Dockerfile.frontend`로 이미지를 빌드한다.
|
|
2. `VITE_DEV_PROXY_TARGET: http://backend:3000` 환경변수를 사용한다.
|
|
3. 포트 `8080:8080`으로 노출한다.
|
|
4. 브라우저의 `/api` 요청을 `backend`로 프록시한다.
|
|
|
|
즉, 현재 Compose는 DB를 띄우지 않고 앱 두 개만 띄운다.
|
|
|
|
---
|
|
|
|
## 5. 사전 준비 사항
|
|
|
|
이 섹션은 Gitea에서 코드를 받기 전 또는 받은 직후에 확인해야 한다.
|
|
|
|
## 5.1 가정하는 기본 상태
|
|
|
|
이미 설치되어 있다고 가정하는 것:
|
|
|
|
1. Windows
|
|
2. WSL2
|
|
3. Ubuntu 배포판
|
|
|
|
아직 없을 수 있는 것:
|
|
|
|
1. Docker Desktop 또는 WSL 내부 Docker 사용 환경
|
|
2. Git 클라이언트
|
|
3. 프로젝트 `.env`
|
|
|
|
---
|
|
|
|
## 5.2 권장 Docker 실행 방식
|
|
|
|
현재 저장소 구조상 가장 권장하는 방식은 다음이다.
|
|
|
|
1. Windows에 Docker Desktop 설치
|
|
2. Docker Desktop에서 WSL2 통합 활성화
|
|
3. Ubuntu WSL 내부에서 `docker` 명령을 사용할 수 있게 한다.
|
|
|
|
이유:
|
|
|
|
1. 현재 `start_docker_wsl.ps1`가 WSL 내부의 `docker`를 호출하는 구조다.
|
|
2. 실제 검증도 WSL 내부 Docker 기준으로 이루어졌다.
|
|
|
|
---
|
|
|
|
## 5.3 외부 DB 정보 준비
|
|
|
|
현재 구조는 외부 MySQL을 사용하므로 `.env` 파일이 반드시 필요하다.
|
|
|
|
최소한 아래 값이 필요하다.
|
|
|
|
```env
|
|
DB_HOST=<외부 MySQL 호스트>
|
|
DB_PORT=3306
|
|
DB_USER=<외부 MySQL 계정>
|
|
DB_PASS=<외부 MySQL 비밀번호>
|
|
DB_NAME=itam
|
|
```
|
|
|
|
필요 시 추가 환경변수는 현재 백엔드 코드 기준으로 함께 넣을 수 있다.
|
|
|
|
---
|
|
|
|
## 6. Gitea에서 소스 받기
|
|
|
|
## 6.1 작업 실행 위치
|
|
|
|
이 단계는 **Windows PowerShell** 또는 **Windows 터미널의 PowerShell**에서 수행한다.
|
|
|
|
실행 위치 이유:
|
|
|
|
1. 이후 `start_docker_wsl.ps1`도 Windows PowerShell에서 실행하는 것이 가장 자연스럽다.
|
|
2. 로컬 작업 폴더를 Windows 경로 기준으로 준비할 수 있다.
|
|
|
|
---
|
|
|
|
## 6.2 소스 클론
|
|
|
|
예시:
|
|
|
|
```powershell
|
|
git clone <Gitea 저장소 URL>
|
|
cd <클론된 저장소 경로>
|
|
```
|
|
|
|
현재 프로젝트처럼 한글 경로를 사용할 수도 있지만, 가능하면 너무 복잡한 경로는 피하는 것이 좋다.
|
|
|
|
현재 실제 프로젝트 경로 예시는 아래였다.
|
|
|
|
```text
|
|
c:\Users\user\Desktop\안건 파일\itam
|
|
```
|
|
|
|
이 경로도 현재 스크립트로는 동작 가능하다.
|
|
|
|
---
|
|
|
|
## 7. Docker 환경 준비
|
|
|
|
## 7.1 작업 실행 위치
|
|
|
|
이 단계는 **Windows PowerShell**과 **WSL Ubuntu 터미널**을 둘 다 사용한다.
|
|
|
|
1. 설치 확인은 Windows PowerShell에서 시작
|
|
2. 실제 Docker 동작 확인은 WSL Ubuntu에서 수행
|
|
|
|
---
|
|
|
|
## 7.2 Docker Desktop 설치 여부 확인
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
docker version
|
|
```
|
|
|
|
만약 여기서 바로 안 잡혀도 현재 프로젝트는 WSL 내부 Docker를 쓰므로, 다음 단계로 넘어가 WSL 내부 확인을 한다.
|
|
|
|
---
|
|
|
|
## 7.3 WSL 내부 Docker 확인
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
wsl -l -v
|
|
wsl sh -lc "docker --version"
|
|
```
|
|
|
|
정상 기대 결과:
|
|
|
|
1. Ubuntu가 Running 상태
|
|
2. `docker --version`이 정상 출력
|
|
|
|
만약 `docker --version`이 실패하면, Docker Desktop 설치 및 WSL 통합을 먼저 완료해야 한다.
|
|
|
|
---
|
|
|
|
## 8. `.env` 파일 준비
|
|
|
|
## 8.1 작업 실행 위치
|
|
|
|
이 단계는 **Windows PowerShell**, **VS Code**, 또는 아무 텍스트 편집기**에서 수행한다.
|
|
|
|
즉, 프로젝트 루트에 `.env` 파일을 만드는 작업이다.
|
|
|
|
---
|
|
|
|
## 8.2 `.env` 작성
|
|
|
|
프로젝트 루트에 `.env`를 만든다.
|
|
|
|
예시:
|
|
|
|
```env
|
|
DB_HOST=your-external-db-host
|
|
DB_PORT=3306
|
|
DB_USER=your-db-user
|
|
DB_PASS=your-db-password
|
|
DB_NAME=itam
|
|
```
|
|
|
|
주의:
|
|
|
|
1. 현재 Compose는 내부 DB를 만들지 않는다.
|
|
2. 따라서 이 값이 곧 실제 운영/개발 외부 DB 연결 정보다.
|
|
3. 이 정보가 틀리면 `backend`는 기동해도 API에서 DB 오류가 난다.
|
|
|
|
---
|
|
|
|
## 9. 현재 Docker 파일이 어떻게 동작하는지 이해하기
|
|
|
|
## 9.1 `Dockerfile.frontend`
|
|
|
|
**확인 위치: 프로젝트 루트 / VS Code**
|
|
|
|
현재 내용 핵심:
|
|
|
|
```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"]
|
|
```
|
|
|
|
의미:
|
|
|
|
1. Node 20 Alpine 기반
|
|
2. 의존성 설치 후 전체 소스 복사
|
|
3. Vite 개발 서버 실행
|
|
|
|
---
|
|
|
|
## 9.2 `Dockerfile.backend`
|
|
|
|
**확인 위치: 프로젝트 루트 / VS Code**
|
|
|
|
현재 내용 핵심:
|
|
|
|
```dockerfile
|
|
FROM node:20-alpine
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci
|
|
COPY . .
|
|
EXPOSE 3000
|
|
CMD ["npm", "run", "server"]
|
|
```
|
|
|
|
의미:
|
|
|
|
1. Node 20 Alpine 기반
|
|
2. Express 서버 실행
|
|
|
|
---
|
|
|
|
## 9.3 `vite.config.ts`
|
|
|
|
**확인 위치: 프로젝트 루트 / VS Code**
|
|
|
|
현재 핵심:
|
|
|
|
```ts
|
|
const proxyTarget = process.env.VITE_DEV_PROXY_TARGET || 'http://localhost:3000';
|
|
```
|
|
|
|
그리고 `/api`, `/uploads`가 모두 `proxyTarget`으로 프록시된다.
|
|
|
|
의미:
|
|
|
|
1. 로컬 실행 시 기본값은 `localhost:3000`
|
|
2. Docker 실행 시 Compose가 `http://backend:3000`을 주입
|
|
|
|
이 수정이 있어야 Docker 안에서도 화면에 데이터가 표시된다.
|
|
|
|
---
|
|
|
|
## 10. Docker Compose 기동
|
|
|
|
## 10.1 작업 실행 위치
|
|
|
|
이 단계는 반드시 **Windows PowerShell**에서 수행하는 것을 권장한다.
|
|
|
|
이유:
|
|
|
|
1. `start_docker_wsl.ps1`가 Windows 경로를 받아 WSL 경로로 바꾸는 구조다.
|
|
2. 한글/공백 경로에서 가장 안전하다.
|
|
|
|
---
|
|
|
|
## 10.2 권장 기동 방법
|
|
|
|
**실행 위치: 프로젝트 루트의 Windows PowerShell**
|
|
|
|
```powershell
|
|
.\start_docker_wsl.ps1
|
|
```
|
|
|
|
또는
|
|
|
|
```powershell
|
|
.\start_docker_wsl.bat
|
|
```
|
|
|
|
이 스크립트는 내부적으로 아래를 수행한다.
|
|
|
|
1. PowerShell 출력 인코딩을 UTF-8로 설정
|
|
2. 현재 Windows 경로를 WSL 경로로 변환
|
|
3. WSL 동작 확인
|
|
4. WSL 내부 Docker 동작 확인
|
|
5. `docker compose up --build -d` 수행
|
|
|
|
---
|
|
|
|
## 10.3 직접 기동이 필요할 때
|
|
|
|
**실행 위치: WSL Ubuntu 터미널**
|
|
|
|
직접 실행 예시는 아래와 같다.
|
|
|
|
```bash
|
|
cd /mnt/c/Users/user/Desktop/안건\ 파일/itam
|
|
docker compose up --build -d
|
|
```
|
|
|
|
하지만 현재 프로젝트는 한글 경로 이슈가 있었기 때문에, 특별한 이유가 없으면 `start_docker_wsl.ps1`를 우선 사용한다.
|
|
|
|
---
|
|
|
|
## 11. 컨테이너 기동 후 검증
|
|
|
|
## 11.1 컨테이너 상태 확인
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
wsl sh -lc "docker ps -a --format 'table {{.Names}}\t{{.Status}}' | grep itam"
|
|
```
|
|
|
|
정상 기대 상태:
|
|
|
|
1. `itam-backend` -> `Up`
|
|
2. `itam-frontend` -> `Up`
|
|
|
|
현재는 `itam-db`, `itam-db-bootstrap`가 없어야 정상이다.
|
|
|
|
---
|
|
|
|
## 11.2 백엔드 API 확인
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
Invoke-WebRequest -Uri http://localhost:3000/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
|
|
```
|
|
|
|
정상 기대값:
|
|
|
|
1. `200`
|
|
|
|
이 검사는 `backend`가 외부 DB에 정상 연결됐는지 보는 가장 직접적인 검사다.
|
|
|
|
---
|
|
|
|
## 11.3 프런트 경유 API 확인
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
Invoke-WebRequest -Uri http://localhost:8080/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
|
|
```
|
|
|
|
정상 기대값:
|
|
|
|
1. `200`
|
|
|
|
이 검사는 프런트 프록시가 정상인지 확인한다.
|
|
|
|
예전에 화면에 데이터가 안 보였던 것은 외부 DB 자체가 아니라, 이 프록시 경로가 잘못돼 있었기 때문이다.
|
|
|
|
---
|
|
|
|
## 11.4 브라우저 화면 확인
|
|
|
|
**실행 위치: 브라우저**
|
|
|
|
```text
|
|
http://localhost:8080
|
|
```
|
|
|
|
확인 포인트:
|
|
|
|
1. 화면이 열리는지
|
|
2. 목록/대시보드/테이블 데이터가 비어 있지 않은지
|
|
3. 모달 진입 시 데이터가 정상적으로 보이는지
|
|
|
|
---
|
|
|
|
## 12. 지금 데이터가 표시되는 원리
|
|
|
|
현재는 내부 DB로 데이터를 옮겨 담지 않는다.
|
|
|
|
현재 실제 동작 원리는 다음과 같다.
|
|
|
|
1. 브라우저가 `frontend`에 접속한다.
|
|
2. 프런트가 `/api/...`로 요청한다.
|
|
3. Vite 프록시가 `backend:3000`으로 요청을 넘긴다.
|
|
4. `backend`가 `.env`의 외부 MySQL에 직접 접속한다.
|
|
5. 조회 결과 JSON을 프런트가 받아 화면에 렌더링한다.
|
|
|
|
즉, 현재는 아래 구조다.
|
|
|
|
```text
|
|
Browser -> frontend -> backend -> external MySQL
|
|
```
|
|
|
|
예전 외부 DB 구조에서 화면에 데이터가 안 보였던 이유는 외부 DB 때문이 아니라, 프런트 컨테이너가 `localhost:3000`을 잘못 바라보고 있었기 때문이다.
|
|
|
|
지금은 `VITE_DEV_PROXY_TARGET: http://backend:3000`으로 수정되어 있기 때문에 정상 표시된다.
|
|
|
|
---
|
|
|
|
## 13. 자주 헷갈리는 포인트
|
|
|
|
## 13.1 현재는 내부 DB 컨테이너가 없다
|
|
|
|
현재 `docker-compose.yaml`에는 아래가 없다.
|
|
|
|
1. `db` 서비스
|
|
2. `db-bootstrap` 서비스
|
|
3. `itam_mysql_data` 볼륨
|
|
|
|
즉, DB는 Docker 스택 밖에 있다.
|
|
|
|
---
|
|
|
|
## 13.2 현재는 `.env`가 곧 실제 DB 연결 정보다
|
|
|
|
현재 `backend`는 아래처럼 Compose에서 그대로 받는다.
|
|
|
|
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}`
|
|
|
|
즉, `.env`를 틀리게 적으면 화면도 데이터가 안 뜬다.
|
|
|
|
---
|
|
|
|
## 13.3 `server.js`는 여전히 중요하게 수정된 상태다
|
|
|
|
현재 `server.js`는 `dotenv.config()`를 사용한다.
|
|
|
|
이 구조는 이후 Compose나 실행 환경에서 변수를 주입할 때, 애플리케이션이 그 값을 받아들일 수 있게 하기 위해 유지해야 한다.
|
|
|
|
---
|
|
|
|
## 14. 스택 중지 방법
|
|
|
|
## 14.1 작업 실행 위치
|
|
|
|
**Windows PowerShell / 프로젝트 루트**
|
|
|
|
---
|
|
|
|
## 14.2 권장 종료 명령
|
|
|
|
```powershell
|
|
.\stop_docker_wsl.ps1
|
|
```
|
|
|
|
또는
|
|
|
|
```powershell
|
|
.\stop_docker_wsl.bat
|
|
```
|
|
|
|
이 스크립트는 내부적으로 WSL 경로 변환 후 `docker compose down`을 수행한다.
|
|
|
|
---
|
|
|
|
## 15. 장애 발생 시 점검 순서
|
|
|
|
## 15.1 `frontend` 화면은 뜨는데 데이터가 없을 때
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
먼저 아래 두 API를 분리해서 본다.
|
|
|
|
```powershell
|
|
Invoke-WebRequest -Uri http://localhost:3000/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
|
|
Invoke-WebRequest -Uri http://localhost:8080/api/assets/master -UseBasicParsing | Select-Object -ExpandProperty StatusCode
|
|
```
|
|
|
|
판단 기준:
|
|
|
|
1. `3000`은 200이고 `8080`만 실패 -> 프런트 프록시 문제
|
|
2. 둘 다 실패 -> 백엔드 또는 외부 DB 연결 문제
|
|
|
|
---
|
|
|
|
## 15.2 백엔드가 외부 DB에 연결되지 않을 때
|
|
|
|
**실행 위치: Windows PowerShell**
|
|
|
|
```powershell
|
|
wsl sh -lc "docker logs --tail=200 itam-backend"
|
|
```
|
|
|
|
점검 항목:
|
|
|
|
1. `.env`의 DB 정보가 정확한지
|
|
2. 외부 DB 서버 접근이 가능한지
|
|
3. 계정/비밀번호가 맞는지
|
|
4. 방화벽 또는 네트워크 이슈가 없는지
|
|
|
|
---
|
|
|
|
## 15.3 프런트 프록시가 의심될 때
|
|
|
|
**확인 위치: `vite.config.ts`, `docker-compose.yaml`**
|
|
|
|
다음 두 설정이 유지되는지 확인한다.
|
|
|
|
`vite.config.ts`
|
|
|
|
```ts
|
|
const proxyTarget = process.env.VITE_DEV_PROXY_TARGET || 'http://localhost:3000';
|
|
```
|
|
|
|
`docker-compose.yaml`
|
|
|
|
```yaml
|
|
VITE_DEV_PROXY_TARGET: http://backend:3000
|
|
```
|
|
|
|
이 둘 중 하나라도 바뀌면 Docker 안에서 화면 데이터가 다시 안 보일 수 있다.
|
|
|
|
---
|
|
|
|
## 16. 현재 기준 재현 절차 요약
|
|
|
|
가장 짧게 정리하면 아래 순서다.
|
|
|
|
1. Gitea에서 소스를 클론한다.
|
|
2. Windows PowerShell에서 프로젝트 루트로 이동한다.
|
|
3. `.env`에 외부 MySQL 정보를 작성한다.
|
|
4. Docker Desktop + WSL 통합 또는 WSL 내부 Docker 사용 가능 상태를 만든다.
|
|
5. `start_docker_wsl.ps1`를 실행한다.
|
|
6. `http://localhost:3000/api/assets/master`가 200인지 확인한다.
|
|
7. `http://localhost:8080/api/assets/master`가 200인지 확인한다.
|
|
8. 브라우저에서 `http://localhost:8080`을 열어 실제 데이터 표시를 확인한다.
|
|
|
|
---
|
|
|
|
## 17. 현재 최종 결론
|
|
|
|
현재 저장소의 도커라이징 구조는 실무 표준에 맞는 `무상태 앱 컨테이너 + 외부 DB` 구조다.
|
|
|
|
현재 핵심은 아래 세 가지다.
|
|
|
|
1. `backend`는 외부 MySQL에 직접 연결한다.
|
|
2. `frontend`는 `backend:3000`으로 API 프록시한다.
|
|
3. WSL 경로 변환 스크립트를 통해 Windows 한글 경로에서도 안정적으로 실행한다.
|
|
|
|
즉, 이 문서대로 진행하면 Gitea 소스만 받은 상태에서 지금과 같은 Docker 실행 구조를 재현할 수 있다.
|