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 |

### 필수 패키지

```bash
# 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 저장소 추가

```bash
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 설치

```bash
sudo dnf install -y jenkins

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

### 2-3. 방화벽 설정

```bash
# 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)

```bash
# 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 저장소 추가

```bash
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 설치

```bash
sudo apt-get install -y jenkins

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

### 3-3. UFW 방화벽 설정

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

---

## 4. 초기 설정

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

```bash
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. 자동화 스크립트

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

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

---

## 5. Java 버전 관리

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

```bash
# 시스템에 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 설정

```bash
# 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를 적용할 경우:

```nginx
# /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;
    }
}
```

```bash
sudo nginx -t && sudo systemctl reload nginx
```

---

## 9. JCasC (Jenkins Configuration as Code) 적용

```bash
# 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. 백업 설정

```bash
# 주요 디렉터리 백업 (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 시작 실패

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

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

### 포트 충돌

```bash
# 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
```

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

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