본문으로 건너뛰기

수동 빌드

Auto CI를 사용하지 않고 직접 빌드를 설정하고 실행하고 싶으신가요? 수동 빌드를 사용하면 빌드 과정을 완전히 제어할 수 있습니다. 특정 브랜치나 커밋으로 빌드하거나, 배포 전에 테스트용 이미지를 만들 때 유용합니다.

수동 빌드는 언제 사용하나요?
  • Auto CI 설정 전에 빌드를 테스트해보고 싶을 때
  • 특정 브랜치나 커밋으로 임시 빌드가 필요할 때
  • 긴급 핫픽스를 바로 빌드하고 싶을 때
  • 빌드 설정을 변경한 후 검증하고 싶을 때

빌드 탭

빌드 개요​

KIWI는 Kaniko를 사용하여 컨테이너 이미지를 빌드합니다. Kaniko는 Docker 데몬 없이도 컨테이너 내에서 안전하게 이미지를 빌드할 수 있는 도구입니다.

Kaniko의 장점
  • 보안: Docker 데몬이 필요 없어 권한 상승 공격의 위험이 낮습니다.
  • K8s 친화적: Kubernetes Pod 내에서 직접 빌드 가능합니다.
  • 캐싱 지원: 레이어 캐시로 빌드 시간을 단축합니다.

지원하는 레지스트리:

  • Harbor (권장)
  • Docker Hub
  • 사설 Docker Registry

빌드 설정하기​

Step 1: 서비스 상세 페이지로 이동​

  1. [서비스 관리] 페이지로 이동합니다.
  2. 빌드할 서비스 카드를 클릭하여 상세 페이지로 이동합니다.

Step 2: Build 단계 클릭​

  1. 파이프라인에서 Build 단계를 클릭합니다.
  2. 빌드 설정 모달이 열립니다.

Step 3: Dockerfile 설정​

Dockerfile을 지정하는 세 가지 방법이 있습니다:

  • 자동 감지: 저장소에서 Dockerfile을 자동으로 탐지합니다. 표준 구조의 프로젝트에 적합합니다.
  • 경로 지정: Dockerfile 경로를 직접 입력합니다. 다중 Dockerfile이 있거나 비표준 위치에 있는 경우 사용합니다.
  • Build Wizard: Dockerfile이 없으면 자동으로 생성합니다. Dockerfile이 없는 프로젝트에 적합합니다.

Dockerfile 경로 예시:

./Dockerfile                    # 루트의 기본 Dockerfile (가장 일반적)
./docker/Dockerfile.prod        # 특정 환경용 Dockerfile
./services/api/Dockerfile       # 모노레포의 서비스별 Dockerfile
모범 사례

프로젝트 루트에 Dockerfile을 두는 것이 가장 일반적이고 권장됩니다. 특별한 이유가 없다면 자동 감지를 사용하세요.

Step 4: 빌드 인자 설정 (선택사항)​

고급 사용자를 위한 추가 설정입니다. 기본값으로도 대부분의 프로젝트가 빌드됩니다.

  • 빌드 경로: 빌드 시 사용할 파일들이 있는 폴더입니다 (기본: .)
  • 빌드 인자(ARG): Dockerfile의 ARG 값 전달 (예: NODE_ENV=production)
  • 타겟 스테이지: 멀티스테이지 빌드에서 특정 단계만 빌드 (예: production)
빌드 인자란?

Dockerfile에서 ARG 명령어로 정의된 변수에 값을 전달합니다. 예를 들어, ARG NODE_ENV가 있는 Dockerfile에 NODE_ENV=production을 전달하면 프로덕션 모드로 빌드됩니다.

Step 5: 이미지 레지스트리 설정​

빌드된 이미지가 저장될 레지스트리 정보를 입력합니다:

  • 레지스트리 URL: 이미지 저장소 주소 (예: harbor.company.com)
  • 프로젝트: 이미지 저장 위치(프로젝트명) (예: library, my-team)
  • 이미지 이름: 이미지 이름 (예: my-web-app)
  • 태그 규칙: 버전 태깅 방식 (예: ${BRANCH}-${SHORT_SHA})
태그 규칙 이해하기
  • ${BRANCH}: 빌드 브랜치명 (예: main, develop)
  • ${SHORT_SHA}: 커밋 해시 앞 7자리 (예: a1b2c3d)
  • ${TIMESTAMP}: 빌드 시간 (예: 20240115-123456)

예: ${BRANCH}-${SHORT_SHA} → main-a1b2c3d

Step 6: 설정 저장​

  1. 저장 버튼을 클릭합니다.
  2. "빌드 설정이 저장되었습니다" 메시지를 확인합니다.

빌드 실행하기​

설정을 완료했다면 이제 실제로 빌드를 실행해 봅시다.

Step 1: 빌드할 브랜치 선택​

  1. 서비스 상세 페이지에서 Build 단계를 클릭합니다.
  2. 브랜치 선택 드롭다운에서 빌드할 브랜치를 선택합니다.
브랜치 확인

잘못된 브랜치를 빌드하면 의도치 않은 코드가 배포될 수 있습니다. 빌드 전 브랜치를 다시 한번 확인하세요.

Step 2: 빌드 시작​

  1. 빌드 시작 버튼을 클릭합니다.
  2. 빌드가 큐에 등록되고 순서대로 실행됩니다.

Step 3: 빌드 로그 확인​

실시간으로 빌드 진행 상황을 확인할 수 있습니다:

[1/5] Cloning repository...
[2/5] Parsing Dockerfile...
[3/5] Building layers...
   → Building layer 1: FROM node:20-alpine
   → Building layer 2: COPY package*.json
   → Building layer 3: RUN npm ci
   → Building layer 4: COPY . .
   → Building layer 5: RUN npm run build
[4/5] Pushing to registry...
[5/5] Build completed successfully!
로그 활용하기

빌드 실패 시 로그에서 어느 단계에서 오류가 발생했는지 확인하세요. 대부분의 오류는 Building layers 단계에서 발생하며, 의존성 설치 실패나 빌드 스크립트 오류가 원인입니다.

Step 4: 빌드 완료 확인​

빌드가 완료되면 다음 정보를 확인할 수 있습니다:

  • 빌드 상태: 성공 또는 실패
  • 이미지 태그: 생성된 이미지의 전체 경로
  • 이미지 크기: 빌드된 이미지 용량
  • 빌드 소요 시간: 빌드 시작부터 완료까지 시간

빌드 최적화​

빌드 시간을 단축하고 이미지 크기를 줄이는 방법을 알아봅니다.

캐시 활용으로 빌드 속도 향상​

KIWI는 두 가지 캐시를 활용하여 빌드 속도를 최적화합니다:

  • 레이어 캐시: 변경이 없는 Docker 레이어를 재사용합니다. 의존성 설치 시간을 대폭 단축하는 효과가 있습니다.
  • 레지스트리 캐시: 기존 이미지 레이어를 활용합니다. 네트워크 전송량을 감소시키는 효과가 있습니다.
첫 빌드 vs 이후 빌드

첫 빌드는 모든 레이어를 새로 생성해야 하므로 오래 걸립니다. 두 번째 빌드부터는 캐시를 활용하여 빠르게 완료됩니다. 소스 코드만 변경된 경우, 의존성 설치 단계는 캐시에서 가져옵니다.

Dockerfile 최적화 팁​

빌드 캐시를 효과적으로 활용하려면 Dockerfile 작성 순서가 중요합니다.

1. 변경이 적은 레이어를 앞에 배치

# 좋은 예 - 의존성 먼저, 소스 코드는 나중에
COPY package*.json ./
RUN npm ci
COPY . .

# 나쁜 예 - 소스 코드 변경 시 의존성도 다시 설치
COPY . .
RUN npm ci

2. 멀티스테이지 빌드로 이미지 크기 최소화

# 빌드 단계: 빌드 도구 포함 (큰 이미지)
FROM node:20 AS builder
WORKDIR /app
COPY . .
RUN npm ci && npm run build

# 프로덕션 단계: 실행에 필요한 것만 (작은 이미지)
FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/main.js"]

3. .dockerignore로 불필요한 파일 제외

node_modules
.git
.env
*.log
.DS_Store
.dockerignore가 없으면

node_modules나 .git 폴더가 이미지에 포함되어 빌드 시간이 길어지고 이미지 크기가 커집니다. 반드시 .dockerignore 파일을 작성하세요.

빌드 이력​

과거 빌드 기록을 조회하고 관리할 수 있습니다.

이력 조회 방법​

  1. 서비스 상세 페이지의 Build 단계를 클릭합니다.
  2. 빌드 이력 탭을 선택합니다.

이력에서 확인할 수 있는 정보​

  • 빌드 번호: 순차적으로 부여된 빌드 식별 번호
  • 브랜치: 빌드에 사용된 Git 브랜치
  • 커밋: 빌드 시점의 커밋 해시 (클릭 시 GitLab으로 이동)
  • 상태: 성공 / 실패 / 진행중 / 취소됨
  • 소요 시간: 빌드에 걸린 시간
  • 이미지 태그: 생성된 이미지의 전체 태그
빌드 이력 활용

실패한 빌드의 로그를 확인하여 문제를 파악하거나, 성공한 빌드의 이미지 태그를 복사하여 배포에 사용할 수 있습니다.

문제 해결​

빌드 중 자주 발생하는 문제와 해결 방법입니다.

Dockerfile을 찾을 수 없음​

  • 경로 오류: 빌드 설정에서 Dockerfile 경로가 정확한지 확인합니다.
  • 파일명 대소문자: Dockerfile이 정확한 대소문자인지 확인합니다 (dockerfile은 인식되지 않음)
  • Git 권한 부족: GitLab 토큰에 read_repository 권한이 있는지 확인합니다.

빌드 실패​

  • npm ERR!: 의존성 설치 실패입니다. package.json과 package-lock.json을 확인하세요.
  • COPY failed: 파일 경로 오류입니다. 경로를 확인하고 .dockerignore를 검토하세요.
  • Permission denied: 파일 권한 문제입니다. 파일 권한을 수정하거나 RUN chmod를 추가하세요.
  • Out of memory: 메모리 부족입니다. 관리자에게 빌드 Pod 리소스 증가를 요청하세요.

이미지 푸시 실패​

  • 인증 실패: 서비스 설정에서 Registry 자격증명(사용자명/비밀번호)을 재확인합니다.
  • 권한 부족: Registry 프로젝트에 쓰기 권한이 있는지 확인합니다.
  • 용량 초과: 멀티스테이지 빌드로 이미지 크기를 최적화합니다.
해결되지 않는 문제

위 방법으로 해결되지 않으면 빌드 로그 전체를 확인하고, 필요시 관리자에게 문의하세요.

관련 가이드​