springbatch-test/NEXUS_SETUP.md

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

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

목차

1. Nexus Repository란?
2. 설정 방법
3. 프로젝트별 설정
4. 전역 설정
5. 인증 정보 관리
6. 트러블슈팅

Nexus Repository란?

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

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

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

설정 방법

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

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

1-1. gradle.properties 파일 생성

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

# Windows
copy gradle.properties.example gradle.properties

1-2. gradle.properties 수정

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

1-3. build.gradle 수정

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

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:

mkdir %USERPROFILE%\.gradle
copy init.gradle.example %USERPROFILE%\.gradle\init.gradle

Linux/Mac:

mkdir -p ~/.gradle
cp init.gradle.example ~/.gradle/init.gradle

2-2. init.gradle 수정

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

2-3. 적용 확인

gradlew.bat dependencies --refresh-dependencies

프로젝트별 설정

1. gradle.properties를 사용한 설정

장점:

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

gradle.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:

repositories {
    maven {
        url = "${nexusMavenPublic}"
        credentials {
            username = "${nexusUsername}"
            password = "${nexusPassword}"
        }
    }
}

2. settings.gradle 설정

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

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

예제:

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

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

인증 정보 관리

1. gradle.properties 사용 (권장)

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

.gitignore에 추가:

gradle.properties

2. 환경 변수 사용

build.gradle:

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

환경 변수 설정:

Windows:

set NEXUS_USERNAME=your-username
set NEXUS_PASSWORD=your-password

Linux/Mac:

export NEXUS_USERNAME=your-username
export NEXUS_PASSWORD=your-password

3. Gradle Credentials Plugin 사용

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

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 사용 (권장)

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

자체 서명 인증서 신뢰

gradle.properties:

systemProp.javax.net.ssl.trustStore=/path/to/truststore.jks
systemProp.javax.net.ssl.trustStorePassword=changeit

또는 JVM 옵션:

org.gradle.jvmargs=-Djavax.net.ssl.trustStore=/path/to/truststore.jks \
                   -Djavax.net.ssl.trustStorePassword=changeit

HTTP 사용 (비권장)

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

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

빌드 명령어

의존성 새로고침

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

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

Nexus 연결 디버그

gradlew.bat dependencies --debug --stacktrace

캐시 정리

# 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: 인증서 신뢰 저장소에 추가

keytool -import -alias nexus -keystore %JAVA_HOME%/lib/security/cacerts \
        -file nexus-cert.crt

방법 2: gradle.properties에 설정

systemProp.javax.net.ssl.trustStore=/path/to/truststore.jks
systemProp.javax.net.ssl.trustStorePassword=changeit

방법 3: HTTP 사용 (임시)

allowInsecureProtocol = true

3. 의존성 다운로드 실패

에러:

> Could not resolve com.example:library:1.0

해결:

1. Nexus에 해당 라이브러리가 있는지 확인
2. Nexus Proxy가 외부에서 다운로드했는지 확인
3. 캐시 정리 후 재시도:

gradlew.bat clean build --refresh-dependencies

4. 느린 빌드 속도

해결:

gradle.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를 명시적으로 허용해야 함:

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
• Gradle Repository Configuration
• Gradle Build Cache

문의

Nexus 관련 문제 발생 시:

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