로컬 환경에서 도커 젠킨스(Jenkins) 컨테이너로 깃허브 레파지토리 클론 테스트하기(with Ngrok) | 로컬 젠킨스 설명 포함

💡 들어가기 전에

 

• 도커의 jenkins 공식이미지는 Deprecated 되었다.
• 나의 경우 자바 11 버전을 사용하기 때문에 lts-jdk 11 버전을 사용했다.
• LTS(Long Term Support)는 장기 지원 버전이란 의미로, 일반적인 경우보다 장기간에 걸쳐 지원하도록 특별히 고안된 소프트웨어의 버전 또는 에디션이다.

 

 

 

📦 준비하기

wonyong@Wonyongui-MacBookAir:~$docker volume create jenkins 
jenkins

• 볼륨 사용을 위해 jenkins 볼륨을 생성했다.
• 이 글은 도커 젠킨스를 기준으로 설명하지만 컨테이너로 젠킨스를 실행하는 점을 제외하고는 로컬에서 설치하는 것과 크게 다르지 않다.
  • 로컬에서 젠키스를 설치하고 싶다면, https://www.jenkins.io/에 접속하여 운영체제에 맞게 설치하면 된다. 

 

📌 도커로 jenkins 컨테이너 실행하기

docker run -d --name jenkins -v jenkins:/var/jenkins_home -p 18080:8080 -p 50000:50000 --restart=on-failure -e TZ=Asia/Seoul jenkins/jenkins:lts-jdk11

• -d는 백그라운드에서 실행한다는 의미이다.
• --name은 생성할 컨테이너의 이름을 지정한다.
• -v는 볼륨 설정이다. 위에서 생성한 볼륨 jenkins와 컨테이너 내부 경로를 매핑해 주었다.
• -p 포트는 로컬의 18080 포트와 컨테이너 내부의 8080 포트를 연결했다. 50000 포트도 마찬가지이다.
  • 컨테이너가 아닌 로컬에 직접 설치했다면 아래의 mac 기준 젠킨스 포트 변경 방법을 참고하자.

8080 포트

• 8080 포트는 기본적으로 Jenkins의 웹 인터페이스에 대한 접근을 허용하기 위해 사용된다.
• 이 포트를 통해 Jenkins 서버에 접속하여 빌드, 배포, 관리 등의 작업을 수행할 수 있다.

50000 포트

• Jenkins 에이전트(또는 슬레이브)와 마스터 간의 통신을 위한 포트이다.
• Jenkins 에이전트는 마스터 서버에서 작업을 받아 실행하고, 결과를 마스터 서버로 보고하는 역할을 한다.

--restart=on-failure

• 이 옵션은 도커 컨테이너가 실패한 경우 자동으로 다시 시작하도록 설정하는 것을 의미한다.
• 컨테이너가 비정상적으로 종료되었을 때 자동으로 재시작하여 서비스의 지속성을 유지할 수 있다.

-e TZ=Asia/Seoul

• 이 옵션은 도커 컨테이너 내부에서 사용할 타임존을 설정하는 것을 의미한다.
• 여기서는 "Asia/Seoul"로 타임존을 설정하였으며, 서울 시간대로 컨테이너 내부의 시간을 설정한다.

 

⌨️ mac 기준 젠킨스 포트 변경 방법

wonyonghwang@Wonyongs-MacBook-Pro ~ % cd /usr/local/opt/jenkins
wonyonghwang@Wonyongs-MacBook-Pro jenkins % ls
INSTALL_RECEIPT.json		homebrew.jenkins.service	libexec
bin				homebrew.mxcl.jenkins.plist

• mac 기준 젠킨스의 포트를 변경하기 위해서는 위의 경로로 들어가 homebrew.mxcl.jenkins.plist를 수정하면 된다.
• 만약 homebrew.mxcl.jenkins.plist가 다른 경로에 설치된 경우 find / -name jenkins.plist 명령어로 찾아보자.
  • 아마 m 시리즈 맥북을 사용한다면 /opt/homebrew/opt/jenkins에 있을 것이다.
• 리눅스 기반 다른 운영체제인 경우는 find / -name jenkins.service로 파일을 찾고 해당 파일에서 수정해야 한다.

 

wonyonghwang@Wonyongs-MacBook-Pro jenkins % vi homebrew.mxcl.jenkins.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>KeepAlive</key>
        <true/>
        <key>Label</key>
        <string>homebrew.mxcl.jenkins</string>
        <key>LimitLoadToSessionType</key>
        <array>
                <string>Aqua</string>
                <string>Background</string>
                <string>LoginWindow</string>
                <string>StandardIO</string>
                <string>System</string>
        </array>
        <key>ProgramArguments</key>
        <array>
                <string>/usr/local/opt/jenkins/bin/jenkins</string>
                <string>--httpListenAddress=127.0.0.1</string>
                <string>--httpPort=8080</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardErrorPath</key>
        <string>/usr/local/var/log/jenkins/error.log</string>
        <key>StandardOutPath</key>
        <string>/usr/local/var/log/jenkins/output.log</string>
</dict>
</plist>

• vi 명령어를 통해 들어가 <string>--httpPort=8080</string> 이 부분을 원하는 포트로 수정하면 된다.

 

📌 젠킨스 컨테이너 접속

• 젠킨스 컨테이너를 접속하려면 위에서 도커 컨테이너와 매핑한 로컬 PC의 포트번호를 주소창에 입력한다.
  • 나의 경우에는 localhost:18080이다. 브라우저 주소창에 입력한다.
  • 로컬 젠킨스도 마찬가지이다. 설정한 포트로 입력하여 접속하면 된다.
• jenkins에 처음 접속하면 초기 비밀번호를 입력해야 한다.

 

⌨️ 초기 비밀번호 확인

방법 1)

dokcer logs jenkins(컨테이너 명)

• 나는 docker run 명령어를 통해 -d 옵션을 사용하여 백그라운드로 실행하여 컨테이너 실행 로그를 볼 수 없었다.
• 따라서 간단히 확인하기 위해 컨테이너의 로그를 확인하는 명령어인 docker logs를 사용했다.

 

방법 2)

docker exec -it jenkins /bin/bash
cat /var/jenkins_home/secrets/initialAdminPassword

• 위와 같이 컨테이너 내부로 접속하여 직접 확인하는 방법도 있다.
• 만약 MacOS에 직접 설치했다면 /User/<user명>/.jenkins/secret/initialAdminPassword에 있을 것이다.

 

• 비밀번호를 입력하면 플러그인 설치페이지가 나오는데 기본적으로 젠킨스에서 권장하는 플러그인으로 설치했다.(왼쪽 클릭)

 

• 왼쪽 버튼을 클릭하면 설치가 진행된다.

 

• 초기 Admin 유저를 생성한다.

 

• jenkins URL을 설정한다.
• AWS 등의 인스턴스 서버로 젠킨스를 설치하면 해당 인스턴스 주소가 나온다고 한다.
• 나는 로컬에서 테스트를 진행하니 그대로 두겠다.

 

로그인 시

• 위에서 만든 계정으로 로그인할 수 있다.

 

⌨️ 스프링부트 서버 세팅

• 젠킨스용 서버를 하나 만들어준다.
• localhost:8080으로 접속하면 get 요청을 기본으로 위의 리턴 문자열이 화면에 출력된다.

 

⌨️ github Repository와 연결

• 테스트용 깃허브 레파지토리를 생성한다.
• 레파지토리 접근 권한은 private로 했는데 그 이유는 실무에서는 private 레파지토리를 적용할 것이 분명하기 때문이다.
  • 아래에 설명하겠지만 Private 레파지토리는 Public 레파지토리와 젠킨스를 설정할 때 약간 다른 부분이 있다.
  • Public으로 설정하여 테스트한 대부분의 블로그 글만 보고 따라 하면 에러가 난다.

 

⌨️ 로컬 레파지토리와 연결

Initialized empty Git repository in /Users/wonyong/study/jenkinsTest/.git/
wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$git remote add origin git@github.com:wonyongg/jenkinsTest.git
wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$git add .
wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$git commit -m "first commit"
[main (root-commit) c730eb8] first commit
 11 files changed, 464 insertions(+)
 create mode 100644 forJenkins/.gitignore
 create mode 100644 forJenkins/build.gradle
 create mode 100644 forJenkins/gradle/wrapper/gradle-wrapper.jar
 create mode 100644 forJenkins/gradle/wrapper/gradle-wrapper.properties
 create mode 100755 forJenkins/gradlew
 create mode 100644 forJenkins/gradlew.bat
 create mode 100644 forJenkins/settings.gradle
 create mode 100644 forJenkins/src/main/java/test/ForJenkinsApplication.java
 create mode 100644 forJenkins/src/main/java/test/MainController.java
 create mode 100644 forJenkins/src/main/resources/application.properties
 create mode 100644 forJenkins/src/test/java/test/ForJenkinsApplicationTests.java
wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$git push origin main

• 로컬 레파지토리와 연결하려면 …or create a new repository on the command line과 위 내용을 참고하여 따라하면 된다.

 

• 정상적으로 연결되었다.

 

📖 본격적인 테스트 시작

순서는 이렇다.

1. 깃허브 토큰 얻기
2. 젠킨스 기본 설정
3. 깃허브 레파지토리와 젠킨스 연결
4. Ngrok 설정
5. 깃허브 레파지토리 웹훅 설정
6. 테스트 성공 과정 : 로컬에서 커밋 & 푸시한다 -> 로컬 레파지토리에 웹훅이 젠킨스에게 신호를 보낸다. -> 젠킨스가 빌드를 진행한다.

 

📌 깃허브 토큰 얻기

• User - Settings에 들어간다.
• Developer settings에 들어간다.

 

• Personalaccess tokens - Tokens (classic)에 들어간다.
• Generate new Token - Generate new token (classic)에 들어간다.

 

• Note(token 발급 목적 기록)과  Expiration을 설정한다.(자유임)
• repo , admin:repo_hook을 체크한다.
• 토큰을 발행한다.

 

• 토큰을 복사한다.
• 참고로 이 토큰은 페이지를 나가면 다시는 볼 수 없으므로 제대로 복사하자.

 

📌 젠킨스 기본 설정

• 젠킨스 대시보드에서 Jenkins 관리를 클릭한다.
• System Configuration -> System을 클릭한다.

 

 

• Add Github Server - Github Server를 클릭한다.

 

• 이름을 정하고, API URL은 그대로 둔다.
• Credentials에는 Add - Jenkins를 클릭한다.

 

Crederntial - Secret test

• Kind를 Secret test로 선택한다면 public 레파지토리에서는 그대로 빌드 시 Credential 정보로 사용할 수 있다.
  • Secret에 위에서 복사한 깃허브 토큰 값을 넣는다.
  • ID, Description은 자유이다. 맘대로 적는다.
   

• 이제 Credentials를 위에서 정한 ID명으로 고를 수 있다.
  • 이 작업을 처음 할 당시에는 secret text로 할 경우 private 레파지토리에 사용할 수 없다는 걸 모르고 secret text로 Credential을 만들었다. private 레파지토리에 대응하는 방법은 아래에 설명해 놓았다.

 

• 오른쪽 하단에 Test connection을 클릭하여 Credentials가 유효한지 확인할 수 있다.
• 이제 Apply - Save(저장)을 누른다.

 

📌 깃허브 레파지토리와 젠킨스 연결

• 이제 깃허브 레파지토리와 연결해 보자.
• 새로운 Item을 클릭한다.

 

• item 이름을 만들고 Freestyle project로 설정 후 OK를 누른다.
  • 여기는 깃허브 클론 테스트가 주 목적이니 가장 간단한 Freestyle project를 골랐다.
• 여러 설정이 있는데 다 건너뛰고 필요한 기능만 설정하겠다.

 

• 맨 위 Github project에서 Project Url을 입력한다.

 

• 소스 코드 관리에서 Git을 누른다.
• Repository URL에는 위의 Url과 동일한 Url을 적고
• Credential은 Add - Jenkins를 클릭하여 등록해 준다.
• Branches to build에서 브랜치 명을 원하는 대로 수정해 준다.
  • 만약 메인 브랜치가 master가 아니라 main이라면 main으로 수정해 주자.

 

• 위에서 언급한 내용이다. 여기서 Public 레파지토리라면 위에 Credential을 설정한 것처럼 Secret text로 Credential을 등록하면 되지만, 내가 만든 jenkinsTest는 Private 레파지토리이므로 위와 같은 에러가 발생했다.

 

🚒 에러 핸들링

• Private 레파지토리도 접근 가능하게 하기 위해서는 Kind에서 Username with password를 사용해야 한다.
• Username은 깃허브의 username Password로는 위에서 만든 token 값을 넣어준다.(username의 계정 비밀번호가 아니다!)

 

• 에러가 사라진 모습을 확인할 수 있다.

 

• 빌드 유발은 Github hook trigger fot GITScm polling을 선택한다.

 

• 빌드 스탭은 Invoke Gadle script를 선택한다.
• 그리고 그래들 버전을 골라야 하는데 만약 Default 밖에 없다면 빌드 에러가 발생할 것이다.
• 만약 버전이 있다면 그걸 클릭하자.
• 나는 아무것도 나오지 않아 따로 그래들을 버전을 설치해야 한다.
• 우선 여기서 저장을 클릭한다.

 

🚒 에러 핸들링

• 밖으로 나와 Jenkins 관리 - System Configuration - Tools에 들어간다.

 

• Gradle Installations - Add Gradle을 클릭한다.

 

• 이름을 쓰고 버전을 적당히 골라준다. 나는 그냥 이름을 버전이랑 똑같이 썼다.

 

• 아까 만든 item의 구성에 들어가 그래들 버전을 정하고 저장한다.

 

📌 깃허브 웹훅 설정

• 설정해 놓은 깃허브 레파지토리에 들어가 Settings - Webhooks - add webhook을 클릭한다.

 

• 자, 여기서 Payload URL을 호스팅 되어있는 링크를 걸어야 한다.
• 만약 AWS와 같은 클라우드를 사용한다면 젠킨스가 설치되어 있는 인스턴스 주소를 적으면 되지만 로컬 환경에서는 불가능하므로 Ngrok을 이용했다.
  • Ngrok이 뭔지 모르면 구글링을 통해 알아보자
  • 다운로드하고 명령어 하나치고 구글 계정으로 가입하면 3분 만에 로컬 서버를 외부에 무료로 호스팅 할 수 있다.

 

💡 Ngrok 설정

wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$docker ps
CONTAINER ID   IMAGE                       COMMAND                   CREATED      STATUS       PORTS                                               NAMES
291cbb2ddcda   jenkins/jenkins:lts-jdk11   "/usr/bin/tini -- /u…"   3 days ago   Up 2 hours   0.0.0.0:50000->50000/tcp, 0.0.0.0:18080->8080/tcp   jenkins

• Ngrok을 다운로드한다.
  • 처음 사용하면 아마 가입하라고 할 텐데 그때 구글 로그인으로 가입하고 인증 토큰을 입력해면 끝이다. 매우 간단하다.
• 나의 경우 jenkins가 도커 컨테이너로 띄워져 있으므로 Ngrok이 18080 포트를 통해 로컬에서 젠킨스 도커 컨테이너로 들어가 젠킨스 서버를 깃허브 레파지토리와 webhook으로 연결하도록 할 것이다.
• 로컬에 젠킨스를 실행시키고 있다고 해도 차이가 없다 기본 포트는 8080일테고, 위에서 포트를 변경 했다면 변경한 젠킨스 포트를 연결시키면 된다.

 

wonyong@Wonyongui-MacBookAir:~/study/jenkinsTest$ngrok http 18080

ngrok                                                                                             (Ctrl+C to quit)
                                                                                                                  
Build better APIs with ngrok. Early access: ngrok.com/early-access                                                
                                                                                                                  
Session Status                online                                                                              
Account                       kakaohwy@gmail.com (Plan: Free)                                                     
Version                       3.4.0                                                                               
Region                        Japan (jp)                                                                          
Latency                       -                                                                                   
Web Interface                 http://127.0.0.1:4040                                                               
Forwarding                    https://dad8-222-109-220-21.ngrok-free.app -> http://localhost:18080                
                                                                                                                  
Connections                   ttl     opn     rt1     rt5     p50     p90                                         
                              0       0       0.00    0.00    0.00    0.00

• ngrok http (젠킨스 포트) 명령어를 통해 로컬 젠킨스 컨테이너를 호스팅 하는 데 성공했다.

 

• 위 링크에 접속하면 ngrok에서 만들어놓은 페이지가 나오는데 Visit Site를 누르면 젠킨스 페이지로 들어가진다.
• 처음에 이 페이지 때문에 웹훅이 제대로 작동할까 싶었지만 제대로 작동하니 무시해도 좋다.

 

⌨️ 웹훅 설정 마무리

• webhook 설정으로 돌아가 Ngrok으로부터 무료로 받은 도메인 주소를 넣고 /github-webhook/을 붙여주자.
  • /를 빼먹으면 에러가 발생한다고 하니 주의하자.
• Add webhook을 누른다.

 

• 정상적으로 등록되었다. 이제 테스트해보자.

 

📌 깃허브 레파지토리 -> 젠킨스 컨테이너 클론 테스트

• 문구를 수정하고 커밋 & 푸시해 보자.

 

• 빌드 성공했다!

 

📜 도커 젠킨스 컨테이너 내 워크스페이스 확인

• 컨테이너 내부의 워크스페이스에 forJenkins라는 이름으로 파일이 생성되었다.
  • 로컬에서는 mac 기준 /User/<user 명>/.jenkins/workspace 폴더에 있을 것이다.
• 정상적으로 깃허브 레파지토리의 업로드 파일들이 젠킨스 컨테이너 내 워크스페이스 폴더에 클론(clone)되었음을 확인할 수 있다.

 

 

 

참고

뤼튼

https://iizz.tistory.com/305

https://hyunminh.github.io/nonstop-deploy/

https://stackoverflow.com/questions/8646762/cannot-run-program-gradle-in-jenkins

https://be-developer.tistory.com/14

https://narup.tistory.com/224