KWON
f41599eef6
- WSL2 Ubuntu에서 'image already exists' 오류 해결 문서 추가 - Linux/macOS용 build.sh 스크립트 추가 (BuildKit 비활성화) - Windows PowerShell용 build.ps1 스크립트 추가 - 빌드 오류 트러블슈팅 가이드 추가 - docker-compose.yml에 빌드 오류 관련 주석 추가 - MODULES.md에 Docker 빌드 오류 해결 섹션 추가
166 lines
3.7 KiB
Markdown
166 lines
3.7 KiB
Markdown
# 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 배포판 내에서 실행하세요.
|