ERP-node/DOCKER.md

# 🐳 Docker 가이드 - WACE 솔루션 (ERP-node)

이 문서는 WACE 솔루션의 Docker 환경 설정 및 사용법을 설명합니다.

## 📋 개요

**기술 스택:**

- **백엔드**: Node.js + TypeScript + PostgreSQL (Raw Query)
- **프론트엔드**: Next.js + TypeScript + Tailwind CSS
- **컨테이너**: Docker + Docker Compose

**환경:**

- **개발**: Mac (볼륨 마운트 + Hot Reload)
- **운영**: Linux 서버 (최적화된 프로덕션 빌드)

---

## 🔧 개발 환경 (Mac)

### 빠른 시작

```bash
# 전체 서비스 시작 (병렬 빌드 - 가장 빠름!)
./scripts/dev/start-all-parallel.sh
```

### 개별 서비스 시작

```bash
# 백엔드만 시작
./scripts/dev/start-backend.sh

# 프론트엔드만 시작
./scripts/dev/start-frontend.sh
```

### 개발용 Docker Compose 파일들

- **`docker/dev/docker-compose.backend.mac.yml`** - Mac 개발용 백엔드

  - 볼륨 마운트: `./backend-node:/app` (Hot Reload)
  - Dockerfile: `docker/dev/backend.Dockerfile`
  - 포트: `8080`

- **`docker/dev/docker-compose.frontend.mac.yml`** - Mac 개발용 프론트엔드
  - 볼륨 마운트: `./frontend:/app` (Hot Reload)
  - Dockerfile: `docker/dev/frontend.Dockerfile`
  - 포트: `3000`

### 개발 환경 특징

- ✅ **Hot Reload**: 코드 변경 시 자동 반영
- ✅ **볼륨 마운트**: 실시간 개발
- ✅ **디버그 모드**: 상세 로그 출력
- ✅ **빠른 재시작**: Docker 재빌드 불필요

### 🔥 Hot Reload 상세 가이드

#### ✅ **바로 반영되는 것들 (즉시 Hot Reload)**

**백엔드 (Node.js + TypeScript):**

```bash
backend-node/src/controllers/*.ts    # API 컨트롤러 수정
backend-node/src/services/*.ts       # 비즈니스 로직 수정
backend-node/src/routes/*.ts         # 라우터 설정 수정
backend-node/src/middleware/*.ts     # 미들웨어 수정
backend-node/src/utils/*.ts          # 유틸리티 함수 수정
backend-node/src/types/*.ts          # 타입 정의 수정
backend-node/src/config/*.ts         # 애플리케이션 설정
```

→ **반영 시간**: 1-2초 (nodemon 자동 재시작)

**프론트엔드 (Next.js + TypeScript):**

```bash
frontend/components/**/*.tsx         # React 컴포넌트 수정
frontend/app/**/*.tsx               # 페이지 컴포넌트 수정
frontend/lib/**/*.ts                # 유틸리티 함수 수정
frontend/hooks/*.ts                 # 커스텀 훅 수정
frontend/types/*.ts                 # 타입 정의 수정
frontend/constants/*.ts             # 상수 정의 수정
CSS/SCSS 파일 수정                   # 스타일 변경
```

→ **반영 시간**: 즉시 (Fast Refresh)

#### ❌ **Docker 재시작이 필요한 것들**

**의존성 변경:**

```bash
package.json 수정                   # 새 패키지 추가/제거
npm install / npm uninstall         # 패키지 설치/제거
package-lock.json 변경              # 의존성 잠금 파일
```

**데이터베이스 관련:**

```bash
db/ilshin.pgsql                    # DB 스키마 파일 변경
db/00-create-roles.sh              # DB 초기화 스크립트 변경
# SQL 마이그레이션은 직접 실행
```

**설정 파일:**

```bash
next.config.mjs                     # Next.js 설정
tsconfig.json                       # TypeScript 설정
tailwind.config.js                  # Tailwind CSS 설정
.env / .env.local                   # 환경 변수
eslint.config.mjs                   # ESLint 설정
```

**Docker 관련:**

```bash
Dockerfile / Dockerfile.dev         # 도커 파일 수정
docker-compose.*.yml                # Docker Compose 설정
.dockerignore                       # Docker 무시 파일
```

#### 🔄 **재시작 방법**

**특정 서비스만 재시작:**

```bash
# 백엔드만 재시작
docker-compose -f docker-compose.backend.mac.yml restart backend

# 프론트엔드만 재시작
docker-compose -f docker-compose.frontend.mac.yml restart frontend
```

**전체 재빌드:**

```bash
# 의존성 변경 시 (rebuild 필요)
docker-compose -f docker-compose.backend.mac.yml up --build -d
docker-compose -f docker-compose.frontend.mac.yml up --build -d
```

---

## 🚀 운영 환경 (Linux)

### 운영 서버 배포

```bash
# Linux 서버에서 실행
./scripts/prod/start-all-linux.sh
```

### 개별 서비스 시작 (운영용)

```bash
# 직접 Docker Compose 사용
docker-compose -f docker/prod/docker-compose.backend.prod.yml up -d
docker-compose -f docker/prod/docker-compose.frontend.prod.yml up -d
```

### 운영용 Docker Compose 파일들

- **`docker/prod/docker-compose.backend.prod.yml`** - 운영용 백엔드

  - Dockerfile: `docker/prod/backend.Dockerfile` (프로덕션 최적화)
  - 포트: `8080`
  - 환경: `NODE_ENV=production`

- **`docker/prod/docker-compose.frontend.prod.yml`** - 운영용 프론트엔드
  - Dockerfile: `docker/prod/frontend.Dockerfile` (프로덕션 최적화)
  - 포트: `3000`
  - 환경: 최적화된 빌드

### 운영 환경 특징

- ✅ **최적화된 빌드**: 프로덕션용 이미지
- ✅ **보안 강화**: 운영 환경 설정
- ✅ **성능 최적화**: 이미지 크기 최소화
- ✅ **안정성**: 프로덕션 모드

---

## 📁 프로젝트 구조

```
ERP-node/
├── 🔧 개발용 (Mac)
│   ├── start-all-parallel.sh          # 병렬 시작 (추천)
│   ├── start-backend.sh               # 백엔드만
│   ├── start-frontend.sh              # 프론트엔드만
│   ├── docker-compose.backend.mac.yml # Mac 개발용 백엔드
│   └── docker-compose.frontend.mac.yml# Mac 개발용 프론트엔드
│
├── 🚀 운영용 (Linux)
│   ├── start-all-separated-linux.sh   # Linux 운영용
│   ├── start-backend-linux.sh         # 백엔드만 (Linux)
│   ├── start-frontend-linux.sh        # 프론트엔드만 (Linux)
│   ├── docker-compose.backend.prod.yml# 운영용 백엔드
│   └── docker-compose.frontend.prod.yml# 운영용 프론트엔드
│
├── 📁 백엔드
│   ├── backend-node/
│   │   ├── Dockerfile                 # 프로덕션용
│   │   └── Dockerfile.dev             # 개발용
│   └── src/, database/, package.json...
│
├── 📁 프론트엔드
│   ├── frontend/
│   │   ├── Dockerfile                 # 프로덕션용
│   │   └── Dockerfile.dev             # 개발용
│   └── app/, components/, hooks/...
│
└── 🗂️ 기타
    ├── db/00-create-roles.sh          # DB 초기화
    └── README.md, DOCKER.md...
```

---

## 🌐 접속 정보

### 개발 환경

- **프론트엔드**: http://localhost:3000
- **백엔드 API**: http://localhost:8080
- **전체 앱**: http://localhost:9771 (프록시 설정 시)

### 운영 환경

- **서버 IP에 따라 다름** (Linux 서버 설정 확인)

---

## 🛠️ 주요 명령어

### Docker 컨테이너 관리

```bash
# 실행 중인 컨테이너 확인
docker ps

# 모든 컨테이너 중지
docker stop $(docker ps -q)

# 사용하지 않는 컨테이너/이미지 정리
docker system prune -f
```

### 로그 확인

```bash
# 백엔드 로그
docker logs pms-backend-mac -f     # 개발용
docker logs pms-backend-prod -f    # 운영용

# 프론트엔드 로그
docker logs pms-frontend-mac -f    # 개발용
docker logs pms-frontend-prod -f   # 운영용
```

### 컨테이너 내부 접속

```bash
# 백엔드 컨테이너 접속
docker exec -it pms-backend-mac bash   # 개발용
docker exec -it pms-backend-prod bash  # 운영용

# 프론트엔드 컨테이너 접속
docker exec -it pms-frontend-mac sh    # 개발용
docker exec -it pms-frontend-prod sh   # 운영용
```

---

## 🚨 트러블슈팅

### 자주 발생하는 문제들

#### 1. 포트 충돌

```bash
# 포트 사용 중인 프로세스 확인
lsof -i :8080
lsof -i :3000

# 프로세스 종료
kill -9 <PID>
```

#### 2. Docker 빌드 오류

```bash
# Docker 캐시 클리어 후 재빌드
docker builder prune -f
./start-all-parallel.sh
```

#### 3. 볼륨 마운트 문제 (개발환경)

```bash
# Docker Desktop 설정에서 파일 공유 확인
# Docker Desktop > Settings > Resources > File Sharing
```

#### 4. 데이터베이스 연결 오류

```bash
# 데이터베이스 초기화
./db/00-create-roles.sh

# PostgreSQL 연결 확인
docker exec -it <db-container> psql -U postgres
```

### Warning 메시지들 (무시해도 됨)

```
WARN: the attribute `version` is obsolete
Network Error (일시적)
```

이런 메시지들은 Docker Compose 버전 차이로 발생하며, 기능에는 영향 없습니다.

---

## 📈 성능 최적화

### 개발 환경 최적화

- ✅ **병렬 빌드**: `start-all-parallel.sh` 사용
- ✅ **Docker 캐시**: `--no-cache` 제거됨
- ✅ **npm 최적화**: `--prefer-offline --no-audit` 적용

### 운영 환경 최적화

- ✅ **멀티 스테이지 빌드**: Dockerfile 최적화
- ✅ **이미지 크기 최소화**: Alpine Linux 기반
- ✅ **의존성 캐시**: 레이어 캐싱 활용

---

## 🔄 업데이트 가이드

### 개발 환경 업데이트

```bash
# 코드 변경 시 (Hot Reload 자동 반영)
# 별도 작업 불필요

# 의존성 변경 시
docker-compose -f docker-compose.backend.mac.yml up --build -d
```

### 운영 환경 업데이트

```bash
# 새로운 버전 배포
./start-all-separated-linux.sh
```

---

## 📞 지원

**문제 발생 시:**

1. 이 문서의 트러블슈팅 섹션 확인
2. Docker 로그 확인 (`docker logs <container-name>`)
3. 개발팀에 문의

**프로젝트 관련:**

- Node.js 백엔드: `backend-node/` 디렉토리
- Next.js 프론트엔드: `frontend/` 디렉토리
- 데이터베이스: PostgreSQL (JNDI 설정)

---

**버전**: 1.0.0  
**마지막 업데이트**: 2024년 12월 28일  
**작성자**: PLM 개발팀