springbatch-test/NEXUS_SETUP.md

# Nexus Repository 설정 가이드 (폐쇄망 환경)

폐쇄망 환경에서 내부 Nexus Repository Manager를 사용하기 위한 설정 가이드입니다.

## 목차

1. [Nexus Repository란?](#nexus-repository란)
2. [설정 방법](#설정-방법)
3. [프로젝트별 설정](#프로젝트별-설정)
4. [전역 설정](#전역-설정)
5. [인증 정보 관리](#인증-정보-관리)
6. [트러블슈팅](#트러블슈팅)

## Nexus Repository란?

Nexus Repository Manager는 Maven, Gradle 등의 빌드 도구가 사용하는 라이브러리를 캐싱하고 관리하는 Repository Manager입니다.

### 폐쇄망에서 Nexus를 사용하는 이유

- 외부 인터넷 접속이 불가능한 환경에서 라이브러리 관리
- 라이브러리 다운로드 속도 향상 (캐싱)
- 보안 정책 준수 (승인된 라이브러리만 사용)
- 내부 개발 라이브러리 배포

## 설정 방법

### 방법 1: 프로젝트별 설정 (권장)

프로젝트 단위로 Nexus를 설정합니다.

#### 1-1. gradle.properties 파일 생성

```bash
# gradle.properties.example을 복사
cp gradle.properties.example gradle.properties

# Windows
copy gradle.properties.example gradle.properties
```

#### 1-2. gradle.properties 수정

```properties
# Nexus 서버 정보
nexusUrl=http://nexus.your-company.com:8081
nexusUsername=your-username
nexusPassword=your-password
```

#### 1-3. build.gradle 수정

`build.gradle` 파일의 repositories 섹션에서:

```gradle
repositories {
    // 폐쇄망: Nexus 사용
    maven {
        url = "${nexusUrl}/repository/maven-public/"
        credentials {
            username = "${nexusUsername}"
            password = "${nexusPassword}"
        }
        allowInsecureProtocol = true  // HTTP 사용 시
    }

    // 인터넷 접속 가능 시: 주석 해제
    // mavenCentral()
}
```

### 방법 2: 전역 설정

모든 Gradle 프로젝트에 Nexus 설정을 적용합니다.

#### 2-1. init.gradle 파일 생성

**Windows:**
```cmd
mkdir %USERPROFILE%\.gradle
copy init.gradle.example %USERPROFILE%\.gradle\init.gradle
```

**Linux/Mac:**
```bash
mkdir -p ~/.gradle
cp init.gradle.example ~/.gradle/init.gradle
```

#### 2-2. init.gradle 수정

```gradle
allprojects {
    repositories {
        maven {
            url 'http://nexus.your-company.com:8081/repository/maven-public/'
            credentials {
                username 'your-username'
                password 'your-password'
            }
        }
    }
}
```

#### 2-3. 적용 확인

```bash
gradlew.bat dependencies --refresh-dependencies
```

## 프로젝트별 설정

### 1. gradle.properties를 사용한 설정

**장점:**
- 프로젝트별로 다른 Nexus 서버 사용 가능
- Git에서 제외 가능 (.gitignore)
- 환경별 설정 관리 용이

**gradle.properties:**
```properties
nexusUrl=http://nexus.company.com:8081
nexusUsername=developer
nexusPassword=secret123

# Repository URLs
nexusMavenPublic=${nexusUrl}/repository/maven-public/
nexusMavenReleases=${nexusUrl}/repository/maven-releases/
nexusMavenSnapshots=${nexusUrl}/repository/maven-snapshots/
```

**build.gradle:**
```gradle
repositories {
    maven {
        url = "${nexusMavenPublic}"
        credentials {
            username = "${nexusUsername}"
            password = "${nexusPassword}"
        }
    }
}
```

### 2. settings.gradle 설정

Plugin 저장소도 Nexus를 사용하도록 설정:

```gradle
pluginManagement {
    repositories {
        maven {
            url = "${nexusUrl}/repository/gradle-plugins/"
            credentials {
                username = "${nexusUsername}"
                password = "${nexusPassword}"
            }
            allowInsecureProtocol = true
        }
    }
}
```

## 전역 설정

### 1. init.gradle 사용

모든 Gradle 프로젝트에 자동으로 적용됩니다.

**위치:**
- Windows: `%USERPROFILE%\.gradle\init.gradle`
- Linux/Mac: `~/.gradle/init.gradle`

**예제:**
```gradle
allprojects {
    repositories {
        all { ArtifactRepository repo ->
            if (repo instanceof MavenArtifactRepository) {
                def url = repo.url.toString()
                if (url.startsWith('https://repo.maven.apache.org') ||
                    url.startsWith('https://jcenter')) {
                    remove repo
                }
            }
        }

        maven {
            url 'http://nexus.company.com:8081/repository/maven-public/'
            credentials {
                username 'nexus-user'
                password 'nexus-pass'
            }
            allowInsecureProtocol = true
        }
    }
}
```

### 2. gradle.properties 전역 설정

**위치:**
- Windows: `%USERPROFILE%\.gradle\gradle.properties`
- Linux/Mac: `~/.gradle/gradle.properties`

```properties
nexusUrl=http://nexus.company.com:8081
nexusUsername=your-username
nexusPassword=your-password
```

## 인증 정보 관리

### 1. gradle.properties 사용 (권장)

```properties
# .gitignore에 추가하여 보안 유지
nexusUsername=username
nexusPassword=password
```

**.gitignore에 추가:**
```
gradle.properties
```

### 2. 환경 변수 사용

**build.gradle:**
```gradle
repositories {
    maven {
        url = "${nexusUrl}/repository/maven-public/"
        credentials {
            username = System.getenv("NEXUS_USERNAME")
            password = System.getenv("NEXUS_PASSWORD")
        }
    }
}
```

**환경 변수 설정:**

Windows:
```cmd
set NEXUS_USERNAME=your-username
set NEXUS_PASSWORD=your-password
```

Linux/Mac:
```bash
export NEXUS_USERNAME=your-username
export NEXUS_PASSWORD=your-password
```

### 3. Gradle Credentials Plugin 사용

고급 인증 관리가 필요한 경우:

```gradle
plugins {
    id 'nu.studer.credentials' version '3.0'
}

repositories {
    maven {
        url = "${nexusUrl}/repository/maven-public/"
        credentials(PasswordCredentials) {
            username = credentials.nexusUsername
            password = credentials.nexusPassword
        }
    }
}
```

## Nexus Repository 구성

일반적인 Nexus Repository 구성:

### 1. Maven Public (Group Repository)

모든 Maven 저장소를 통합한 그룹:
```
URL: http://nexus.company.com:8081/repository/maven-public/
```

**포함 저장소:**
- maven-central (Proxy)
- maven-releases (Hosted)
- maven-snapshots (Hosted)

### 2. Maven Central Proxy

Maven Central을 캐싱하는 프록시:
```
URL: http://nexus.company.com:8081/repository/maven-central/
```

### 3. Maven Releases

내부 릴리즈 라이브러리:
```
URL: http://nexus.company.com:8081/repository/maven-releases/
```

### 4. Maven Snapshots

내부 스냅샷 라이브러리:
```
URL: http://nexus.company.com:8081/repository/maven-snapshots/
```

### 5. Gradle Plugins

Gradle 플러그인용 저장소:
```
URL: http://nexus.company.com:8081/repository/gradle-plugins/
```

## SSL/TLS 설정

### HTTPS 사용 (권장)

```gradle
repositories {
    maven {
        url = "https://nexus.company.com/repository/maven-public/"
        credentials {
            username = "${nexusUsername}"
            password = "${nexusPassword}"
        }
        // allowInsecureProtocol = false (기본값)
    }
}
```

### 자체 서명 인증서 신뢰

**gradle.properties:**
```properties
systemProp.javax.net.ssl.trustStore=/path/to/truststore.jks
systemProp.javax.net.ssl.trustStorePassword=changeit
```

**또는 JVM 옵션:**
```properties
org.gradle.jvmargs=-Djavax.net.ssl.trustStore=/path/to/truststore.jks \
                   -Djavax.net.ssl.trustStorePassword=changeit
```

### HTTP 사용 (비권장)

보안상 권장하지 않지만, 내부망에서 사용:

```gradle
repositories {
    maven {
        url = "http://nexus.company.com:8081/repository/maven-public/"
        allowInsecureProtocol = true  // 필수!
        credentials {
            username = "${nexusUsername}"
            password = "${nexusPassword}"
        }
    }
}
```

## 빌드 명령어

### 의존성 새로고침

```bash
# Windows
gradlew.bat clean build --refresh-dependencies

# Linux/Mac
./gradlew clean build --refresh-dependencies
```

### Nexus 연결 디버그

```bash
gradlew.bat dependencies --debug --stacktrace
```

### 캐시 정리

```bash
# Gradle 캐시 정리
gradlew.bat clean --no-daemon
rm -rf %USERPROFILE%\.gradle\caches
```

## 트러블슈팅

### 1. 인증 실패

**에러:**
```
> Could not resolve all dependencies
> HTTP 401 Unauthorized
```

**해결:**
- Nexus 사용자명/비밀번호 확인
- Nexus 사용자 권한 확인
- gradle.properties 파일 위치 확인

### 2. SSL 인증서 오류

**에러:**
```
> PKIX path building failed
> unable to find valid certification path
```

**해결:**

**방법 1: 인증서 신뢰 저장소에 추가**
```bash
keytool -import -alias nexus -keystore %JAVA_HOME%/lib/security/cacerts \
        -file nexus-cert.crt
```

**방법 2: gradle.properties에 설정**
```properties
systemProp.javax.net.ssl.trustStore=/path/to/truststore.jks
systemProp.javax.net.ssl.trustStorePassword=changeit
```

**방법 3: HTTP 사용 (임시)**
```gradle
allowInsecureProtocol = true
```

### 3. 의존성 다운로드 실패

**에러:**
```
> Could not resolve com.example:library:1.0
```

**해결:**
1. Nexus에 해당 라이브러리가 있는지 확인
2. Nexus Proxy가 외부에서 다운로드했는지 확인
3. 캐시 정리 후 재시도:
```bash
gradlew.bat clean build --refresh-dependencies
```

### 4. 느린 빌드 속도

**해결:**

**gradle.properties 최적화:**
```properties
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.daemon=true
```

### 5. HTTP/HTTPS 프로토콜 오류

**에러:**
```
> Using insecure protocols with repositories is not allowed
```

**해결:**

Gradle 7.0 이상에서는 HTTP를 명시적으로 허용해야 함:
```gradle
maven {
    url = "http://nexus.company.com:8081/repository/maven-public/"
    allowInsecureProtocol = true  // 추가 필수
}
```

## 보안 체크리스트

- [ ] HTTPS 사용 (HTTP는 가급적 피함)
- [ ] gradle.properties를 .gitignore에 추가
- [ ] 인증 정보를 환경 변수로 관리
- [ ] Nexus 사용자 최소 권한 부여
- [ ] 정기적인 비밀번호 변경
- [ ] SSL 인증서 유효성 검증

## 예제 파일 구조

```
springbatch-test/
├── build.gradle                    # Nexus 저장소 설정
├── settings.gradle                 # Plugin 저장소 설정
├── gradle.properties               # Nexus 인증 정보 (Git 제외)
├── gradle.properties.example       # 템플릿 (Git 포함)
├── init.gradle.example             # 전역 설정 템플릿
└── .gitignore                      # gradle.properties 제외
```

## 참고 자료

- [Nexus Repository Manager Documentation](https://help.sonatype.com/repomanager3)
- [Gradle Repository Configuration](https://docs.gradle.org/current/userguide/declaring_repositories.html)
- [Gradle Build Cache](https://docs.gradle.org/current/userguide/build_cache.html)

## 문의

Nexus 관련 문제 발생 시:
1. 사내 DevOps 팀 문의
2. Nexus 관리자에게 저장소 권한 확인 요청
3. 네트워크 팀에 방화벽 설정 확인 요청