Jenkins로 Unity WebGL 프로젝트 CI/CD

목적

Loop는 Steam(PC타겟플랫폼)과 GooglePlay(Mobile타겟플랫폼)에 출시되어,

각 빌드 파일을 자동 배포할 필요는 없었습니다.

 

그런데 Web Browser 타겟 플랫폼의 경우에는 인프라를 직접 구축하고 배포해야 합니다.

무엇보다도, 제 예상보다 앱 수정&재배포가 필요한 경우가 발생해서 Jenkins를 통해 CI/CD를 적용했습니다.

 

---

CI/CD

CI/CD에서 CD는 Deployment와 Delivery로 2가지 의미를 가지는데요,

이 글에서 저의 Jenkins CI/CD는 Delivery의 의미로 설계하였습니다.

Deployment의 경우 실제 배포 환경인 AWS EC2에서 Watchtower를 통해 이미지 변화를 모니터링하고 배포하도록 했습니다.

=> 서버 비용 절감을 위해  아래와 같은 Hybrid 인프라를 설계했기 때문입니다. (클라우드 비용 89% 절감)

 

제 Unity프로젝트를 Jenkins가 Build할 때 요구하는 하드웨어 리소스는

4개 이상의 Processor, 8GB이상의 Main Memory였습니다.

WebGL빌드시 IL2CPP컴파일을 거치며 하드웨어 리소스가 일정 부분 필요하기 때문입니다. 

이는 AWS 프리티어인 t2.micro로는 충당할 수 없는 수준입니다. 

 

그러나 자체 데이터센터에서 CI/CD(Delivery)를 진행한 후, Docker Image를 만들어 내기만 한다면 

Deployment를 위한 AWS 서버에서는 더 적은 리소스로도 Container를 통해 배포할 수 있습니다.

 

[Web타겟] C# 스크립트가 WebGL을 통해 웹 브라우저에서 실행되는 과정

WebGL빌드와 IL2CPP에 관해서는 이 글을 참고해주세요. 

---

Jenkins에서 Unity 빌드환경 세팅  

VMWare로 구축한 Ubuntu환경에서 Docker, Jenkins Image를 통해 CI/CD Container를 생성했습니다.

이후 이 Container에 Unity 빌드를 위한 환경을 세팅했습니다.

 

1. Unity3d Plugin 설치

CLI로 Unity3d Editor를 호출하고 빌드와 패키징을 자동화 할 수 있게 하는 Plugin입니다.

Unity3d

 

2. Unity3d Editor빌드 환경 만들기

GUI에서 Unity Hub를 통해 환경을 구축하시던 모든 과정을 

CLI를 통해 그대로 진행했다고 보시면 됩니다. 

 

Step 1. Unity3d Editor 설치

Unity 다운로드 아카이브에서 프로젝트 버전에 해당하는 것을 찾아 우클릭, 링크 주소 복사합니다.

다운로드 아카이브

# 설치
wget https://download.unity3d.com/download_unity/61c2feb0970d/LinuxEditorInstaller/Unity-2022.3.20f1.tar.xz -O Unity-2022.3.20f1.tar.xz

# tar.xz압축해제를 위해 xz-utils설치
sudo apt update
sudo apt install xz-utils

# 압축해제
tar -xvf Unity-2022.3.20f1.tar.xz

 

설치 후 대시보드 > Jenkins 관리 > Tools에서 Unity3d를 추가하여 이름과 경로를 설정했습니다.

Step 2. WebGL 모듈 설치

마찬가지로 다운로드 아카이브에서 설치했습니다.

버전에 맞는 WebGL Build Support를 설치합니다.

#설치 
wget https://download.unity3d.com/download_unity/61c2feb0970d/LinuxEditorTargetInstaller/UnitySetup-WebGL-Support-for-Editor-2022.3.20f1.tar.xz

#압축해제
tar -xvf UnitySetup-WebGL-Support-for-Editor-2022.3.20f1.tar.xz

 

 

Step 3. 그 외 의존성 설치

Unity가 필요로 하는 라이브러리들을 확인해 설치합니다.

ldd /Editor/Unity

 

나열된 라이브러리를 설치했습니다. 

apt-get install -y \
    libxcursor1 \
    libxrandr2 \
    libxrender1 \
    libxfixes3 \
    libxi6 \
    libxinerama1 \
    libxext6 \
    libglib2.0-0 \
    libgtk-3-0 \
 
    ..............(그 외 의존성들 나열. 이럴 땐 GPT!)

 

 

Step 4. 라이선스 확보

Jenkins Container가 Unity를 사용하기 위해 라이선스를 활성화해야 합니다.

아래 문서에 따르면 상업용 Unity 라이선스 하나 당 컴퓨터 2대까지만 사용 가능하니 

혹시 컴퓨터 2대 쓰시는 분들은 Jenkins에 내어 줄 한 자리를 비활성화 하시는 점 참고하세요..! 

라이선스 활성화 설정을 원하면 여기로: https://id.unity.com/ko/serials

정품 활성화 FAQ - Unity 매뉴얼

 

Step 5. Build Script.cs작성

빌드에 필요한 몇가지 설정들을 미리 아래 링크와 같이 스크립트화 했습니다.

https://github.com/ellen310/Loop/blob/main/Assets/Editor/BuildScript.cs

이 파일은 Assets/Editor아래에 위치시킵니다. 이 폴더는 특수폴더로서, 여기에 위치시킨 스크립트는 런타임 스크립트가 아니라 에디터 스크립트로서 동작합니다.

기존에는 오브젝트 등에 연결하는 스크립트 위주로 작성하고, Editor전용코드를 작성하는 방식만 알고 있었는데, 이렇게 빌드 파일에는 포함시키지 않는 스크립트를 별도로 작성하는 방법을 새로 배우게되었습니다.

특수 폴더 이름 - Unity 매뉴얼

---

Jenkins 구성

Freestyle Project를 생성했습니다.

 

1. 소스코드 관리

Github Repository의 main브랜치를 연동했습니다.

참고로 저의 Repository에는 오직 빌드에 필요한 항목들만 올라간 상태입니다.

그 외 항목들은 .gitignore 템플릿에서 Unity.gitignore를 참고하여 push하지 않도록 했습니다.

GitHub - github/gitignore: A collection of useful .gitignore templates

 

2. 빌드 단계

앞서 추가한 Unity 툴을 선택하고, Editor command line arguments를 작성했습니다. 

Editor command line arguments를 통해 command line에서 Unity Editor를 run할 수 있습니다. 

저는 Editor command line arguments를 아래와 같이 구성했습니다. 

-quit -batchmode -nographics -executeMethod BuildScript.PerformBuild -username <username> -password <password> -serial <serial-key>

• -quit: 커맨드가 끝나면 Unity Editor를 종료합니다.
• -batchmode: 배치모드로 CLI에서 Unity를 실행합니다. 
• -nographics: 배치모드에서 그래픽 장치를 초기화하지 않고 GPU없이 실행합니다.
• -serial: 앞서 언급한 라이선스를 활성화합니다.

이러한 구성은 아래 문서를 참고했습니다. 더 많은 Configuration arguments를 확인하실 수 있습니다.

Unity - Manual: Unity Editor command line arguments

+ .....Editor command line arguments작성시 인코딩에 유의하세요...ㅠㅠㅠ

저는 다른 편집기에서 작성하고 복붙했었는데, 공백 한개가 깨져서... 로그보고 굉장히 허무했네요호호... 

---

WebGL빌드에 성공하면 Build폴더, TemplateData폴더, index.html파일이 생성됩니다.

저는 이들을 압축한 후, SSH를 통해 NGINX Container 웹 루트 디렉토리에 전달, 압축해제하도록 했습니다. 

따라서 빌드 단계 마지막에 압축을 하는 Execute shell을 추가했습니다.

tar -czf Builds/LoopWebGLBuild.tar.gz -C Builds Build TemplateData index.html

 

3. 빌드 후 조치

압축한 파일을 NGINX컨테이너에 SSH로 전송하겠습니다.

물론 NGINX Container에는 OpenSSH서버 설치 및 세팅을 해뒀으며,

Jenkins에서도 이 SSH 서버 정보를 대시보드 > Jenkins관리 > System에서 아래처럼 등록해둔 상태입니다. 

 

참고로 여기서 NGINX Container는 오직 실제 배포를 위한 agent라고 볼 수 있으며,

빌드 파일을 포함한 NGINX Agent Container를 이미지화해서 AWS EC2에서 배포한 것입니다.

 

미리 빌드 후 조치 단계에서 등록한 SSH서버를 선택하고, 소스파일 지정했습니다.

 

Remote directory는 SSH server등록에서 NGINX빌드 위치로 설정해줬기때문에 그대로 두었습니다.

그리고 Exec command를 통해 원격으로 해당 Container에서 아래의 압축해제 명령을 실행하도록 했습니다.

tar -xzf /usr/share/nginx/html/LoopWebGLBuild.tar.gz -C /usr/share/nginx/html

 

NGINX컨테이너에 접속해 확인해보면 빌드파일이 잘 전달되어 돌아가는 것을 확인할 수 있습니다.

이제 이 상태 그대로 이미지화해서 EC2의 실제 배포에 활용할 것입니다.

 

 

다음 글에서는 아래 단계들에 해당하는 Deployment 과정까지 마저 설명하도록 하겠습니다.

 

• NGINX Agent Container설정
• Docker-compose통한 컨테이너 관리
• AWS EC2 배포
• Watchtower 이미지 변화 모니터링

긴 글 읽어주셔서 감사합니다!

---

참고자료

 

Command-line arguments: Command-line argumentshttps://docs.unity3d.com/Manual/CommandLineArguments.html

Configuration arguments: https://docs.unity3d.com/Manual/EditorCommandLineArguments.html

Unity 라이선스 활성화: https://docs.unity3d.com/kr/2019.4/Manual/ActivationFAQ.html

Unity Editor Script: https://algorfati.tistory.com/23

.gitignore templates: https://github.com/github/gitignore/tree/main