fgtools/scripts

Scripts 가이드

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

빌드 스크립트

build.sh (Linux/macOS)

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

설치

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

사용법

# 기본 빌드 (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용 빌드 스크립트입니다.

설치

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

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

사용법

# 기본 빌드
.\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 캐시 문제가 자주 발생합니다:

# 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.

해결:

# 영구적 변경
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 배포판 내에서 실행하세요.