zioinfo-mail/workspace/guardia-itsm/cicd/docs/01_jenkins_install.md

Jenkins 설치 가이드

버전: Jenkins LTS (2.440.x 기준)
대상 OS: RHEL 8/9, Rocky Linux 8/9, Ubuntu 20.04/22.04
최종 수정: 2026-05-25

---

1. 사전 요구사항

구분	최소	권장
CPU	2 Core	4 Core
RAM	4 GB	8 GB
Disk	50 GB	100 GB
Java	JDK 17	JDK 21
OS	RHEL 8 / Ubuntu 20.04	RHEL 9 / Ubuntu 22.04

필수 패키지

# RHEL/Rocky
sudo dnf install -y git curl wget unzip fontconfig java-17-openjdk-devel

# Ubuntu
sudo apt-get install -y git curl wget unzip fontconfig openjdk-17-jdk

---

2. RHEL 8 / Rocky Linux 8/9 설치

2-1. Jenkins 저장소 추가

sudo wget -O /etc/yum.repos.d/jenkins.repo \
    https://pkg.jenkins.io/redhat-stable/jenkins.repo

sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key

sudo dnf upgrade -y

2-2. Jenkins 설치

sudo dnf install -y jenkins

sudo systemctl enable jenkins
sudo systemctl start jenkins
sudo systemctl status jenkins

2-3. 방화벽 설정

# firewalld 사용 시
sudo firewall-cmd --permanent --new-service=jenkins
sudo firewall-cmd --permanent --service=jenkins --set-short=Jenkins
sudo firewall-cmd --permanent --service=jenkins --add-port=8080/tcp
sudo firewall-cmd --reload

# 또는 직접 포트 개방
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

2-4. SELinux 설정 (RHEL)

# Jenkins가 네트워크 바인딩 가능하도록
sudo setsebool -P httpd_can_network_connect 1
sudo semanage port -a -t http_port_t -p tcp 8080 2>/dev/null || \
sudo semanage port -m -t http_port_t -p tcp 8080

---

3. Ubuntu 20.04 / 22.04 설치

3-1. Jenkins 저장소 추가

sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
    https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key

echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
    https://pkg.jenkins.io/debian-stable binary/" | \
    sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

sudo apt-get update

3-2. Jenkins 설치

sudo apt-get install -y jenkins

sudo systemctl enable jenkins
sudo systemctl start jenkins
sudo systemctl status jenkins

3-3. UFW 방화벽 설정

sudo ufw allow 8080/tcp
sudo ufw reload
sudo ufw status

---

4. 초기 설정

4-1. 초기 관리자 비밀번호 확인

sudo cat /var/lib/jenkins/secrets/initialAdminPassword

4-2. 웹 브라우저 접속

http://<서버IP>:8080

1. 초기 비밀번호 입력
2. "Install suggested plugins" 선택 (또는 jenkins_plugins.sh 스크립트 사용)
3. 관리자 계정 생성
4. Jenkins URL 설정 (http://jenkins.agency.go.kr:8080)

4-3. 자동화 스크립트

# 자동 설치 (비대화형)
sudo bash cicd/scripts/install/jenkins_install.sh

# 플러그인 자동 설치
sudo bash cicd/scripts/install/jenkins_plugins.sh

---

5. Java 버전 관리

Jenkins와 빌드 Java 버전이 다를 경우 도구 관리에서 JDK를 별도 등록한다.

# 시스템에 JDK 17, 21 병행 설치
# RHEL
sudo dnf install -y java-17-openjdk-devel java-21-openjdk-devel
sudo alternatives --list | grep java

# Ubuntu
sudo apt-get install -y openjdk-17-jdk openjdk-21-jdk
sudo update-alternatives --list java

Jenkins 관리 → Tools → JDK Installations:

• JDK17 → /usr/lib/jvm/java-17-openjdk
• JDK21 → /usr/lib/jvm/java-21-openjdk

---

6. Git 설정

# Jenkins 사용자로 Git 전역 설정
sudo -u jenkins git config --global user.email "jenkins@agency.go.kr"
sudo -u jenkins git config --global user.name "Jenkins CI"

# SSH 키 생성 (Git 서버 인증용)
sudo -u jenkins ssh-keygen -t ed25519 -C "jenkins@agency.go.kr" \
    -f /var/lib/jenkins/.ssh/id_ed25519 -N ""

# 공개키 출력 → Git 서버에 등록
sudo cat /var/lib/jenkins/.ssh/id_ed25519.pub

---

7. Maven / Gradle 도구 설정

Jenkins 관리 → Tools:

Maven

• Name: maven3
• Install automatically: ✓ (Version: 3.9.x)
• 또는 직접 경로: /usr/share/maven

Gradle

• Name: gradle8
• Install automatically: ✓ (Version: 8.x)

Node.js (NodeJS Plugin 설치 후)

• Name: nodejs20
• Version: 20.x LTS

---

8. 역방향 프록시 (Nginx)

내부망에서 80 포트로 접근하거나 HTTPS를 적용할 경우:

# /etc/nginx/conf.d/jenkins.conf
upstream jenkins {
    keepalive 32;
    server 127.0.0.1:8080 fail_timeout=0;
}

server {
    listen 80;
    server_name jenkins.agency.go.kr;

    location / {
        proxy_pass         http://jenkins;
        proxy_redirect     default;
        proxy_http_version 1.1;

        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   Connection        "";

        proxy_connect_timeout    90;
        proxy_send_timeout       90;
        proxy_read_timeout       90;
        proxy_buffering          off;
        proxy_request_buffering  off;
        proxy_max_temp_file_size 0;
    }
}

sudo nginx -t && sudo systemctl reload nginx

---

9. JCasC (Jenkins Configuration as Code) 적용

# JCasC 설정 파일 배포
sudo mkdir -p /var/lib/jenkins/casc_configs
sudo cp cicd/config/jenkins.yaml /var/lib/jenkins/casc_configs/
sudo chown -R jenkins:jenkins /var/lib/jenkins/casc_configs/

# 환경변수 설정 (jenkins 서비스 systemd override)
sudo mkdir -p /etc/systemd/system/jenkins.service.d/
cat <<'EOF' | sudo tee /etc/systemd/system/jenkins.service.d/casc.conf
[Service]
Environment="CASC_JENKINS_CONFIG=/var/lib/jenkins/casc_configs"
Environment="JENKINS_URL=http://jenkins.agency.go.kr:8080"
Environment="ITSM_URL=http://itsm.agency.go.kr:8000"
EOF

sudo systemctl daemon-reload
sudo systemctl restart jenkins

---

10. 백업 설정

# 주요 디렉터리 백업 (crontab 등록)
cat <<'EOF' | sudo tee /etc/cron.d/jenkins-backup
# Jenkins 일 2회 백업
0 2,14 * * * jenkins tar czf /backup/jenkins-$(date +\%Y\%m\%d-\%H\%M).tar.gz \
    /var/lib/jenkins/jobs \
    /var/lib/jenkins/casc_configs \
    /var/lib/jenkins/credentials.xml \
    2>/dev/null
# 30일 이전 백업 삭제
30 2 * * * find /backup -name "jenkins-*.tar.gz" -mtime +30 -delete
EOF

---

11. 문제 해결

Jenkins 시작 실패

# 로그 확인
sudo journalctl -u jenkins -n 100 --no-pager
sudo cat /var/log/jenkins/jenkins.log

# Java 버전 확인
java -version
sudo -u jenkins java -version

포트 충돌

# 8080 포트 사용 프로세스 확인
sudo ss -tlnp | grep 8080

# 포트 변경 (/etc/sysconfig/jenkins 또는 /etc/default/jenkins)
# RHEL
sudo sed -i 's/^HTTP_PORT=.*/HTTP_PORT=8090/' /etc/sysconfig/jenkins
# Ubuntu
sudo sed -i 's/^HTTP_PORT=.*/HTTP_PORT=8090/' /etc/default/jenkins

플러그인 설치 실패 (오프라인 환경)

# 플러그인 .hpi 파일을 직접 업로드
# Jenkins 관리 → Plugins → Advanced → Deploy Plugin
# 또는 /var/lib/jenkins/plugins/ 에 직접 복사 후 재시작
sudo cp plugins/*.hpi /var/lib/jenkins/plugins/
sudo systemctl restart jenkins