hgzero/deployment/jenkins/JENKINS_SETUP.md

# Jenkins Pipeline 설정 가이드

## 개요
GitHub Actions가 막혀 있을 때 Jenkins를 사용하여 HGZero 백엔드 서비스를 빌드하고 배포하는 가이드입니다.

## 전제 조건

### 1. Jenkins 서버 요구사항
- Jenkins 2.x 이상
- Docker가 설치되어 있어야 함
- Kustomize CLI 다운로드 가능한 환경
- 인터넷 연결 (Docker Hub, Azure Container Registry, GitHub 접근)

### 2. 필수 Jenkins 플러그인
다음 플러그인들이 설치되어 있어야 합니다:
- Pipeline (기본 포함)
- Git Plugin
- Docker Pipeline Plugin
- SonarQube Scanner Plugin (선택사항)
- Credentials Plugin (기본 포함)

## Jenkins 설정 단계

### 1단계: Credentials 설정

Jenkins 관리 → Manage Credentials → Global credentials에서 다음 credential들을 추가합니다:

#### 1.1 ACR Credentials
- **ID**: `acr-credentials`
- **Type**: Username with password
- **Username**: Azure Container Registry 사용자명
- **Password**: Azure Container Registry 비밀번호
- **Description**: Azure Container Registry Credentials

#### 1.2 Docker Hub Credentials
- **ID**: `dockerhub-credentials`
- **Type**: Username with password
- **Username**: Docker Hub 사용자명
- **Password**: Docker Hub 비밀번호 또는 Access Token
- **Description**: Docker Hub Credentials (rate limit 방지용)

#### 1.3 SonarQube Token (선택사항)
- **ID**: `sonar-token`
- **Type**: Secret text
- **Secret**: SonarQube authentication token
- **Description**: SonarQube Token

#### 1.4 Git Credentials
- **ID**: `git-credentials`
- **Type**: Username with password
- **Username**: GitHub 사용자명
- **Password**: GitHub Personal Access Token (repo 권한 필요)
- **Description**: GitHub Credentials for Manifest Repository

> **중요**: GitHub Personal Access Token 생성 시 다음 권한이 필요합니다:
> - `repo` (Full control of private repositories)

### 2단계: JDK 21 설정

Jenkins 관리 → Global Tool Configuration → JDK에서:
1. "Add JDK" 클릭
2. **Name**: `JDK21`
3. "Install automatically" 체크
4. Install from adoptium.net 선택
5. Version: jdk-21.x.x 선택

> **참고**: 또는 Jenkins 서버에 JDK 21이 이미 설치되어 있다면, 설치 경로를 지정할 수 있습니다.

### 3단계: SonarQube 서버 설정 (선택사항)

SonarQube 분석을 사용하려면:

Jenkins 관리 → Configure System → SonarQube servers에서:
1. "Add SonarQube" 클릭
2. **Name**: `SonarQube`
3. **Server URL**: SonarQube 서버 URL
4. **Server authentication token**: 앞서 생성한 `sonar-token` credential 선택

### 4단계: Pipeline Job 생성

1. Jenkins 메인 화면에서 "New Item" 클릭
2. Job 이름 입력 (예: `hgzero-backend-pipeline`)
3. "Pipeline" 선택
4. "OK" 클릭

Pipeline 설정:
1. **General**
   - "This project is parameterized" 체크 (자동으로 Jenkinsfile의 parameters가 인식됨)

2. **Pipeline**
   - **Definition**: Pipeline script from SCM
   - **SCM**: Git
   - **Repository URL**: `https://github.com/hjmoons/HGZero.git` (또는 실제 저장소 URL)
   - **Credentials**: 필요시 Git credentials 선택
   - **Branch Specifier**: `*/main` (또는 원하는 브랜치)
   - **Script Path**: `Jenkinsfile`

3. "Save" 클릭

## Pipeline 실행

### 수동 실행
1. 생성한 Pipeline Job 선택
2. "Build with Parameters" 클릭
3. 파라미터 선택:
   - **ENVIRONMENT**: `dev`, `staging`, 또는 `prod` 선택
   - **SKIP_SONARQUBE**: `true` (건너뛰기) 또는 `false` (실행)
4. "Build" 클릭

### Pipeline 동작 흐름

```
1. Checkout
   └─> Git 저장소에서 코드 체크아웃

2. Setup Java
   └─> JDK 21 환경 설정

3. Load Environment Variables
   └─> .github/config/deploy_env_vars_{환경} 파일에서 환경변수 로드

4. Build with Gradle
   └─> ./gradlew build -x test 실행 (JAR 파일 생성)

5. SonarQube Analysis (선택사항)
   └─> 각 서비스별 테스트 및 코드 품질 분석

6. Archive Artifacts
   └─> 생성된 JAR 파일을 Jenkins에 보관

7. Docker Build & Push
   └─> 각 서비스별 Docker 이미지 빌드 및 ACR에 푸시

8. Update Manifest Repository
   └─> hgzero-manifest 저장소의 Kustomize 파일 업데이트
   └─> ArgoCD가 자동으로 배포 감지
```

## 빌드 결과 확인

### 성공 시
- Console Output에 "✅ Pipeline completed successfully!" 메시지 표시
- Environment와 Image Tag 정보 출력
- Manifest 저장소가 업데이트됨
- ArgoCD가 자동으로 새 이미지를 배포

### 실패 시
- Console Output에 "❌ Pipeline failed!" 메시지 표시
- 실패한 Stage와 에러 메시지 확인
- Workspace가 자동으로 정리됨

## 환경별 설정

### Dev 환경
```bash
ENVIRONMENT: dev
```
- 개발 환경에 배포
- 빠른 반복 개발용

### Staging 환경
```bash
ENVIRONMENT: staging
```
- 스테이징 환경에 배포
- 프로덕션 배포 전 최종 검증

### Production 환경
```bash
ENVIRONMENT: prod
```
- 프로덕션 환경에 배포
- **주의**: 프로덕션 배포는 신중하게 진행

## 트러블슈팅

### 문제 1: Gradle 빌드 실패
**증상**: `./gradlew build` 실패

**해결방법**:
- Console Output에서 에러 로그 확인
- Java 버전이 21인지 확인
- Gradle wrapper 권한 확인: `chmod +x gradlew`

### 문제 2: Docker 로그인 실패
**증상**: Docker login 실패

**해결방법**:
- Jenkins Credentials에 ACR credentials가 올바르게 설정되었는지 확인
- Azure Container Registry URL이 `acrdigitalgarage02.azurecr.io`인지 확인
- Credential ID가 정확히 `acr-credentials`인지 확인

### 문제 3: Git clone 실패 (Manifest Repository)
**증상**: hgzero-manifest 저장소 clone 실패

**해결방법**:
- GitHub Personal Access Token이 유효한지 확인
- Token에 `repo` 권한이 있는지 확인
- Credential ID가 정확히 `git-credentials`인지 확인

### 문제 4: Kustomize 설치 실패
**증상**: Kustomize 다운로드 실패

**해결방법**:
- Jenkins 서버에서 인터넷 연결 확인
- curl 명령어가 사용 가능한지 확인
- 필요시 Kustomize를 미리 설치하고 PATH에 추가

## 보안 고려사항

1. **Credentials 관리**
   - 모든 비밀번호와 토큰은 Jenkins Credentials로 관리
   - Pipeline 코드에 절대 하드코딩하지 않음

2. **Git Credentials**
   - Personal Access Token 사용 (비밀번호 사용 금지)
   - 최소 권한 원칙 적용

3. **Docker Registry**
   - ACR 접근은 Service Principal 또는 관리되는 자격 증명 사용 권장

## 추가 참고사항

### Webhook 설정 (선택사항)
GitHub push 이벤트 시 자동으로 빌드를 트리거하려면:

1. Jenkins Job → Configure → Build Triggers
2. "GitHub hook trigger for GITScm polling" 체크
3. GitHub 저장소 → Settings → Webhooks
4. Jenkins URL 추가: `http://{jenkins-url}/github-webhook/`

### 알림 설정 (선택사항)
빌드 결과를 이메일이나 Slack으로 받으려면:

- Email: Email Extension Plugin 설치 및 설정
- Slack: Slack Notification Plugin 설치 및 설정

## 지원 서비스

현재 Pipeline에서 빌드하는 서비스:
- `user`: 사용자 관리 서비스
- `meeting`: 회의 관리 서비스
- `stt`: 음성-텍스트 변환 서비스
- `ai`: AI 처리 서비스
- `notification`: 알림 서비스

## 관련 파일

- `Jenkinsfile`: Pipeline 정의 파일
- `.github/config/deploy_env_vars_{환경}`: 환경별 변수 파일
- `deployment/container/Dockerfile-backend`: 백엔드 Dockerfile
- `hgzero-manifest` 저장소: Kubernetes 매니페스트 파일

## 문의

Pipeline 관련 문제가 발생하면 Jenkins Console Output을 확인하고, 필요시 DevOps 팀에 문의하세요.