sam-docs/WSL_MIGRATION_PLAN.md

# WSL 내부 Docker 환경 마이그레이션 계획

## 1. 현재 구조 (문제점)

```
┌─ Windows 11 (NTFS) ─────────────────────────────────────┐
│  C:/work/@KD_SAM/SAM/                                    │
│  ├── api/     (406MB)   소스코드                          │
│  ├── react/   (649MB)   소스 20MB + node_modules 629MB   │
│  ├── mng/     (89MB)    소스코드                          │
│  ├── 5130/    (799MB)   레거시                            │
│  ├── docker/  (237MB)   Docker 설정 + SSL                │
│  └── docs/    (57MB)    문서                              │
│                                                           │
│  ──── 9P 프로토콜 (느림) ────                              │
│                                                           │
│  ┌─ Docker Desktop (WSL2 backend) ──────────────────┐    │
│  │  nginx, api, react, mng, legacy, mysql            │    │
│  │  바인드 마운트가 Windows NTFS 경유 → 느림          │    │
│  │                                                    │    │
│  │  extra_hosts: api.sam.kr → host-gateway            │    │
│  │  → React SSR API 호출이 Docker 밖으로 나감          │    │
│  └────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────────┘
```

### 병목 3가지

| # | 병목 | 원인 | 영향 |
|---|------|------|------|
| 1 | **파일 I/O 느림** | Windows NTFS → WSL2 ext4 간 9P 프로토콜 | HMR 3~5초, npm install 수분 |
| 2 | **API 호출 우회** | extra_hosts로 Docker→WSL호스트→Docker 왕복 | API 호출마다 +10~20ms |
| 3 | **파일 감시 폴링** | inotify 불가 → 3초 폴링 | 코드 변경 반영 3초 지연 |

### 현재 시스템 사양

| 항목 | 값 |
|------|-----|
| RAM | 32GB |
| CPU | 20 논리 코어 |
| .wslconfig | 없음 (기본값) |
| WSL 배포판 | docker-desktop만 있음 |
| Docker | Docker Desktop (WSL2 backend) |

### 현재 DB 크기

| DB | 크기 |
|----|------|
| samdb | 177 MB |
| sam | 25 MB |
| chandj | 21 MB |
| 기타 (backup 등) | ~20 MB |
| **합계** | **~250 MB** |

### 현재 실행 중 컨테이너

| 컨테이너 | 상태 |
|----------|------|
| nginx | Running (26h) |
| mysql | Running (25h) |
| api | Running (19h) |
| mng | Running (26h) |
| legacy | Running (26h) |
| react | **Not Running** |
| phpmyadmin | **Not Running** |

---

## 2. 목표 구조

```
┌─ WSL2 Ubuntu 24.04 (ext4 네이티브) ─────────────────────┐
│                                                           │
│  ~/sam/                                                   │
│  ├── api/     ← git clone (네이티브 ext4)                 │
│  ├── react/   ← git clone (네이티브 ext4)                 │
│  ├── mng/     ← git clone (네이티브 ext4)                 │
│  ├── 5130/    ← 파일 복사 (git 없으면)                    │
│  ├── docker/  ← 복사 + 수정                               │
│  └── docs/    ← 복사                                      │
│                                                           │
│  ┌─ Docker Engine (WSL 네이티브) ───────────────────┐    │
│  │  바인드 마운트 = 같은 ext4 → 네이티브 속도         │    │
│  │                                                    │    │
│  │  서비스 간 통신: Docker 내부 DNS 직접 연결          │    │
│  │  → extra_hosts 불필요                              │    │
│  │  → 파일 폴링 불필요 (inotify 정상 작동)            │    │
│  └────────────────────────────────────────────────────┘    │
│                                                           │
│  Windows에서 접근: \\wsl$\Ubuntu-24.04\home\user\sam      │
│  VSCode: Remote WSL 확장으로 편집                          │
│                                                           │
└───────────────────────────────────────────────────────────┘
```

### 개선 효과 예상

| 항목 | 현재 | 목표 | 개선폭 |
|------|------|------|--------|
| 파일 I/O | 9P (느림) | ext4 네이티브 | **5~10배** |
| Next.js HMR | 3~5초 | 0.3~1초 | **3~5배** |
| npm install | 3~5분 | 30초~1분 | **3~5배** |
| API 내부 호출 | Docker→WSL→Docker | Docker 내부 직접 | **2~3배** |
| 파일 감시 | 3초 폴링 | inotify 즉시 | **즉시 반영** |

---

## 3. 마이그레이션 단계

### Phase 1: WSL Ubuntu 설치 + 기본 설정 (10분)

```bash
# 1-1. Ubuntu 24.04 설치
wsl --install -d Ubuntu-24.04

# 1-2. 초기 설정 (Ubuntu 내부)
sudo apt update && sudo apt upgrade -y

# 1-3. 기본 도구 설치
sudo apt install -y git curl wget unzip
```

### Phase 2: Docker Engine 설치 (10분)

> Docker Desktop 대신 WSL 내부에 Docker Engine 직접 설치

```bash
# 2-1. Docker 공식 GPG 키 + 저장소 추가
sudo apt install -y ca-certificates gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 2-2. Docker Engine 설치
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 2-3. 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER

# 2-4. Docker 시작
sudo service docker start
```

### Phase 3: .wslconfig 설정 (2분)

> Windows 측에서 WSL 리소스 할당

**파일**: `C:\Users\codeb\.wslconfig`

```ini
[wsl2]
memory=12GB
processors=8
swap=4GB
localhostForwarding=true
```

> 32GB RAM 중 12GB 할당 (Docker + 6개 컨테이너 충분)

### Phase 4: 소스코드 가져오기 (10~15분)

```bash
# 4-1. 디렉토리 구조 생성
mkdir -p ~/sam

# 4-2. Git clone (소스코드만, vendor/node_modules 제외)
cd ~/sam
git clone http://114.203.209.83:3000/SamProject/sam-api.git api
git clone http://114.203.209.83:3000/SamProject/sam-react.git react
git clone http://114.203.209.83:3000/SamProject/sam-manage.git mng

# 4-3. 각 저장소 브랜치 맞추기
cd ~/sam/api && git checkout develop
cd ~/sam/mng && git checkout sam-kkk

# 4-4. Git 사용자 설정
git config --global user.name "강영보"
git config --global user.email "sam-kkk@codebridge-x.com"

# 4-5. 레거시(5130) - Git 저장소가 없으면 Windows에서 복사
cp -r /mnt/c/work/@KD_SAM/SAM/5130 ~/sam/5130

# 4-6. Docker 설정 복사
cp -r /mnt/c/work/@KD_SAM/SAM/docker ~/sam/docker

# 4-7. 문서 복사
cp -r /mnt/c/work/@KD_SAM/SAM/docs ~/sam/docs

# 4-8. .env 파일 복사 (git에 포함 안 된 경우)
cp /mnt/c/work/@KD_SAM/SAM/api/.env ~/sam/api/.env
cp /mnt/c/work/@KD_SAM/SAM/react/.env ~/sam/react/.env
cp /mnt/c/work/@KD_SAM/SAM/mng/.env ~/sam/mng/.env
cp /mnt/c/work/@KD_SAM/SAM/5130/.env ~/sam/5130/.env 2>/dev/null
```

### Phase 5: Docker 설정 수정 (5분)

#### 5-1. docker-compose.yml 수정

**변경사항**:

| 항목 | 변경 전 | 변경 후 | 이유 |
|------|---------|---------|------|
| extra_hosts | `api.sam.kr:host-gateway` | **제거** | Docker 내부 DNS로 충분 |
| WATCHPACK_POLLING | `3000` | **제거** | ext4에서 inotify 정상 작동 |
| CHOKIDAR_USEPOLLING | `true` | **제거** | 폴링 불필요 |
| CHOKIDAR_INTERVAL | `3000` | **제거** | 폴링 불필요 |

#### 5-2. React 환경변수 수정 (SSR 내부 통신 최적화)

```yaml
react:
  environment:
    - NEXT_PUBLIC_API_URL=https://api.sam.kr       # 브라우저용 (유지)
    - API_URL_INTERNAL=http://api:9000             # SSR용 (추가)
    # 아래 3줄 제거
    # - WATCHPACK_POLLING=3000
    # - CHOKIDAR_USEPOLLING=true
    # - CHOKIDAR_INTERVAL=3000
  # extra_hosts 제거
```

#### 5-3. Windows hosts 파일 유지

**`C:\Windows\System32\drivers\etc\hosts`** (기존과 동일):
```
127.0.0.1  dev.sam.kr api.sam.kr mng.sam.kr admin.sam.kr 5130.sam.kr
```

> WSL2의 localhostForwarding=true 덕분에 Windows에서 localhost로 WSL 포트 접근 가능

### Phase 6: DB 마이그레이션 (5~10분)

```bash
# 6-1. Windows Docker에서 DB 덤프 (Windows 측에서 실행)
# PowerShell 또는 Git Bash에서:
docker exec docker-mysql-1 mysqldump -uroot -proot --all-databases --routines --triggers > /mnt/c/temp/sam_db_dump.sql

# 6-2. WSL Ubuntu에서 Docker 컨테이너 시작 (MySQL만 먼저)
cd ~/sam/docker
docker compose up -d mysql
# MySQL 초기화 대기 (약 30초)
sleep 30

# 6-3. DB 덤프 복원
docker exec -i $(docker compose ps -q mysql) mysql -uroot -proot < /mnt/c/temp/sam_db_dump.sql
```

### Phase 7: 전체 서비스 빌드 + 실행 (10~15분)

```bash
cd ~/sam/docker

# 7-1. 이미지 빌드
docker compose build

# 7-2. 전체 서비스 시작
docker compose up -d

# 7-3. 상태 확인
docker compose ps

# 7-4. 로그 확인
docker compose logs -f --tail=50
```

### Phase 8: 검증 (5분)

| # | 확인 항목 | 방법 |
|---|----------|------|
| 1 | 서비스 실행 상태 | `docker compose ps` - 모든 컨테이너 Up |
| 2 | Nginx 접근 | 브라우저에서 `https://dev.sam.kr` 열기 |
| 3 | API 응답 | `curl -k https://api.sam.kr/api/health` |
| 4 | 관리자 접근 | `https://admin.sam.kr` 열기 |
| 5 | DB 연결 | phpMyAdmin (`http://localhost:8080`) |
| 6 | HMR 작동 | React 소스 수정 → 즉시 반영 확인 |
| 7 | 파일 감시 | `WATCHPACK_POLLING` 없이 변경 감지 확인 |

### Phase 9: Docker Desktop 정리 (선택)

```bash
# 기존 Docker Desktop 컨테이너 중지 (Windows에서)
docker compose -f C:/work/@KD_SAM/SAM/docker/docker-compose.yml down

# Docker Desktop 비활성화 또는 제거 (선택)
# → WSL Ubuntu Docker와 충돌 방지
```

---

## 4. 주의사항

### 포트 충돌

| 포트 | 용도 | 주의 |
|------|------|------|
| 80/443 | Nginx | Docker Desktop 먼저 중지해야 함 |
| 3306 | MySQL | 동시에 2개 MySQL 불가 |
| 8080 | phpMyAdmin | 충돌 가능 |

> **반드시 기존 Docker Desktop 컨테이너를 먼저 중지** 후 WSL Docker 시작

### VSCode 편집 환경

```
기존: VSCode에서 C:/work/@KD_SAM/SAM/ 직접 편집
변경: VSCode Remote WSL 확장 사용
  - Ctrl+Shift+P → "WSL: Connect to WSL"
  - ~/sam/ 폴더 열기
  - 터미널도 WSL Ubuntu 내부에서 실행
```

### Git 작업 흐름

```
기존: Windows Git Bash에서 커밋/푸시
변경: WSL Ubuntu 터미널에서 커밋/푸시 (동일한 원격 저장소)
  - 또는 VSCode Remote WSL의 Git 기능 사용
```

### 백업/롤백 계획

```
Windows 원본 소스: C:/work/@KD_SAM/SAM/ (그대로 보존)
Windows Docker: 컨테이너 중지만 (삭제 안 함)
DB 덤프: C:/temp/sam_db_dump.sql (보존)

문제 시 롤백:
  1. WSL Docker 중지: docker compose down
  2. Windows Docker 재시작: docker compose up -d
  → 5분 이내 원복 가능
```

---

## 5. 일정 요약

| Phase | 작업 | 소요 시간 |
|-------|------|----------|
| 1 | Ubuntu 설치 + 기본 설정 | 10분 |
| 2 | Docker Engine 설치 | 10분 |
| 3 | .wslconfig 설정 | 2분 |
| 4 | 소스코드 가져오기 | 10~15분 |
| 5 | Docker 설정 수정 | 5분 |
| 6 | DB 마이그레이션 | 5~10분 |
| 7 | 빌드 + 실행 | 10~15분 |
| 8 | 검증 | 5분 |
| 9 | Docker Desktop 정리 | 3분 |
| **합계** | | **약 60~75분** |

> 롤백 가능하므로 리스크 낮음. Windows 원본은 그대로 보존.