Jenkins란? + 설치(Docker 기준, 초기 설정)

Jenkins란 무엇인가

Jenkins는 빌드, 테스트, 배포까지 소프트웨어 개발 과정을 자동화해 CI/CD 파이프라인을 구성할 수 있게 해주는 오픈 소스 자동화 서버입니다. Java 기반으로 동작하며, Git과 같은 버전 관리 시스템, 빌드 도구, 배포 도구와 연동해 코드 변경 시점마다 자동으로 작업을 실행할 수 있습니다.

주로 다음과 같은 목적에 사용합니다.

• 코드 변경마다 자동 빌드·테스트를 수행하는 지속적 통합(Continuous Integration) 구현
• 승인/조건에 따라 점진적으로 배포를 진행하는 지속적 배포(Continuous Deployment/Delivery) 구성
• Git, Docker, Slack 등 다양한 플러그인을 통해 팀에서 사용하는 DevOps 도구 체인과 손쉽게 연동

Jenkins는 JVM만 있으면 Linux, Windows, macOS, 컨테이너 환경 등 거의 모든 플랫폼에서 동작할 수 있습니다. 수백 개의 플러그인을 통해 소스 관리, 빌드, 테스트, 배포, 모니터링 등 대부분의 DevOps 도구와 연동이 가능합니다.

Docker로 Jenkins 설치 개요

여기서는 Jenkins를 호스트 서버에 직접 설치하는 대신, docker-compose.yml과 Dockerfile을 이용해 컨테이너 형태로 구성합니다. 이렇게 하면 Jenkins 업그레이드나 설정 백업·복원이 단순해지고, 다른 서버로의 마이그레이션도 비교적 수월해집니다.
또한 Jenkins 컨테이너 안에서 Docker를 사용하도록 설정해, Jenkins Job이나 Pipeline에서 docker build, docker compose 명령을 실행해 애플리케이션 빌드와 컨테이너 기동까지 자동화할 수 있습니다.

docker-compose.yml 작성

먼저 서버에서 /home/ubuntu/app/jenkins 폴더를 만들고 해당 경로에 docker-compose.yml 파일을 생성합니다.

cd /home/ubuntu/app

# jenkins 폴더 생성 
mkdir jenkins

cd /jenkins 

# docker-compose.yml 파일 생성 
touch docker-compose.yml 

# 편집기 사용 
vim docker-compose.yml 

 services:
  jenkins:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: jenkins
    user: root
    ports:
      - "9090:8080"
      - "50000:50000"
    volumes:
      - jenkins_home:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
      - /home/ubuntu/app:/home/ubuntu/app
      - /home/ubuntu/.ssh:/root/.ssh
    restart: always

volumes:
  jenkins_home: 

각 항목은 다음 의미를 가집니다.

• build.context, dockerfile
  • 현재 디렉터리의 Dockerfile을 사용해 커스텀 Jenkins 이미지를 빌드합니다.
• user: root
  • 컨테이너 내부에서 root 계정으로 실행해 Docker 설치 및 호스트 리소스 접근을 단순화합니다.
• ports
  • 9090:8080: 호스트 9090 포트를 컨테이너 8080 포트(Jenkins UI)와 매핑
  • 50000:50000: JNLP 에이전트 연결용 포트로, 별도 에이전트 노드를 구성할 때 사용
• volumes
  • jenkins_home:/var/jenkins_home: Jenkins 설정, Job, 플러그인 데이터를 영구 보관하는 볼륨
  • /var/run/docker.sock:/var/run/docker.sock: Jenkins 컨테이너가 호스트의 Docker 데몬을 그대로 사용하도록 연결
  • /home/ubuntu/app:/home/ubuntu/app: 실제 프로젝트 코드가 있는 디렉터리를 Jenkins에서 그대로 참조할 수 있도록 마운트
  • /home/ubuntu/.ssh:/root/.ssh: 호스트의 SSH 키를 컨테이너 root 계정에 마운트해 GitHub, GitLab, 사내 Git 등 SSH 리포지토리에 접근 가능하게 설정

Dockerfile 작성

같은 경로에 docker-compose.yml에서 사용할 Dockerfile을 생성합니다.

# Dockerfile 생성 
touch Dockerfile

# 편집기 
vim Dockerfile

FROM jenkins/jenkins:lts-jdk21

USER root

# 1. 기본 필수 패키지 설치 (Docker Client + curl)
RUN apt-get update && \
    apt-get install -y docker.io curl && \
    rm -rf /var/lib/apt/lists/*

# 2. Docker Compose V2 수동 설치
# 공식 GitHub 릴리즈에서 바이너리를 다운로드하여 CLI 플러그인 경로에 설치합니다.
RUN mkdir -p /usr/lib/docker/cli-plugins && \
    curl -SL https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-x86_64 \
      -o /usr/lib/docker/cli-plugins/docker-compose && \
    chmod +x /usr/lib/docker/cli-plugins/docker-compose

# 3. Git Safe Directory 설정 (영구 적용)
RUN git config --system --add safe.directory '*'

USER root

각 단계는 다음 역할을 합니다.

• FROM jenkins/jenkins:lts-jdk21
  • Jenkins LTS 및 JDK 21이 포함된 공식 이미지를 기반으로 사용합니다.
  • JDK 21 외 다른 버전 이용 시 일부 플러그인 설치가 불가합니다.
  • 프로젝트의 JDK 버전과 꼭 맞출 필요 없습니다. 해당 JDK는 플러그인으로 JDK를 설정할 수 있습니다.
• apt-get install -y docker.io curl
  • 컨테이너 내부에서 docker CLI를 사용할 수 있도록 Docker 클라이언트를 설치합니다.
  • curl은 Docker Compose 바이너리를 다운로드할 때 사용합니다.
• Docker Compose v2 설치
  • /usr/lib/docker/cli-plugins/docker-compose 경로에 바이너리를 두면 docker compose 서브커맨드로 인식됩니다.
  • 이후 Jenkins Job에서 docker compose up -d와 같은 명령을 그대로 사용할 수 있습니다.
• git config --system --add safe.directory '*'
  • Jenkins가 Git 리포지토리를 다룰 때 “dubious ownership” 경고를 피하기 위해 모든 디렉터리를 Git safe directory로 처리합니다.
  • 호스트 디렉터리를 마운트했는데 권한이 Jenkins 사용자와 다를 때 유용합니다.

실무에서는 docker.io 대신 Docker 공식 리포지토리(docker-ce)에서 CLI를 설치하는 예제도 자주 사용합니다. 보안상으로는 Dockerfile 마지막에 USER jenkins로 다시 내려가는 구성이 더 안전하지만, 여기서는 권한 문제를 피하기 위해 root 계정을 유지했습니다.

본글에서는 권한 문제를 겪고 싶지 않기에 그냥 root로 하겠습니다.

Jenkins 컨테이너 실행 및 초기 설정

이제 컨테이너를 빌드하고 실행한 뒤, http://<서버IP>:9090 으로 접속합니다.

# build 
docker compose build 

# 컨테이너 띄우기 
docker compose up -d 

# 빌드와 실행을 한 번에
docker compose up --build -d 

컨테이너가 올라가면 브라우저에서 http://<서버IP>:9090으로 접속합니다. 처음 접속 시 Jenkins는 초기 관리자 비밀번호 입력 화면을 보여주는데, 이 값은 컨테이너 내부의 /var/jenkins_home/secrets/initialAdminPassword 파일에서 확인할 수 있습니다.

docker exec -it jenkins cat /var/jenkins_home/secrets/initialAdminPassword

위 명령으로 얻은 비밀번호를 초기 화면에 입력하면 다음 단계로 진행됩니다. 이후 플러그인 설치 화면이 나오면, 처음 사용하는 경우라면 “Install suggested plugins”를 선택해 Git, Pipeline 등 기본 플러그인을 자동 설치하는 것이 편리합니다. 특정 조직 표준이 있거나 최소 설치를 선호한다면 최소 플러그인만 설치 후 필요한 플러그인만 추가하는 방식도 가능합니다.

플러그인 설치가 끝나면 관리자 계정 생성 화면이 표시되며, 일반적인 회원가입처럼 사용자명·비밀번호·이메일 등을 입력해 계정을 만들면 됩니다. 여기까지가 서버에 Docker 기반으로 Jenkins를 설치하고 초기 설정을 완료하는 전체 흐름입니다. 이후 글에서는 Jenkins를 활용하기 전에 알고 있으면 좋은 기본 개념과 주요 용어, Pipeline 구성 방법 등을 정리해 보겠습니다.