Docker로 Jenkins 설치하고 초기 설정까지 완료하는 방법

Docker Jenkins 설치가 WAR 파일 방식보다 나은 이유

Jenkins를 서버에 직접 설치하는 전통적인 방법은 WAR 파일을 다운받아 Java로 실행하거나, apt나 yum 같은 패키지 매니저로 설치하는 방식이다. 이 방식의 문제는 Jenkins가 실행되는 Java 버전에 직접 의존한다는 점이다. OS 업데이트나 다른 프로젝트의 Java 버전 변경으로 Jenkins 실행 환경이 흔들릴 수 있다. 실제로 서버 Java가 11에서 17로 업그레이드되면서 Jenkins가 구동되지 않아 긴급 복구 작업을 한 적이 있다. Docker로 설치하면 Jenkins가 필요로 하는 Java 환경이 컨테이너 안에 격리된다. 서버에 어떤 Java가 설치되어 있든 무관하게 항상 동일한 환경에서 Jenkins가 실행된다. 설치 과정도 단순하다. docker run 명령 한 줄로 컨테이너를 생성하고 실행할 수 있다. 이미지 자체가 Jenkins 공식 팀이 유지 관리하기 때문에 별도 패키지 저장소를 설정할 필요가 없다. 서버를 새로 프로비저닝할 때도 docker run 명령 하나로 Jenkins 환경을 그대로 복원할 수 있어서 인프라 관리가 편해진다. 여러 서버에 동일한 Jenkins 환경을 배포할 때도 이미지 태그 하나로 버전을 통일할 수 있다는 점이 큰 장점이다.

Jenkins Docker 이미지 종류와 docker jenkins 설치에 적합한 이미지 선택

Docker Hub에 올라온 Jenkins 공식 이미지는 jenkins/jenkins 저장소에서 관리된다. jenkins/jenkins:lts 태그는 Long Term Support 버전으로 안정성을 우선시하는 환경에 적합하다. jenkins/jenkins:latest는 최신 버전을 따라가지만 안정성이 보장되지 않아 프로덕션 환경에는 lts를 권장한다. Jenkins 2.357 이후로 Java 11 지원이 종료됐고 현재는 Java 17과 21을 권장한다. jenkins/jenkins:lts-jdk17처럼 태그에 JDK 버전이 명시된 이미지를 쓰면 어떤 Java로 실행되는지 이미지 이름에서 바로 알 수 있다. latest를 쓰다가 어느 날 업데이트 후 플러그인 호환성 문제가 생긴 적이 있어서 그 이후로는 lts 태그를 고정해서 쓰고 있다. 처음 Docker Jenkins를 설치한다면 jenkins/jenkins:lts-jdk17을 추천한다. alpine 기반의 경량 이미지도 있는데, 일부 플러그인이 alpine 환경에서 동작하지 않는 경우가 있어서 특별한 이유가 없다면 일반 이미지를 쓰는 게 안정적이다. 이미지 태그를 latest나 lts처럼 부동 태그로 설정해두면 docker pull 할 때마다 최신 버전이 내려오기 때문에, 버전을 고정하고 싶다면 구체적인 버전 번호를 포함한 태그를 쓰는 것도 방법이다.

docker run으로 Jenkins 컨테이너를 시작하는 방법

Docker Jenkins 설치는 docker run 명령 하나로 시작한다. 기본 실행 명령은 docker run -d -p 8080:8080 -p 50000:50000 --name jenkins jenkins/jenkins:lts-jdk17 이다. -d는 백그라운드 실행, -p 8080:8080은 브라우저 접속용 포트, -p 50000:50000은 Jenkins agent 연결용 포트다. 이 명령만으로 컨테이너가 시작되고 브라우저에서 http://서버IP:8080으로 접속하면 Jenkins 초기 설정 화면이 나타난다. 단, 이 상태에서 컨테이너를 삭제하면 Jenkins 설정과 플러그인, Job 데이터가 모두 사라진다. 컨테이너가 재시작해도 데이터가 유지되려면 볼륨 마운트가 필요하다. 볼륨 마운트는 -v jenkins_home:/var/jenkins_home 옵션을 추가하면 된다. --restart unless-stopped를 추가하면 서버 재부팅 후에도 자동으로 Jenkins 컨테이너가 올라온다. 처음 Jenkins Docker 설치를 해봤을 때 볼륨을 빠뜨려서 컨테이너 재시작 후 설정이 다 날아가는 걸 경험했다. 볼륨 마운트는 선택이 아니라 필수다.

docker run -d \
  -p 8080:8080 \
  -p 50000:50000 \
  --name jenkins \
  -v jenkins_home:/var/jenkins_home \
  --restart unless-stopped \
  jenkins/jenkins:lts-jdk17

Jenkins Docker 초기 설정 — 관리자 비밀번호 확인과 플러그인 설치

컨테이너가 실행되면 http://서버IP:8080에 접속했을 때 'Unlock Jenkins' 화면이 나온다. 초기 관리자 비밀번호를 입력해야 다음으로 넘어갈 수 있다. 비밀번호는 컨테이너 로그에서 확인한다. docker logs jenkins를 실행하면 로그에 비밀번호가 찍혀 있다. docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword 명령으로도 확인할 수 있다. 비밀번호를 입력하면 플러그인 설치 화면이 나온다. 'Install suggested plugins'를 선택하면 Jenkins 팀이 추천하는 기본 플러그인이 자동으로 설치된다. 처음 Jenkins를 설치한다면 이 옵션을 선택하는 게 가장 빠르다. 플러그인 설치가 끝나면 관리자 계정을 만들고, Jenkins URL을 설정하는 화면이 이어진다. Jenkins URL은 외부에서 접근할 때 쓰는 실제 주소를 입력해야 한다. 나중에 GitHub Webhook을 연동할 때 이 URL이 Payload URL의 기반이 되기 때문에 처음부터 정확하게 입력해두는 게 좋다. 설정을 마치면 Jenkins 대시보드가 열리고 Job을 만들 수 있는 상태가 된다.

Jenkins Docker 볼륨 마운트로 설정과 데이터를 보존하는 방법

Docker Jenkins의 모든 데이터는 컨테이너 안의 /var/jenkins_home 경로에 저장된다. Job 설정, 플러그인, 빌드 이력, 자격증명 전부 이 경로 아래에 있다. 볼륨 마운트 없이 컨테이너를 삭제하면 이 데이터가 모두 사라진다. 볼륨 마운트 방식은 두 가지다. 첫 번째는 Docker named volume이다. docker volume create jenkins_home으로 볼륨을 만들고 -v jenkins_home:/var/jenkins_home으로 마운트한다. 컨테이너를 삭제해도 볼륨은 남아 있어서 새 컨테이너를 만들 때 같은 볼륨을 연결하면 데이터가 그대로 복원된다. 두 번째는 바인드 마운트다. -v /home/user/jenkins_data:/var/jenkins_home처럼 서버의 실제 경로를 지정한다. 데이터가 서버 파일 시스템에 직접 저장되기 때문에 백업 스크립트로 파일을 복사하거나 압축하는 방식으로 백업이 가능하다. 바인드 마운트를 쓸 때 주의할 점은 파일 권한 문제다. Jenkins 컨테이너는 uid 1000의 jenkins 사용자로 실행되기 때문에 호스트 경로의 소유자를 uid 1000으로 맞춰야 컨테이너가 그 경로에 쓰기를 할 수 있다. chown 1000:1000 /home/user/jenkins_data 명령으로 권한을 설정해두면 된다.

Jenkins Docker 컨테이너 버전을 업그레이드하는 방법

Docker Jenkins의 버전 업그레이드는 이미지를 교체하는 방식으로 처리한다. 새 이미지를 내려받고, 기존 컨테이너를 중지, 삭제한 뒤 같은 볼륨을 마운트해서 새 이미지로 컨테이너를 다시 만들면 된다. 데이터는 볼륨에 남아 있기 때문에 업그레이드 후에도 기존 Job, 플러그인, 설정이 그대로 유지된다. 순서는 docker pull jenkins/jenkins:lts-jdk17로 최신 이미지를 받은 뒤, docker stop jenkins && docker rm jenkins로 기존 컨테이너를 제거하고, 처음에 사용한 docker run 명령을 다시 실행하면 된다. 업그레이드 전에 jenkins_home 디렉토리를 통째로 압축해두는 게 좋다. 문제가 생겼을 때 이전 이미지로 롤백하고 데이터를 복원할 수 있기 때문이다. 메이저 버전 업그레이드라면 플러그인 호환성 문제가 생길 수 있어서 릴리즈 노트를 미리 확인하는 게 좋다. 마이너 버전 업그레이드는 대부분 무사히 넘어가지만, 실제로 특정 버전 업그레이드 후 자주 쓰던 플러그인 하나가 작동하지 않아서 직전 이미지로 롤백한 적이 있다. 업그레이드 직후에는 주요 파이프라인을 한 번씩 돌려서 정상 동작을 확인하는 습관이 필요하다.