GitLab 오프라인 설치 후기 및 폐쇄망 구축 가이드

폐쇄망 및 보안 구역 환경에서 개발 프로젝트를 진행할 때 가장 먼저 맞닥뜨리는 난관 중 하나가 바로 소스코드 관리 시스템 구축입니다. 인터넷이 연결되지 않은 서버에 GitLab 오프라인 설치를 진행하면서 겪었던 실제 경험과 시행착오, 그리고 gitlab runner 오프라인 설치까지 완성하는 전체 프로세스를 자세하게 공유해 드립니다.

01. 사전 준비 및 환경 구성

폐쇄망 설치 시 가장 핵심은 필요한 모든 파일과 의존성을 외부망에서 미리 다운로드하여 준비하는 것입니다.
✓ 확인할 점

설치 대상 OS 버전(Ubuntu, Rocky Linux, CentOS 등) 정확히 파악하기
GitLab OmniBus 패키지(.deb 또는 .rpm) 최신/안정 버전 다운로드
SSH 서비스 및 firewall/iptables 포트 개방 계획 수립

외부 인터넷이 가능한 환경에서 대상 서버 OS와 정확히 일치하는 GitLab Omnibus 패키지를 다운로드해야 합니다. 아울러 curl, openssh-server, postfix, policycoreutils 등 필수 사전 의존성 패키지도 함께 준비해 두셔야 설치 과정에서 오류가 발생하지 않습니다.

구분	준비 항목	비고
필수 패키지	GitLab Omnibus 설치 파일 (.deb / .rpm)	공식 깃랩 리포지토리 다운로드
의존성 패키지	OpenSSH, Postfix, policycoreutils, perl	OS 설치 미디어(ISO) 활용 가능
반입 수단	USB, 내부망 망연계 솔루션, SCP	보안 규정에 맞춰 반입

02. GitLab 오프라인 설치 실전 단계

미리 준비해 둔 패키지를 폐쇄망 서버로 이관한 후 진행하는 실제 설치 절차입니다.
✓ 작업 순서

준비된 패키지 파일 서버 내부 디렉토리로 이동
패키지 매니저(dpkg / rpm)를 이용한 수동 설치 실행
gitlab.rb 설정 파일 수정 및 reconfigure 수행

우분투 환경이라면 dpkg -i 명령어를, RHEL/Rocky Linux 환경이라면 rpm -ivh 명령어를 사용하여 설치를 진행합니다. 설치가 완료되면 /etc/gitlab/gitlab.rb 파일에서 external_url 항목을 폐쇄망 내부 IP 또는 내부 DNS 도메인 주소로 변경해 주셔야 합니다.

Bash

# 예시: Rocky/CentOS 환경 패키지 설치
sudo rpm -ivh gitlab-ce-<version>.rpm

# 설정 반영
sudo gitlab-ctl reconfigure

gitlab-ctl reconfigure 명령을 실행하면 Chef 기반의 자동 설정이 진행되며, 완료 후 gitlab-ctl status 명령어로 모든 프로세스가 정상 작동하는지 확인하실 수 있습니다.

03. GitLab Runner 오프라인 설치 및 연동

CI/CD 파이프라인을 구동하기 위해서는 gitlab runner 오프라인 설치 작업이 필수적으로 동반되어야 합니다.
✓ 체크 포인트

GitLab Runner 바이너리 파일 다운로드 (gitlab-runner-linux-amd64)
실행 권한 부여 및 시스템 서비스 등록
폐쇄망 GitLab 서버와 토큰 연동 등록(Register)

인터넷이 끊긴 환경에서는 Docker Executor를 사용할 때 필요한 도커 이미지(예: alpine:latest, bash:latest 등)도 미리 docker save 명령어로 추출한 뒤, 폐쇄망 서버에서 docker load로 불러와 두어야 작업이 정상 처리됩니다.

Bash

# 바이너리 실행 권한 부여 및 설치
sudo chmod +x gitlab-runner-linux-amd64
sudo mv gitlab-runner-linux-amd64 /usr/local/bin/gitlab-runner
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

등록 시에는 GitLab 관리자 페이지 또는 프로젝트 설정에서 발급받은 Registration Token과 내부 서버 URL을 입력하여 연결을 마무리합니다.

04. 트러블슈팅 및 운영 팁

오프라인 환경 설치 시 빈번하게 발생하는 오류와 이에 대한 해결 방안입니다.

의존성 라이브러리 부재 오류: OS ISO 이미지를 내부 Yum/APT 로컬 리포지토리로 등록하여 부족한 라이브러리를 설치합니다.
502 Bad Gateway 에러: 메모리 부족이 원인인 경우가 많습니다. 최소 4GB 이상(8GB 권장)의 RAM을 할당받았는지 확인하세요.
HTTP/HTTPS SSL 인증서 이슈: 폐쇄망 내부 사설 CA 인증서를 사용할 경우, GitLab Runner 및 Git 클라이언트 설정에 해당 CA 인증서를 추가 등록해 주어야 통신 에러가 발생하지 않습니다.

자주 묻는 질문 (FAQ)

Q1. 인터넷이 아예 안 되는데 백업과 복구는 어떻게 진행하나요?
A. gitlab-rake gitlab:backup:create 명령어를 사용하면 /var/opt/gitlab/backups 경로에 백업 타르볼(.tar) 파일이 생성됩니다. 이 파일을 외부 매체로 안전하게 이관하여 오프라인 상태에서도 동일하게 복구 작업할 수 있습니다.
Q2. GitLab Runner에서 Docker Executor 사용 시 이미지를 못 불러옵니다.
A. 폐쇄망 특성상 외부 Docker Hub 접근이 불가능하기 때문입니다. 사내 프라이빗 도메인 리포지토리(Nexus, Harbor 등)를 구축하시거나, 필요한 이미지를 미리 docker load로 로컬에 로드한 후 pull_policy = "if-not-present" 또는 "never"로 설정해 사용하세요.
Q3. 라이선스 등록이 필요한 EE 버전도 오프라인 설치가 가능한가요?
A. 네, 가능합니다. Enterprise Edition(EE) 패키지도 동일하게 다운로드하여 설치할 수 있으며, 발급받은 텍스트 형태의 라이선스 키 파일(.gitlab-license)을 웹 UI 상에서 업로드해 주시면 문제없이 활성화됩니다.