|

GitHub Actions로 Docker 자동 배포 (워크플로, 이미지 빌드, Push 자동화)

코드 수정할 때마다 서버에 직접 접속해서 배포하던 시절이 있었습니다. 처음에는 그게 당연한 줄 알았는데, 직접 겪어보니 반복 작업이 쌓일수록 실수도 늘고 피로도도 만만치 않았습니다. 그러다 GitHub Actions와 Docker를 함께 써서 배포를 자동화해 본 뒤로는, 배포에 대한 생각 자체가 바뀌었습니다. PHP 개발자가 Next.js 프로젝트를 처음 자동 배포해 본 경험을 있는 그대로 풀어보겠습니다.

PHP 배포와 Next.js 배포, 뭐가 다를까

PHP를 쓸 때는 배포가 비교적 단순했습니다. 웹서버에 소스 파일을 올리고 Apache나 Nginx에서 PHP가 실행되도록 설정하면 끝이었습니다. 물론 Composer나 환경변수 설정이 필요한 경우도 있었지만, 기본 구조는 “파일을 서버에 올린다”는 개념이었습니다.

그런데 Next.js는 달랐습니다. 개발 중에는 npm run dev로 띄우지만, 실제 운영 환경에서는 npm run build로 빌드한 뒤 npm run start로 실행해야 합니다. 빌드(Build)란 소스 코드를 실제 서버에서 최적화된 형태로 변환하는 과정으로, PHP처럼 파일을 단순히 복사하는 방식과는 본질적으로 다릅니다. 처음에 이 차이를 몰랐을 때 서버에 소스만 올렸다가 아무것도 안 뜨는 상황을 겪었습니다. 그때 느낀 당혹감이 지금도 생생합니다.

그래서 이번에는 Docker를 선택했습니다. Docker란 애플리케이션과 그 실행 환경을 하나의 컨테이너(Container)라는 독립된 패키지로 묶어서 어디서든 동일하게 실행할 수 있게 해주는 기술입니다. 서버 환경이 달라도 “내 컴퓨터에서는 됐는데 서버에서 안 된다”는 문제를 원천 차단할 수 있습니다. 개인 서버로 사용 중인 Synology NAS에 이미 Docker 환경이 구성되어 있었기 때문에, 선택은 자연스러웠습니다.

GitHub Actions 워크플로를 직접 짜보니

GitHub Actions란 GitHub 저장소에 코드가 push되거나 특정 이벤트가 발생했을 때 미리 정의해둔 작업을 자동으로 실행해주는 CI/CD 도구입니다. CI/CD란 Continuous Integration(지속적 통합)과 Continuous Deployment(지속적 배포)의 약자로, 코드 변경부터 서비스 반영까지의 과정을 자동화하는 개발 방식을 말합니다.

워크플로(Workflow)는 .github/workflows 폴더 안에 YAML 파일로 작성합니다. 제가 직접 써봤는데, 처음에는 들여쓰기 하나 잘못돼서 Actions가 아예 실행조차 안 되는 경우도 있었습니다. YAML 문법이 익숙하지 않다면 초반에 꽤 시간을 쏟게 됩니다. 전체 워크플로의 흐름을 정리하면 다음과 같습니다.

  1. 빌드용 Ubuntu 머신을 자동으로 시작한다 (runs-on: ubuntu-latest)
  2. 해당 머신에 GitHub 저장소를 체크아웃(Checkout)한다 — 최신 코드를 내려받는 과정
  3. Docker Meta 액션으로 이미지 이름과 버전 태그를 자동 생성한다
  4. Docker Buildx를 설정한다 — 멀티 플랫폼 빌드를 지원하는 확장 빌드 도구
  5. Docker Hub에 로그인한다 — 이미지를 업로드할 원격 저장소
  6. Dockerfile을 기반으로 이미지를 빌드하고 Docker Hub로 Push한다

여기서 Docker Hub란 빌드된 Docker 이미지를 저장하고 공유할 수 있는 원격 레지스트리(Registry)로, GitHub와 유사한 개념이지만 코드 대신 컨테이너 이미지를 관리하는 공간입니다. 로그인 정보는 GitHub 저장소의 Secrets에 DOCKERHUB_USERNAME과 DOCKERHUB_TOKEN으로 저장해두면, 워크플로에서 ${{ secrets.DOCKERHUB_TOKEN }} 형태로 안전하게 불러올 수 있습니다. 처음에 이걸 환경변수로 직접 넣었다가 토큰이 그대로 노출될 뻔했는데, Secrets 기능이 있어서 다행이었습니다.

push 조건은 branches와 tags 모두 ‘**'(와일드카드)로 설정했습니다. 브랜치에 push하면 브랜치 이름으로 태그된 이미지가, 릴리즈 태그를 push하면 버전 번호로 태그된 이미지가 Docker Hub에 올라갑니다. 실제로 v1.0 태그를 push했더니 1.0과 1이라는 태그가 동시에 생성되는 걸 보고 꽤 편리하다고 느꼈습니다. GitHub Actions의 공식 문서는 GitHub Docs — GitHub Actions에서 확인할 수 있습니다.

Dockerfile 구조와 이미지 빌드 경험

Dockerfile이란 Docker 이미지를 만들기 위한 설계도로, 베이스 이미지 선택부터 패키지 설치, 파일 복사, 실행 명령어까지 이미지 생성 과정을 순서대로 기술한 파일입니다. 이번 프로젝트에서는 node:erbium-buster-slim을 베이스 이미지로 사용했습니다. slim이 붙은 이미지는 불필요한 패키지를 제거한 경량 버전으로, 같은 Node.js 환경이어도 용량이 훨씬 작습니다.

제 경험상 이건 좀 다른 부분이 있었는데, Dockerfile에서 타임존 설정을 빠뜨리면 컨테이너 내부 시간이 UTC 기준으로 동작해서 로그 시간이 9시간 어긋납니다. ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime으로 KST(한국 표준시)를 명시적으로 지정해두는 게 나중에 골치 아픈 일을 막는 방법입니다. 처음에 이걸 간과했다가 디버깅할 때 시간대 때문에 한참 헤맸습니다.

플랫폼(Platform) 설정도 놓치기 쉬운 부분입니다. platforms: linux/amd64로 지정하지 않으면 로컬 맥(Apple Silicon)에서 빌드한 이미지가 서버의 x86 환경에서 실행되지 않는 경우가 생깁니다. 이미지 빌드는 성공했는데 서버에서 컨테이너가 실행되지 않으면 플랫폼 불일치를 가장 먼저 의심해볼 만합니다. Docker의 공식 멀티 플랫폼 빌드 가이드는 Docker Docs — Multi-platform builds에서 확인할 수 있습니다.

자동화 이후 달라진 배포 감각

GitHub Actions를 적용하고 나서 가장 먼저 달라진 건 배포를 대하는 마음가짐이었습니다. 이전에는 코드를 수정하면 “이제 서버에 들어가서 배포해야겠다”는 생각이 먼저 들었습니다. 그런데 자동화 이후에는 “push하면 되지”라는 생각으로 바뀌었습니다. 작은 차이 같지만, 배포 부담이 줄어드니 작은 수정도 더 자주 반영하게 됐습니다.

물론 자동화가 모든 문제를 해결해주지는 않습니다. 빌드가 실패하면 Actions 탭에서 로그를 직접 확인해야 하고, 이미지가 정상적으로 Docker Hub에 올라갔어도 서버의 컨테이너가 새 이미지로 교체되는 과정은 별도로 트리거해줘야 하는 경우도 있습니다. 솔직히 이건 예상 밖이었습니다. “push하면 배포까지 완료”라는 그림을 그렸는데, 실제로는 이미지 빌드와 서버 배포가 별개의 단계라는 걸 직접 겪고 나서야 제대로 이해했습니다.

그래도 기술 스택이 처음에는 굉장히 많아 보였지만 각각의 역할이 명확하게 나뉘어 있다는 걸 이번에 깨달았습니다. GitHub는 코드를 관리하고, GitHub Actions는 배포 과정을 자동화하고, Docker는 실행 환경을 패키징하고, Synology는 실제 서버 역할을 하고, Reverse Proxy는 외부 요청을 내부 컨테이너로 연결합니다. 하나씩 역할을 이해하고 연결하다 보니 전체 그림이 보이기 시작했습니다.

아직 프로젝트 규모가 크지 않아서 Synology NAS로도 충분하지만, Docker로 컨테이너화해두면 나중에 클라우드로 이전할 때도 같은 이미지를 그대로 사용할 수 있다는 점이 가장 큰 장점으로 보입니다. 지금 당장은 작은 서버지만 확장 가능성을 열어두는 구성이라는 점에서 이 방식을 선택한 게 잘한 것 같다는 생각이 듭니다.

자주 묻는 질문

Q. GitHub Actions로 Docker 이미지를 빌드할 때 Docker Hub 토큰은 어디서 발급받나요?

A. Docker Hub에 로그인한 뒤 Account Settings → Security 메뉴에서 Access Token을 발급받을 수 있습니다. 발급받은 토큰은 GitHub 저장소의 Settings → Secrets and variables → Actions에 DOCKERHUB_TOKEN이라는 이름으로 저장해두면 워크플로에서 안전하게 불러올 수 있습니다. 토큰을 YAML 파일에 직접 넣는 것은 보안상 절대 금지입니다.

Q. 모든 브랜치가 아니라 특정 브랜치에 push할 때만 빌드를 트리거하려면 어떻게 하나요?

A. 워크플로 YAML 파일의 on.push.branches 항목에서 ‘**’ 대신 원하는 브랜치 이름을 적으면 됩니다. 예를 들어 main 브랜치만 트리거하려면 – main으로 변경하면 됩니다. 개발 브랜치에서 테스트 중일 때 불필요한 빌드가 계속 돌아가는 게 귀찮다면 이 설정을 먼저 조정하는 게 좋습니다.

Q. Apple Silicon(M1/M2) 맥에서 빌드한 Docker 이미지가 서버에서 실행되지 않는 경우는 왜인가요?

A. CPU 아키텍처 차이 때문입니다. Apple Silicon은 arm64 기반이고, 일반 서버는 대부분 amd64(x86_64) 기반입니다. GitHub Actions 워크플로에서 platforms: linux/amd64를 명시하면 빌드 머신(ubuntu-latest)이 amd64 이미지를 생성하므로 서버에서 정상 실행됩니다. Docker Buildx를 사용하면 멀티 플랫폼 이미지를 한 번에 빌드하는 것도 가능합니다.

Q. GitHub Actions 빌드가 실패했을 때 원인을 어디서 확인하나요?

A. GitHub 저장소의 Actions 탭에서 실패한 워크플로를 클릭하면 각 스텝별 로그를 확인할 수 있습니다. 어느 단계에서 빨간 X가 떴는지 보고 해당 스텝의 로그를 펼치면 오류 메시지가 나옵니다. 제 경험상 초반에 가장 많이 나오는 오류는 Secrets 이름 오타, Dockerfile 경로 불일치, YAML 들여쓰기 오류였습니다.

처음에는 PHP 배포보다 복잡해 보였던 이 구성이, 직접 하나씩 연결하고 나니 오히려 더 명확하게 느껴졌습니다. 코드를 수정하고 push하면 나머지는 자동으로 처리되는 흐름을 한 번 경험하면, 다시 수동 배포로 돌아가기가 어렵습니다. Next.js 외에 다른 프레임워크도 같은 구조로 적용할 수 있으니, 아직 자동 배포를 해본 적 없다면 작은 토이 프로젝트 하나로 먼저 시도해보는 걸 권합니다. Dockerfile 작성부터 GitHub Actions 워크플로 연결까지 한 번 통으로 겪어보는 게 개념 이해에 가장 빠른 방법이었습니다.

—
참고: https://teichae.tistory.com/entry/Github-Actions%EC%9D%84-%EC%9D%B4%EC%9A%A9%ED%95%9C-Docker-Image-Build-%EB%B0%8F-Push

Similar Posts