[CI/CD] Docker와 Github Actions으로 CI/CD 파이프라인 구축하기

🧐 들어가기전

최근에 예전에 진행했던 프로젝트를 코프링(Kotlin + Spring) 기반으로 마이그레이션하는 작업을 시작하게 되었다.

 

당시에는 코드가 수정될 때마다 로컬에서 빌드한 파일을 서버에 수동으로 업로드하고 실행하는 방식으로 배포를 진행했었다.

하지만 이런 방식은 코드가 변경될 때마다 매번 수작업으로 빌드 파일을 옮겨야 하는 번거로움이 있었고, DB나 기타 환경 설정들도 서버에 직접 설치하고 구성해야 해서 불편함이 많았다.

 

그래서 이번에는 이런 불편을 줄이기 위해, Docker와 GitHub Actions를 활용해 코드 변경 시 자동으로 테스트 → 빌드 → 배포가 이루어지는 CI/CD 파이프라인을 구축해보고자 한다.

 

추가로, 무중단 배포까지 도전해보며 실무에 가까운 배포 환경을 경험해볼 계획이다.

---

🔸Docker + Github Actions CI/CD 파이프라인 이해하기

Docker와 Github Actions를 통한 CI/CD의 과정이 어떻게 진행하는지 동작 원리를 이해해보자.

1️⃣ on trigger

우선은 workflow에서 trigger를 걸어서 git에서 해당 동작이 일어났을 때 github actions가 실행되는 원리이다.

# event trigger
# main이나 develop 브랜치에 push가 되었을 때 실행 / main에 pr되면 실행
on:
  pull_request:
    branches:
      - main

  push:
    branches:
      - develop
      - main

  workflow_dispatch:

GitHub Actions에서 workflow를 어떤 이벤트에 반응해서 실행할지 정하는 부분이 바로 on: 트리거이다.

 

주요 트리거의 종류로는 다음과 같이 있다.

• pull_request : 조건을 걸어둔 브랜치에 pr이 일어났을 때 실행
• push : 조건을 걸어둔 브랜치에 push가 일어났을 때 실행
• workflow_dispatch: 수동 실행 버튼으로 워크플로우를 실행할 수 있게 함
• schedule: 정해진 시간마다 workflow 실행
• release: 릴리스를 생성/수정/삭제할 때 실행

---

2️⃣ CI의 flow

CI: Continuous Integration(지속적 통합)의 약자로, 개발자가 작성한 코드를 지속적으로 통합하면서 문제가 없는지 자동으로 검사하는 프로세스를 말한다.

 

CI의 과정은 크게 "자동화 테스트 실행" ->  "빌드"의 과정을 따른다.

🔹1. 자동화 테스트 실행

      # 테스트
      - name: Run tests
        run: ./gradlew test --no-daemon

gradle demon이란?:
Gradle은 기본적으로 빌드 속도를 빠르게 하기 위해 백그라운드에서 "데몬(daemon)" 프로세스를 띄워두고 이를 재사용한다. 즉, 한 번 빌드를 실행하면 다음 빌드부터는 메모리에 상주한 Gradle 데몬이 작업을 빠르게 처리할 수 있다.

하지만 CI의 환경에서는 demon을 꺼주는 것이 일반적이다.

1. 환경이 일회성이고 휘발성이기 때문
   → CI 환경은 실행 후 종료되기 때문에, 데몬을 띄워봤자 다시 재사용하지 못한다.
2. 메모리 절약 및 안정성
   → 데몬을 사용하면 메모리를 더 잡아먹고, 간혹 예기치 않은 에러나 캐싱 이슈가 생긴다.

🔹2. 빌드

      # gradle build, demon 사용 x
      - name: build
        run: ./gradlew build --no-daemon

 

빌드까지 완료하면 CI의 과정이 완료된다.

---

3️⃣ Docker 이미지 build & push

코드의 바뀐 내용을 어떻게 보낼 것인가?

 

코드가 바뀔 때마다 이를 서버에 반영하는 가장 효율적인 방법은, 코드를 Docker 이미지로 빌드한 뒤 Docker Hub에 업로드하는 것이다. 이렇게 이미지를 업로드해두면, 서버에서는 Docker Hub에 로그인한 후 해당 이미지를 pull해와서 곧바로 컨테이너로 실행시킬 수 있다.

 

# JDK 17 slim 이미지 사용
FROM openjdk:17-jdk-slim

# 작업 디렉토리 설정
WORKDIR /app

# 빌드된 JAR 복사
COPY build/libs/*.jar app.jar

# 실행 명령어
ENTRYPOINT ["java", "-jar", "app.jar"]

 

그렇다면 Docker 이미지를 build하기 위해서는 위와 같은 Dockerfile을 프로젝트 루트 디렉토리에 정의해야한다.

 

이렇게 되면 내 프로젝트의 코드가 JDK 17 이미지로 감싸져서 Docker hub에 보낼 수 있는 사전작업을 마친 것이다.

 

      # Dockerfile app 이미지 build & push
      - name: Docker Log in
        run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u "${{ secrets.DOCKER_USERNAME }}" --password-stdin

      - name: build Docker Image
        run: docker build -t ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest .

      - name: push Docker Hub
        run: docker push ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest

Docker hub에 회원가입을 하고 USERNAME과 PASSWORD를 github secrets variable에 정의해야한다.

CD job에서 위와 같이 DOCKER_USERNAME과 DOCKER_PASSWORD를 통해 docker hub에 연결을 하고 Dockerfile로 빌드된 Image를 Docker hub에 push한다.

4️⃣ ssh to server & pull docker image

다음으로는 docker에 image를 push했으므로 서버에 접속을 해서 push했던 image를 가져올 것이다.

      # ssh로 서버 접속해서 컨테이너 띄우기
      - name: ssh to ec2 and deploy
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker rmi -f ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
            docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest

github actions에서 서버에 접속해야하므로, ssh를 통해 서버에 접속 한 후 기존에 있던 image를 삭제하고 push 했던 이미지를 pull해오는 과정이다.

---

5️⃣ DB 관련 컨테이너 미리 서버에 띄워두기

현재 app과 관련된 image를 pull해온 상태이다.

 

물론 CD job의 과정에서 db와 관련된 부분들도 함께 docker compose로 내렸다가 띄울 수 있겠지만, 그렇게 되는 경우에는 데이터가 손실의 위험이 있다.

 

docker compose down 명령어는 기본적으로 컨테이너와 함께 연결된 네트워크와 볼륨까지 제거한다.

 

 

따라서 DB 컨테이너에 별도로 볼륨을 설정해두지 않았다면, 컨테이너가 내려가는 순간 DB 데이터도 함께 삭제된다.

이러한 이유로, 배포 시에는 앱 컨테이너만 내렸다가 다시 올리는 방식이 더 안전하고 효율적이다.

앱 컨테이너만 내렸다가 다시 올리는 방식으로 진행하려면 CI/CD를 진행하기 전에 서버에 docker-compose로 db관련 image들을 띄워야 한다. db 서버가 띄워져 있어야 app 컨테이너가 제대로 동작할 수 있기 때문이다.

---

 

6️⃣ app 컨테이너 띄우기 -> 서버 실행

최종적으로 서버를 실행하는 과정이다.

 

services:
  app:
    image: your-docker-username/daboa-app:latest
    container_name: springboot-app
    ports:
      - "8080:8080"
    environment:
	<<필요한 환경변수 정의해주기>>

위의 docker-compose.yml을 서버에 미리 정의해둔다.

      # ssh로 서버 접속해서 컨테이너 띄우기
      - name: ssh to ec2 and deploy
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker rmi -f ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
            docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
            cd /home/ubuntu/daboa/docker/app
            docker compose up -d
            docker image prune -f

 

그렇게 되면 CD job 과정 중에 docker compose up -d 명령어가 들어왔을 때 이미지를 기반으로 컨테이너를 띄울 수 있다.

 

성공

 

💡 해당 과정이 무중단 배포가 아닌 이유?

docker rmi -f ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
cd /home/ubuntu/daboa/docker/app
docker compose up -d
docker image prune -f

해당 과정 중 기존의 이미지를 삭제하고 다시 pull해와서 docker compose로 컨테이너를 띄우는 과정이 있다.

즉, 이 흐름은 기존 앱 컨테이너를 중단하고, 그 다음에 새로운 컨테이너를 실행하는 방식이기 때문에 중단 배포 또는 중지 후 재배포 방식이라고 불린다.

 

따라서 서비스가 배포 중 일시적으로라도 내려가 있는 상태가 발생할 수 있는 방식이다.

---

🔸Workflow 스크립트

name: CI/CD with Docker

# event trigger
# main이나 develop 브랜치에 push가 되었을 때 실행 / main에 pr되면 실행
on:
  pull_request:
    branches:
      - main

  push:
    branches:
      - develop
      - main

  workflow_dispatch:

jobs:
  ci:
    name: Run CI
    runs-on: ubuntu-latest

    steps:
      # 현재 워크플로우를 실행하는 저장소의 소스 코드를 가져오는 작업
      - name: checkout
        uses: actions/checkout@v4

      # JDK setting - github actions에서 사용할 JDK 설정
      - name: setting JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      # gradlew 실행권한 부여
      - name: Grant execute permission to gradlew
        run: chmod +x ./gradlew

      # gradle caching - 빌드 시간 향상
      - name: Gradle cashing
        uses: actions/cache@v3
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            gradle-${{ runner.os }}-

      # 필요한 라이브러리를 다운로드
      - name: dependency
        run: ./gradlew dependencies

      # 테스트
      - name: Run tests
        run: ./gradlew test --no-daemon

      # gradle build, demon 사용 x
      - name: build
        run: ./gradlew build --no-daemon

      # build된 jar 파일 저장
      - name: upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: jar
          path: build/libs/*.jar

  cd:
    name: Build & Deploy
    runs-on: ubuntu-latest
    needs: ci

    steps:
      - name: code checkout
        uses: actions/checkout@v4

      # jar 파일 가져오기
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: jar
          path: build/libs

      # Dockerfile app 이미지 build & push
      - name: Docker Log in
        run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u "${{ secrets.DOCKER_USERNAME }}" --password-stdin

      - name: build Docker Image
        run: docker build -t ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest .

      - name: push Docker Hub
        run: docker push ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest

      # ssh로 서버 접속해서 컨테이너 띄우기
      - name: ssh to ec2 and deploy
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker rmi -f ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
            docker pull ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_IMAGENAME }}:latest
            cd /home/ubuntu/daboa/docker/app
            docker compose up -d
            docker image prune -f

---

🚨트러블 슈팅

1️⃣ docker 그룹 권한 부여하기

docker compose up -d

CI/CD를 배포하기 전 docker compose로 db관련된 것들을 띄울라 했는데,

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

현재 사용자가 docker 그룹에 속해있지 않아 docker compose를 실행할 권한이 없다고 에러가 떴다.

 

🧐 해결하기

sudo usermod -aG docker $USER

현재 유저에게 docker 그룹에 추가해주는 명령어를 실행한다.

그리고 서버를 재실행한 이후에 다시 명령어를 실행하면 위와 같이 docker 컨테이너가 제대로 뜨는 것을 확인할 수 있다.

---

2️⃣ gradlew 실행권한 부여

      # 필요한 라이브러리를 다운로드
      - name: dependency
        run: ./gradlew dependencies

 

CI를 실행하는 과정 중 위의 플로우를 진행하던 도중 gradlew에 대한 실행권한이 없어서 뜨는 에러이다.

🧐해결하기

      # gradlew 실행권한 부여
      - name: Grant execute permission to gradlew
        run: chmod +x ./gradlew

플로우 중에 위와 같이 권한을 부여해주었다.

성공적으로 CI를 완료하였다.

---

3️⃣ CD 과정 중 jar 파일을 찾지 못함

#9 ERROR: lstat /var/lib/docker/tmp/buildkit-mount.../build/libs: no such file or directory

# 빌드된 JAR 복사
COPY build/libs/*.jar app.jar

Dockerfile을 실행하는 과정에서, 해당 명령어를 실행하는 과정 중에 *.jar를 찾지 못해 발생하는 에러이다.

 

이유는 CI단계에서 jar를 빌드하는데 CD를 다시 시작하면서 jar파일을 불러오지 못해서 그런것이다.

🧐해결하기

github actions에는 artifact라는 중간 결과물을 저장할 수 있는 공간이 있다.

 

따라서 artifact를 이용하면 쉽게 해결할 수 있다.

# CI 마지막에
- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: jar
    path: build/libs/*.jar

# CD 시작 시
- name: Download artifact
  uses: actions/download-artifact@v4
  with:
    name: jar
    path: build/libs/

• 문제점: CI Job에서 .jar 파일을 빌드함 → 하지만 CD Job에서는 파일이 사라짐
• 해결법: CI Job에서 artifact로 업로드하고→ CD Job에서 다운로드해서 이어서 사용

 

성공적으로 CI/CD 파이프라인을 구축하였다.