완전한 오프라인 환경에서 GitLab Self-Managed 인스턴스를 설치하고 구성해 사용하는 방법을 단계별로 안내합니다.

설치#

이 과정을 영상으로 확인하려면 Offline GitLab Installation: Downloading & Installing을 참고합니다.

GitLab 패키지 다운로드#

인터넷에 연결된 동일한 운영체제 유형의 서버를 사용해 GitLab 패키지를 다운로드하고 관련 의존성도 함께 내려받습니다.

오프라인 환경에 로컬 네트워크 접근이 없다면 USB 드라이브 같은 물리 매체로 해당 패키지를 직접 옮겨야 합니다.

Ubuntu에서는 인터넷에 연결된 서버에서 다음 명령으로 수행할 수 있습니다:

# Download the bash script to prepare the repository
curl --silent "https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh" | sudo bash

# Download the gitlab-ee package and dependencies to /var/cache/apt/archives
sudo apt-get install --download-only gitlab-ee

# Copy the contents of the apt download folder to a mounted media device
sudo cp /var/cache/apt/archives/*.deb /path/to/mount

GitLab 패키지 설치#

사전 요구 사항:

• 오프라인 환경에 GitLab 패키지를 설치하기 전에, 필요한 모든 의존성을 먼저 설치했는지 확인합니다.

Ubuntu를 사용한다면 복사해 온 의존성 .deb 패키지를 dpkg로 설치할 수 있습니다. GitLab 패키지는 아직 설치하지 않습니다.

# Go to the physical media device
sudo cd /path/to/mount

# Install the dependency packages
sudo dpkg -i <package_name>.deb

운영체제에 맞는 명령으로 패키지를 설치하되, EXTERNAL_URL 설치 단계에서는 반드시 http URL을 지정합니다. 설치를 마친 뒤에는 SSL을 직접 수동으로 구성할 수 있습니다.

서버의 IP 주소에 바인딩하기보다 IP 확인용 도메인을 설정하는 방식을 권장합니다. 도메인은 인증서의 Common Name(CN)에 안정적인 대상을 제공하고, 장기적인 이름 확인을 단순하게 만듭니다.

다음은 Ubuntu에서 HTTP로 EXTERNAL_URL을 지정해 GitLab 패키지를 설치하는 예시입니다:

sudo EXTERNAL_URL="http://my-host.internal" dpkg -i <gitlab_package_name>.deb

SSL 활성화#

새로 설치한 인스턴스에서 SSL을 활성화하려면 다음 단계를 따릅니다. 이 단계는 NGINX 구성에서 SSL을 수동으로 구성하는 방법과 동일합니다:

1. /etc/gitlab/gitlab.rb를 다음과 같이 변경합니다:

   # Update external_url from "http" to "https"
   external_url "https://my-host.internal"
   
   # Set Let's Encrypt to false
   letsencrypt['enable'] = false
   

2. 자체 서명 인증서를 생성할 수 있도록 적절한 권한으로 다음 디렉터리를 만듭니다:

   sudo mkdir -p /etc/gitlab/ssl
   sudo chmod 755 /etc/gitlab/ssl
   sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/gitlab/ssl/my-host.internal.key -out /etc/gitlab/ssl/my-host.internal.crt
   

3. 변경 사항을 적용하도록 인스턴스를 재구성합니다:

   sudo gitlab-ctl reconfigure
   

GitLab 컨테이너 레지스트리 활성화#

컨테이너 레지스트리를 활성화하려면 다음 단계를 따릅니다. 이 단계는 기존 도메인에서 컨테이너 레지스트리를 구성하는 방법과 동일합니다:

1. /etc/gitlab/gitlab.rb를 다음과 같이 변경합니다:

   # Change external_registry_url to match external_url, but append the port 4567
   external_url "https://gitlab.example.com"
   registry_external_url "https://gitlab.example.com:4567"
   

2. 변경 사항을 적용하도록 인스턴스를 재구성합니다:

   sudo gitlab-ctl reconfigure
   

Docker 데몬이 레지스트리와 GitLab Runner를 신뢰하도록 허용#

Docker 데몬에 인증서를 제공하려면 레지스트리에서 신뢰할 수 있는 인증서를 사용하는 단계를 따릅니다:

sudo mkdir -p /etc/docker/certs.d/my-host.internal:5000

sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/docker/certs.d/my-host.internal:5000/ca.crt

다음 단계에서 설치할 GitLab Runner에 인증서를 제공하려면 러너에서 신뢰할 수 있는 인증서를 사용하는 단계를 따릅니다:

sudo mkdir -p /etc/gitlab-runner/certs

sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/gitlab-runner/certs/ca.crt

GitLab Runner 활성화#

GitLab Runner를 Docker 서비스로 설치하는 단계와 비슷한 과정을 따라, 먼저 러너를 등록해야 합니다:

$ sudo docker run --rm -it -v /etc/gitlab-runner:/etc/gitlab-runner gitlab/gitlab-runner register
Updating CA certificates...
Runtime platform                                    arch=amd64 os=linux pid=7 revision=1b659122 version=12.8.0
Running in system-mode.

Enter the GitLab instance URL (for example, https://gitlab.com/):
https://my-host.internal
Enter the registration token:
XXXXXXXXXXX
Enter a description for the runner:
[eb18856e13c0]:
Enter tags for the runner (comma-separated):
Enter optional maintenance note for the runner:

Registering runner... succeeded                     runner=FSMwkvLZ
Please enter the executor: custom, docker, virtualbox, kubernetes, docker+machine, docker-ssh+machine, docker-ssh, parallels, shell, ssh:
docker
Please enter the default Docker image (for example, ruby:2.6):
ruby:2.6
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

다음으로 러너에 몇 가지 설정을 추가해야 합니다.

/etc/gitlab-runner/config.toml을 다음과 같이 변경합니다:

• volumes에 Docker 소켓을 추가합니다. volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
• executor 구성에 pull_policy = "if-not-present"를 추가합니다.

이제 러너를 시작할 수 있습니다:

sudo docker run -d --restart always --name gitlab-runner -v /etc/gitlab-runner:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest
90646b6587127906a4ee3f2e51454c6e1f10f26fc7a0b03d9928d8d0d5897b64

호스트 OS에 대한 레지스트리 인증#

Docker 레지스트리 인증 문서에 설명된 대로, 일부 Docker 버전은 OS 수준에서 인증서 체인을 신뢰해야 합니다.

Ubuntu에서는 update-ca-certificates를 사용합니다:

sudo cp /etc/docker/certs.d/my-host.internal\:5000/ca.crt /usr/local/share/ca-certificates/my-host.internal.crt

sudo update-ca-certificates

정상적으로 진행되면 다음과 같이 표시됩니다:

1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

버전 확인 및 서비스 핑 비활성화#

버전 확인(Version Check)과 서비스 핑(Service Ping)은 GitLab 사용자 경험을 개선하고 사용자가 최신 GitLab 인스턴스를 사용하도록 돕습니다. 오프라인 환경에서는 이 두 서비스가 GitLab 서비스에 연결을 시도했다가 실패하지 않도록 끌 수 있습니다.

자세한 내용은 서비스 핑 활성화 또는 비활성화를 참고합니다.

러너 버전 관리 비활성화#

러너 버전 관리는 GitLab에서 최신 러너 버전을 가져와 환경의 어떤 러너가 오래되었는지 판단합니다. 오프라인 환경에서는 러너 버전 관리를 비활성화해야 합니다.

NTP 구성#

Gitaly Cluster(Praefect)는 pool.ntp.org에 접근할 수 있다고 가정합니다. pool.ntp.org에 접근할 수 없다면 Gitaly 및 Praefect 서버에서 시간 서버 설정을 사용자 지정해 접근 가능한 NTP 서버를 사용하도록 합니다.

오프라인 인스턴스에서는 GitLab Geo 점검 Rake 태스크가 pool.ntp.org를 사용하기 때문에 항상 실패합니다. 이 오류는 무시해도 되며, 우회 방법에 관한 자세한 내용도 확인할 수 있습니다.

패키지 메타데이터 데이터베이스 활성화#

지속적 취약점 스캔과 CycloneDX 파일의 라이선스 스캔은 패키지 메타데이터 데이터베이스를 읽습니다. 오프라인 인스턴스는 이 데이터베이스를 내려받을 수 없으므로, 인터넷에 연결된 머신에서 내려받아 인스턴스로 복사합니다.

• 데이터베이스에 담긴 내용과 사용 중인 GitLab 버전이 읽는 데이터 형식 버전은 패키지 메타데이터 데이터베이스를 참고합니다.
• 내려받기와 복사 절차는 오프라인 인스턴스용 패키지 메타데이터 데이터베이스를 참고합니다.