[Claude 블로그 자동화] Jenkins로 Docker 자동 배포 파이프라인 구축하기 3편

코드 고칠 때마다 서버 들어가서 직접 배포하고 있다면.

이거 한번 생각해봐요.

git push 하나로 끝나면 어떨까요?

이전에 Hetzner 서버에 Jenkins 올리는 과정을 정리한 적이 있어요.

Docker 소켓 마운트, SSH 키 등록, Webhook 연결까지 전부 다뤘거든요.

→ Jenkins CI/CD 파이프라인 직접 구성해봤습니다 — Hetzner 실전 세팅 5편

Jenkins 자체가 처음이거나 설치부터 다시 보고 싶다면 위 글 먼저 보고 오는 걸 추천해요.

이번 글은 그 설정이 이미 돼있다는 전제에서, 이 프로젝트(web-scrap-note) 전용 파이프라인을 추가하는 과정만 다뤄요.

이전에 작성한 Python Flask 를 활용한 RSS 자동 수집기 만든 과정을 보시려면 아래 글에서 보시면 됩니다.

 

이전글 : [개발] - Python Flask + RSS 자동 수집 시스템 만들기 2편

---

전체 흐름 먼저 보기

GitHub에 코드 push
↓
GitHub Webhook → Jenkins 트리거
↓
Jenkinsfile 실행
  1. 코드 체크아웃
  2. Docker 이미지 빌드
  3. 컨테이너 재시작 (docker compose up)
  4. 헬스 체크
↓
배포 완료

[이미지 삽입] 키워드: "Jenkins CI/CD pipeline diagram" / 설명: GitHub push부터 Docker 배포까지 파이프라인 흐름을 보여주는 다이어그램

이게 전부예요. 단계별로 하나씩 만들어볼게요.

---

1단계 — Jenkinsfile 작성

프로젝트 루트에 Jenkinsfile 하나 만들어요.

이 파일이 파이프라인의 설계도예요.

이전 글의 Next.js / Spring Boot 구성과 다른 점이 있어요.

이쪽은 Python Flask 기반이라 Gradle 빌드 단계가 없고, 구조가 훨씬 단순해요.

pipeline {
    agent any

    environment {
        IMAGE_NAME = "web-scrap-note"
        CONTAINER_NAME = "web-scrap-note"
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build Image') {
            steps {
                sh "docker build -t ${IMAGE_NAME} ."
            }
        }

        stage('Deploy') {
            steps {
                sh """
                    docker compose stop ${CONTAINER_NAME} || true
                    docker compose rm -f ${CONTAINER_NAME} || true
                    docker compose up -d ${CONTAINER_NAME}
                """
            }
        }

        stage('Health Check') {
            steps {
                sh "sleep 5"
                sh "docker ps | grep ${CONTAINER_NAME}"
            }
        }
    }

    post {
        success {
            echo "배포 성공!"
        }
        failure {
            echo "배포 실패. 로그 확인 필요."
        }
    }
}

단계별로 뭐 하는지 보면,

Checkout — GitHub에서 코드 받아와요.
Build Image — Docker 이미지 새로 빌드해요.
Deploy — 기존 컨테이너 내리고, 새 이미지로 재시작해요.
Health Check — 컨테이너가 제대로 떴는지 확인해요.

---

2단계 — Jenkins Job 만들기

Jenkins 웹에서 새 Job을 추가해요.

이전 글에서 만든 Jenkins 환경에 파이프라인 하나를 더 얹는 거예요.

1. 새로운 Item 클릭
2. 이름 입력 (web-scrap-note) → Pipeline 선택
3. Pipeline 탭에서 Pipeline script from SCM 선택
4. SCM: Git, Repository URL에 GitHub 주소 입력
5. Credentials: 이전에 등록한 github-credentials 그대로 사용
6. Script Path: Jenkinsfile
7. 저장

Credentials는 새로 만들 필요 없어요.

이전 글에서 등록해둔 SSH 키가 Jenkins에 이미 있거든요.

---

3단계 — GitHub Webhook 연결

이번 프로젝트 레포에도 Webhook을 등록해야 해요.

GitHub 저장소에서 Settings → Webhooks → Add webhook으로 가요.

Payload URL: http://서버IP:8090/github-webhook/
Content type: application/json
Events: Just the push event

이전 글에서 다른 레포에 이미 달아봤으니까, 똑같이 하면 돼요.

등록 후 초록색 체크 뜨면 연결 완료예요.

webhook 등록

---

실제로 push해보면

git add .
git commit -m "update collector sources"
git push origin main

Jenkins 대시보드 보면 파이프라인이 돌아가는 게 보여요.

초록불 뜨면 성공이에요.

전체 소요 시간은 이미지 캐시 있으면 1~2분, 없으면 3~4분 정도예요.

---

근데 여기서 반전이 있어요

Jenkins를 처음 세팅할 때 가장 많이 막히는 게 권한 문제예요.

Docker 소켓 접근, GitHub 인증, 빌드 경로…

근데 이미 이전 프로젝트에서 한 번 다 겪었잖아요.

이번엔 그 고생이 없어요.

Job 하나 추가하고 Jenkinsfile만 맞게 써주면 그냥 돌아가거든요.

그게 Jenkins를 처음부터 제대로 세팅해두는 이유예요.

한 번 고생하면, 다음 프로젝트는 5분이에요.

---

여기까지 정리하면

기존 Jenkins 환경에 파이프라인 하나를 추가하는 것만으로 자동 배포가 붙었어요.

git push 한 번으로 서버 배포가 끝나는 구조가 완성됐어요.

다음 편에서는 nginx + certbot으로 도메인 연결하고 HTTPS까지 올려요.

지금은 http://서버IP:5000 으로 접속하고 있는데, 이걸 깔끔한 도메인 주소로 바꾸는 작업이에요.

결국 핵심은 이거예요.

배포는 한 번만 고민하면 된다. 그 이후엔 코드만 고민한다.