# Scripts 가이드

프로젝트의 각종 자동화 스크립트를 제공합니다.

## 빌드 스크립트

### build.sh (Linux/macOS)

Docker 이미지 빌드를 자동화하는 Bash 스크립트입니다. WSL2 Ubuntu에서 발생하는 "image already exists" 오류를 해결합니다.

#### 설치

```bash
# 실행 권한 부여
chmod +x scripts/build.sh
```

#### 사용법

```bash
# 기본 빌드 (BuildKit 비활성화)
./scripts/build.sh

# 캐시 무시하고 빌드
./scripts/build.sh clean

# 완전 초기화 후 빌드 (강력함)
./scripts/build.sh force

# 빌드 및 사설 레지스트리에 푸시
./scripts/build.sh push

# 도움말
./scripts/build.sh help
```

#### 옵션 설명

| 옵션 | 설명 | 사용 시점 |
|------|------|----------|
| (기본값) | BuildKit 비활성화로 빌드 | 일반적인 빌드 |
| `clean` | 캐시를 무시하고 빌드 | 의존성 변경 후 |
| `force` | 완전 초기화 후 빌드 | "image already exists" 오류 발생 |
| `push` | 빌드 및 사설 레지스트리 푸시 | 배포 시 |

### build.ps1 (Windows PowerShell)

PowerShell로 작성된 Windows용 빌드 스크립트입니다.

#### 설치

```powershell
# 실행 정책 변경 (처음 한 번만)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 또는 현재 세션에서만 실행 허용
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
```

#### 사용법

```powershell
# 기본 빌드
.\scripts\build.ps1

# 캐시 무시하고 빌드
.\scripts\build.ps1 -Clean

# 완전 초기화 후 빌드
.\scripts\build.ps1 -Force

# 빌드 및 푸시
.\scripts\build.ps1 -Push

# 도움말
.\scripts\build.ps1 -Help
```

## 빌드 오류 해결 흐름도

```
docker compose build 실행
    ↓
"image already exists" 오류 발생?
    ↓ YES
./scripts/build.sh clean  (또는 build.ps1 -Clean)
    ↓
성공?
    ↓ NO
./scripts/build.sh force  (또는 build.ps1 -Force)
    ↓
성공?
    ↓ NO
docker system prune -a
docker compose build
```

## 트러블슈팅

### WSL2 Ubuntu 특정 팁

WSL2의 Docker 환경에서 BuildKit 캐시 문제가 자주 발생합니다:

```bash
# 1. BuildKit 비활성화
export DOCKER_BUILDKIT=0
./scripts/build.sh

# 2. 또는 스크립트에서 자동으로 처리됨
./scripts/build.sh clean

# 3. 최후의 수단: 시스템 정리
docker system prune -a --volumes
./scripts/build.sh force
```

### Docker Desktop 설정 확인

Windows/macOS에서 Docker Desktop을 사용하는 경우:

1. Docker Desktop 설정 열기
2. "Resources" → "WSL integration" 확인
3. "Docker Engine" → "BuildKit" 활성화 확인
4. 필요시 다시 시작

### PowerShell 실행 정책 오류

```
File cannot be loaded because running scripts is disabled on this system.
```

해결:
```powershell
# 영구적 변경
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 현재 세션에서만
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

# 또는 -NoProfile 옵션으로 실행
powershell -NoProfile -ExecutionPolicy Bypass -File "scripts\build.ps1"
```

## 향후 추가 스크립트 (계획)

- `test.sh` - 모든 모듈 테스트 실행
- `deploy.sh` - 배포 자동화
- `cleanup.sh` - Docker 리소스 정리
- `setup.sh` - 개발 환경 초기화

## 지원 환경

| OS | Shell | 상태 |
|----|-------|------|
| Linux | bash | ✓ 지원 |
| macOS | bash | ✓ 지원 |
| WSL2 Ubuntu | bash | ✓ 지원 (권장) |
| Windows | PowerShell | ✓ 지원 |
| Windows | CMD | ✗ 미지원 |

## 참고

- 모든 스크립트는 프로젝트 루트 디렉토리에서 실행해야 합니다.
- 스크립트는 Docker 및 Docker Compose가 설치되어 있어야 합니다.
- WSL2에서 실행할 때는 WSL2 배포판 내에서 실행하세요.