Jenkins 배포 중 마주한 에러들과 해결방법

Jenkins를 사용하면서 Pipeline을 구성할 때, 특히 Docker와 React/Flask 프로젝트를 배포할 때 다양한 에러를 만나게 됩니다. 아래는 실제 경험을 바탕으로 흔히 마주치는 에러와 해결 방법을 정리했습니다.

---

1️⃣ WorkflowScript: Undefined section "stage"

WorkflowScript: 6: Undefined section "stage" @ line 6, column 6.
        stage('Checkout') {
        ^

 

원인:

• Declarative Pipeline에서 stage 블록이 잘못된 위치에 있음
• pipeline { agent any ... } 블록 안에 있어야 함

해결 방법:

• Jenkinsfile 구조 확인

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/eunhwa99/ImageGallery.git'
            }
        }
        stage('Build') {
            steps {
                sh 'echo Build here'
            }
        }
    }
}

• stages 안에 stage를 작성해야 합니다.

---

2️⃣ docker-compose: command not found

.jenkins/workspace/pipeline@tmp/durable-70d771de/script.sh.copy: line 1: docker-compose: command not found

 

원인:

• Jenkins 에이전트(Master 또는 Slave)에 docker-compose가 설치되어 있지 않음
• 또는 PATH에 추가되지 않음

해결 방법:

• 서버에 Docker Compose 설치 확인

docker compose version

• 설치 후, Jenkins Pipeline에서 PATH 지정

environment {
    PATH = "/usr/local/bin:/usr/bin:$PATH"
}

• 최신 Docker Compose는 docker compose (space) 형식 사용, 구버전은 docker-compose (hyphen) 사용

---

3️⃣ /usr/local/bin/docker-compose: No such file or directory

sh: /usr/local/bin/docker-compose build: No such file or directory

원인:

• Jenkins 에이전트에서 지정한 경로에 docker-compose 바이너리가 없음
• Mac과 Linux 경로 차이, 혹은 Jenkins 도커 컨테이너 내에는 설치 안 됨

해결 방법:

• 컨테이너 내부에서 실행 시: Docker image에 docker-compose 포함
• Mac/Linux 환경에서는 which docker-compose 또는 which docker로 경로 확인 후 PATH 지정

2. PATH
   • 시스템에서 명령어를 찾는 경로 목록 (명령어를 실행할 때 운영체제가 어디서 실행 파일을 찾을지 알려주는 “검색 경로 목록”)
   • 예: docker, docker-compose, python 등의 실행 파일 위치를 검색
3. "/usr/local/bin:/opt/homebrew/bin:$PATH"
   • :로 구분된 디렉토리 목록
   • 의미:
     • /usr/local/bin → 먼저 검색
     • /opt/homebrew/bin → 그 다음 검색
     • $PATH → 기존 시스템 PATH도 포함
   • 즉, Jenkins가 명령어를 찾을 때 이 순서대로 탐색함

---

4️⃣ failed to calculate checksum of ref "/requirements.txt": not found

target backend: failed to solve: failed to compute cache key: failed to calculate checksum of ref y3v0ir13r3lqtuu8b2ztv72x8::fdnhx8hqtbl783yfswk6fl1bl: "/requirements.txt": not found

 

원인:

• Dockerfile에서 COPY requirements.txt .를 했는데, 실제로 Docker build context에 파일이 없음
• requirements.txt 경로가 Dockerfile 위치와 다름

해결 방법:

• Dockerfile에서 경로를 정확히 지정

COPY app/requirements.txt .
COPY app/ .

• Docker build 명령어 위치 기준으로 COPY 경로 수정

---

5️⃣ no configuration file provided: not found

+ docker compose build
no configuration file provided: not found

원인:

• Jenkins workspace에 docker-compose.yml 파일이 없거나
• 현재 디렉토리에서 찾지 못함

해결 방법:

1. SCM 체크아웃 확인

stage('Checkout') {
    steps {
        git branch: 'main', url: 'https://github.com/eunhwa99/ImageGallery.git'
    }
}

2. docker-compose.yml 위치 지정

dir('backend') {
    sh 'docker compose build'
    sh 'docker compose up -d'
}

3. 또는 -f 옵션 사용

docker compose -f backend/docker-compose.yml build

---

🔹 추가 팁

• Jenkins Master에서 직접 빌드하지 말고 별도 Agent 사용 → 보안성 확보
• Docker Compose 빌드 시 --no-cache 옵션 사용 → 캐시 문제 방지
• Pipeline에서 deleteDir()로 workspace 초기화 → 이전 빌드 아티팩트 제거