fix: docker-compose 빌드 오류 해결 가이드 및 자동화 스크립트 추가

- WSL2 Ubuntu에서 'image already exists' 오류 해결 문서 추가
- Linux/macOS용 build.sh 스크립트 추가 (BuildKit 비활성화)
- Windows PowerShell용 build.ps1 스크립트 추가
- 빌드 오류 트러블슈팅 가이드 추가
- docker-compose.yml에 빌드 오류 관련 주석 추가
- MODULES.md에 Docker 빌드 오류 해결 섹션 추가
This commit is contained in:
2025-12-31 11:48:29 +09:00
parent 53326703ab
commit f41599eef6
6 changed files with 591 additions and 0 deletions

View File

@ -230,6 +230,31 @@ $env:DB_USER
$env:DB_NAME
```
### Docker 빌드 오류 ("image already exists")
```powershell
# WSL2 Ubuntu 환경에서 발생하는 오류 해결:
# 방법 1: BuildKit 비활성화 (권장)
$env:DOCKER_BUILDKIT=0
docker compose build
# 방법 2: 캐시 무시하고 빌드
docker compose build --no-cache
# 방법 3: 이전 이미지 삭제
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker compose build
# 방법 4: BuildKit 캐시 정리
docker buildx prune -a
# 방법 5: 완전 초기화 후 빌드
docker compose down
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker buildx prune -a
docker compose build
```
## 추가 정보
- [전체 프로젝트 구조](README.md)

View File

@ -279,6 +279,103 @@ docker compose push
docker compose build && docker compose push
```
### 9. 빌드 오류 해결
#### 오류: "image already exists"
```bash
# 증상
# > [weather-api] exporting to image:
# [+] build 0/1
# target weather-api: failed to solve: image "reg.firstgarden.co.kr/fgtools:latest": already exists
# 해결 방법 1: BuildKit 비활성화 (권장)
DOCKER_BUILDKIT=0 docker compose build
# 해결 방법 2: 캐시 무시하고 빌드
docker compose build --no-cache
# 해결 방법 3: 이전 이미지 삭제 후 빌드
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker compose build
# 해결 방법 4: 완전 초기화
docker compose down
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker buildx prune -a
docker compose build
# 해결 방법 5: 빌드 스크립트 사용 (권장)
# Linux/macOS
chmod +x scripts/build.sh
./scripts/build.sh clean # 또는 ./scripts/build.sh force
# Windows PowerShell
.\scripts\build.ps1 -Clean # 또는 .\scripts\build.ps1 -Force
```
#### 빌드 스크립트 사용
자동화된 빌드 스크립트를 제공합니다:
**Linux/macOS:**
```bash
chmod +x scripts/build.sh
# 기본 빌드 (BuildKit 비활성화)
./scripts/build.sh
# 캐시 무시하고 빌드
./scripts/build.sh clean
# 완전 초기화 후 빌드
./scripts/build.sh force
# 빌드 및 사설 레지스트리에 푸시
./scripts/build.sh push
```
**Windows PowerShell:**
```powershell
# 첫 실행 시 실행 정책 설정
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 기본 빌드
.\scripts\build.ps1
# 캐시 무시하고 빌드
.\scripts\build.ps1 -Clean
# 완전 초기화 후 빌드
.\scripts\build.ps1 -Force
# 빌드 및 푸시
.\scripts\build.ps1 -Push
```
#### WSL2 Ubuntu에서 권장 방법
```bash
# WSL2 우분투에서 BuildKit 문제가 자주 발생합니다.
# 다음 방법들을 순서대로 시도하세요:
# 1단계: BuildKit 비활성화로 빌드
DOCKER_BUILDKIT=0 docker compose build
# 실패하면:
# 2단계: 캐시 무시하고 빌드
DOCKER_BUILDKIT=0 docker compose build --no-cache
# 여전히 실패하면:
# 3단계: 완전 초기화
docker compose down
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker buildx prune -a
DOCKER_BUILDKIT=0 docker compose build
# 또는 제공된 빌드 스크립트 사용:
chmod +x scripts/build.sh
./scripts/build.sh force
```
## 📖 API 문서
### Dashboard API (포트 5000)

View File

@ -9,6 +9,11 @@
# 실행: docker compose up -d
# 중지: docker compose down
# 로그: docker compose logs -f
#
# 빌드 오류 시 (image already exists):
# - docker compose build --no-cache
# - docker rmi reg.firstgarden.co.kr/fgtools:latest
# - DOCKER_BUILDKIT=0 docker compose build (WSL2에서 권장)
# ###################################################################
x-common: &common

165
scripts/README.md Normal file
View File

@ -0,0 +1,165 @@
# 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 배포판 내에서 실행하세요.

162
scripts/build.ps1 Normal file
View File

@ -0,0 +1,162 @@
# ###################################################################
# build.ps1 - FGTools Docker 이미지 빌드 스크립트 (PowerShell)
# ###################################################################
# 용도: Windows/WSL2에서 docker-compose build 오류 해결
#
# 사용법:
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# .\scripts\build.ps1 # 기본 빌드
# .\scripts\build.ps1 -Clean # 캐시 무시하고 빌드
# .\scripts\build.ps1 -Force # 완전 초기화 후 빌드
# .\scripts\build.ps1 -Push # 빌드 및 푸시
# ###################################################################
param(
[switch]$Clean = $false,
[switch]$Force = $false,
[switch]$Push = $false,
[switch]$Help = $false
)
# 설정
$REGISTRY = "reg.firstgarden.co.kr"
$IMAGE_NAME = "fgtools:latest"
$FULL_IMAGE = "$REGISTRY/$IMAGE_NAME"
# 함수: 메시지 출력
function Write-Log {
param([string]$Message)
Write-Host "[FGTools Build] $Message" -ForegroundColor Green
}
function Write-Error-Custom {
param([string]$Message)
Write-Host "[FGTools Build ERROR] $Message" -ForegroundColor Red
}
function Write-Warn {
param([string]$Message)
Write-Host "[FGTools Build WARN] $Message" -ForegroundColor Yellow
}
# 함수: 기본 빌드
function Build-Normal {
Write-Log "도커 이미지 빌드 시작 (일반 모드)..."
$env:DOCKER_BUILDKIT = 0
docker compose build
if ($LASTEXITCODE -eq 0) {
Write-Log "✓ 빌드 완료: $FULL_IMAGE"
} else {
Write-Error-Custom "빌드 실패"
exit 1
}
}
# 함수: 캐시 무시 빌드
function Build-Clean {
Write-Log "도커 이미지 빌드 시작 (캐시 무시)..."
docker compose build --no-cache
if ($LASTEXITCODE -eq 0) {
Write-Log "✓ 빌드 완료: $FULL_IMAGE"
} else {
Write-Error-Custom "빌드 실패"
exit 1
}
}
# 함수: 강제 초기화 후 빌드
function Build-Force {
Write-Log "완전 초기화 모드 시작..."
Write-Warn "서비스 중지 중..."
docker compose down 2>$null
Write-Warn "이전 이미지 삭제 중..."
docker rmi $FULL_IMAGE 2>$null
Write-Warn "BuildKit 캐시 정리 중..."
docker buildx prune -a --force 2>$null
Write-Log "도커 이미지 빌드 시작..."
$env:DOCKER_BUILDKIT = 0
docker compose build
if ($LASTEXITCODE -eq 0) {
Write-Log "✓ 빌드 완료: $FULL_IMAGE"
} else {
Write-Error-Custom "빌드 실패"
exit 1
}
}
# 함수: 빌드 및 푸시
function Build-And-Push {
Write-Log "도커 이미지 빌드 및 푸시 시작..."
$env:DOCKER_BUILDKIT = 0
docker compose build
if ($LASTEXITCODE -ne 0) {
Write-Error-Custom "빌드 실패"
exit 1
}
Write-Log "이미지 푸시 중..."
docker compose push
if ($LASTEXITCODE -eq 0) {
Write-Log "✓ 빌드 및 푸시 완료: $FULL_IMAGE"
} else {
Write-Error-Custom "푸시 실패"
exit 1
}
}
# 함수: 사용법 출력
function Show-Usage {
$usage = @"
FGTools Docker
:
.\scripts\build.ps1 #
.\scripts\build.ps1 -Clean #
.\scripts\build.ps1 -Force #
.\scripts\build.ps1 -Push #
.\scripts\build.ps1 -Help #
:
-Clean
-Force ()
-Push
-Help
:
WSL2 "image already exists" :
1. clean : .\scripts\build.ps1 -Clean
2. force : .\scripts\build.ps1 -Force
3. : docker system prune -a
:
:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
"@
Write-Host $usage
}
# 메인 로직
if ($Help) {
Show-Usage
exit 0
}
if ($Force) {
Build-Force
} elseif ($Clean) {
Build-Clean
} elseif ($Push) {
Build-And-Push
} else {
Build-Normal
}
Write-Log "완료!"

137
scripts/build.sh Normal file
View File

@ -0,0 +1,137 @@
#!/bin/bash
# ###################################################################
# build.sh - FGTools Docker 이미지 빌드 스크립트
# ###################################################################
# 용도: WSL2 Ubuntu에서 docker-compose build 오류 해결
#
# 사용법:
# chmod +x scripts/build.sh
# ./scripts/build.sh # 기본 빌드
# ./scripts/build.sh clean # 캐시 무시하고 빌드
# ./scripts/build.sh force # 완전 초기화 후 빌드
# ./scripts/build.sh push # 빌드 및 푸시
# ###################################################################
set -e
REGISTRY="reg.firstgarden.co.kr"
IMAGE_NAME="fgtools:latest"
FULL_IMAGE="$REGISTRY/$IMAGE_NAME"
# 색상 정의
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# 함수: 메시지 출력
log() {
echo -e "${GREEN}[FGTools Build]${NC} $1"
}
error() {
echo -e "${RED}[FGTools Build ERROR]${NC} $1"
}
warn() {
echo -e "${YELLOW}[FGTools Build WARN]${NC} $1"
}
# 함수: 기본 빌드
build_normal() {
log "도커 이미지 빌드 시작 (일반 모드)..."
export DOCKER_BUILDKIT=0
docker compose build
log "✓ 빌드 완료: $FULL_IMAGE"
}
# 함수: 캐시 무시 빌드
build_clean() {
log "도커 이미지 빌드 시작 (캐시 무시)..."
docker compose build --no-cache
log "✓ 빌드 완료: $FULL_IMAGE"
}
# 함수: 강제 초기화 후 빌드
build_force() {
log "완전 초기화 모드 시작..."
warn "서비스 중지 중..."
docker compose down || true
warn "이전 이미지 삭제 중..."
docker rmi "$FULL_IMAGE" || true
warn "BuildKit 캐시 정리 중..."
docker buildx prune -a --force || true
log "도커 이미지 빌드 시작..."
export DOCKER_BUILDKIT=0
docker compose build
log "✓ 빌드 완료: $FULL_IMAGE"
}
# 함수: 빌드 및 푸시
build_and_push() {
log "도커 이미지 빌드 및 푸시 시작..."
export DOCKER_BUILDKIT=0
docker compose build
log "이미지 푸시 중..."
docker compose push
log "✓ 빌드 및 푸시 완료: $FULL_IMAGE"
}
# 함수: 사용법 출력
usage() {
cat << EOF
사용법: ./scripts/build.sh [옵션]
옵션:
(기본값) 일반 빌드 (BuildKit 비활성화)
clean 캐시를 무시하고 빌드
force 완전 초기화 후 빌드 (강력함)
push 빌드 및 사설 레지스트리에 푸시
예시:
./scripts/build.sh # 기본 빌드
./scripts/build.sh clean # 캐시 제거 후 빌드
./scripts/build.sh force # 완전 초기화
./scripts/build.sh push # 빌드 및 푸시
트러블슈팅:
WSL2에서 "image already exists" 오류 발생 시:
1. 먼저 clean 모드 시도: ./scripts/build.sh clean
2. 실패 시 force 모드 시도: ./scripts/build.sh force
3. 계속 실패하면: docker system prune -a
EOF
}
# 메인 로직
case "${1:-default}" in
default)
build_normal
;;
clean)
build_clean
;;
force)
build_force
;;
push)
build_and_push
;;
help|--help|-h)
usage
;;
*)
error "알 수 없는 옵션: $1"
usage
exit 1
;;
esac
log "완료!"