젠킨스 초기 설정 가이드 - 비밀번호, 동시성, 이메일, 환경변수

젠킨스를 설치하고 나면 본격적으로 사용하기 전에 몇 가지 초기 설정이 필요하다. 이 포스트에서는 실무에서 꼭 해두어야 할 설정들을 정리한다.

1. 초기 관리자 비밀번호

http://localhost:8080 에 접속하면 초기 비밀번호를 물어본다. 아래 명령어로 확인할 수 있다.

cat ~/.jenkins/secrets/initialAdminPassword

비밀번호를 물어보지 않는 경우

만약 젠킨스가 초기 비밀번호를 물어보지 않는다면 ~/.jenkins/config.xml 파일을 열어서 보안 설정을 잠시 비활성화할 수 있다.

<useSecurity>true</useSecurity>

위 항목을 false로 변경하고 젠킨스를 재시작한다.

brew services restart jenkins-lts

재시작 후 접속하면 비밀번호 없이 들어갈 수 있고, 이후 보안 설정을 다시 활성화하면 된다.

2. 동시 실행(Executor) 설정

젠킨스는 기본적으로 여러 개의 잡을 동시에 실행할 수 있다. 기본값은 2개로 설정되어 있다.

하지만 대부분의 배포 작업은 상당히 무겁기 때문에 동시 실행을 1개로 제한하는 게 바람직하다.

젠킨스 관리 → 시스템 설정 에서 # of executors 값을 변경하면 된다.

agent와 deadlock 주의

Jenkinsfile에서 agent any 를 사용하면 트리거가 걸릴 때마다 아무 에이전트나 할당되어 동시에 실행되므로, executor 수가 부족할 경우 deadlock이 발생할 수 있다.

따라서 executor 수가 모자라다면 agent를 명확하게 지정해서 deadlock을 방지해야 한다.

3. 이메일 알림 설정

빌드 실패나 성공 시 이메일 알림을 받으려면 SMTP 설정이 필요하다. Gmail을 사용하는 경우 아래와 같이 설정한다.

앱 비밀번호 설정

Gmail에서 2단계 인증을 사용 중이라면 일반 비밀번호 대신 앱 비밀번호를 생성해서 사용해야 한다.

Google 계정 → 보안 → 앱 비밀번호 에서 생성할 수 있다.

2단계 인증을 사용하지 않는 경우, 보안 수준이 낮은 앱 액세스 설정을 활성화해야 한다.

4. 시스템 환경변수 설정

젠킨스에서 시스템 명령어를 사용하려면 PATH 환경변수를 설정해주어야 한다.

젠킨스 관리 → 시스템 설정 → Environment Variables 를 체크하고, 환경변수를 추가한다.

• 이름: PATH+EXTRA
• 값: /usr/local/bin

PATH+EXTRA 형식으로 지정하면 기존 PATH에 값이 추가된다. 이때 ~ 같은 홈 디렉토리 표기는 사용할 수 없으며, 반드시 절대 경로로 입력해야 한다.

현재 서버에서 사용 중인 PATH를 확인하려면:

echo $PATH

이 결과에 나온 경로들을 젠킨스에도 등록해주면 된다.

nvm 권한 문제 해결

nvm은 보통 시스템 유저(예: ec2-user)의 홈 디렉토리에 설치된다. jenkins 유저는 이 경로에 접근 권한이 없어서 node를 찾지 못하는 경우가 있다.

먼저 jenkins 유저의 쉘 설정을 확인해보자.

grep jenkins /etc/passwd

마지막에 /bin/false 로 끝난다면 jenkins 유저는 interactive shell이 없다는 의미다. Non-Interactive Shell의 경우 ~/.bashrc 나 ~/.bash_profile 이 실행되지 않기 때문에 $PATH가 실제와 다를 수 있다.

해결 방법: jenkins 유저를 ec2-user 그룹에 추가하고, ec2-user 홈 디렉토리 권한을 변경한다.

# jenkins 유저를 ec2-user 그룹에 추가
sudo usermod -aG ec2-user jenkins

# ec2-user 홈 디렉토리 권한 변경 (그룹에 read, execute 허용)
sudo chmod -R 750 /home/ec2-user

750 권한은 소유자(rwx), 그룹(r-x), 기타(---)를 의미한다. 그룹에 속한 jenkins 유저가 해당 디렉토리를 읽고 실행할 수 있게 된다.

변경 후 젠킨스를 재시작하면 적용된다.

참고

이 포스트는 젠킨스 완벽 가이드 시리즈의 일부다. 플러그인 설정, 인증 정보 관리 등 다른 주제는 해당 가이드에서 확인할 수 있다.