GitLab을 Docker 컨테이너에 설치하기

Tier: Free, Premium, Ultimate Offering: Self-managed

GitLab을 Docker 컨테이너에 설치하려면 Docker Compose, Docker Engine 또는 Docker Swarm 모드를 사용하세요.

필수 조건:

  • Docker for Windows가 아닌 작동하는 Docker 설치가 있어야 합니다.
    Docker for Windows는 볼륨 권한과 잠재적으로 다른 알려지지 않은 문제와의 호환성 문제로 인해 공식적으로 지원되지 않습니다.
    만약 Docker for Windows에서 실행하려는 경우, 도움 받기 페이지를 참조하세요. 이 페이지에는 다른 사용자로부터 도움을 받을 수 있는 커뮤니티 리소스(IRC나 포럼과 같은)의 링크가 포함되어 있습니다.
  • Postfix나 Sendmail과 같은 메일 전송 에이전트(MTA)가 필요합니다. GitLab 이미지에는 MTA가 포함되어 있지 않습니다. 별도의 컨테이너에 MTA를 설치할 수 있습니다. GitLab과 동일한 컨테이너에 MTA를 설치할 수 있지만, 모든 업그레이드나 재시작 후에 MTA를 다시 설치해야 할 수 있습니다.
  • GitLab Docker 이미지를 Kubernetes에 배포할 계획을 세우지 않도록 하세요. 이는 단일 실패 지점을 생성합니다. Kubernetes에 GitLab을 배포하려면 GitLab Helm Chart 또는 GitLab Operator를 사용하세요.
  • Docker 설치를 위한 유효한 외부 접근이 가능한 호스트 이름이 필요합니다. localhost를 사용하지 마세요.

SSH 포트 구성하기

기본적으로 GitLab은 SSH를 통해 Git과 상호작용하기 위해 포트 22를 사용합니다.
포트 22를 사용하려면 이 섹션을 건너뛰세요.

다른 포트를 사용하려면 다음 중 하나를 선택할 수 있습니다:

  • 지금 서버의 SSH 포트를 변경하세요(권장). 그러면 SSH 복제 URL에는 새 포트 번호가 필요 없습니다:

    ssh://git@gitlab.example.com/user/project.git  
    
  • 설치 후 GitLab Shell SSH 포트 변경하세요. 그러면 SSH 복제 URL에는 구성된 포트 번호가 포함됩니다:

    ssh://git@gitlab.example.com:<portNumber>/user/project.git  
    

서버의 SSH 포트를 변경하려면:

  1. /etc/ssh/sshd_config를 편집기로 열고 SSH 포트를 변경합니다:

    Port = 2424  
    
  2. 파일을 저장하고 SSH 서비스를 재시작합니다:

    sudo systemctl restart ssh  
    
  3. SSH를 통해 연결할 수 있는지 확인합니다. 새로운 터미널 세션을 열고 새 포트를 사용하여 서버에 SSH로 접속합니다.

볼륨을 위한 디렉터리 생성하기

구성 파일, 로그 및 데이터 파일을 위한 디렉터리를 생성합니다.
디렉터리는 사용자의 홈 디렉터리(예: ~/gitlab-docker)에 위치할 수 있거나 /srv/gitlab과 같은 디렉터리에 위치할 수 있습니다.

  1. 디렉터리를 생성합니다:

    sudo mkdir -p /srv/gitlab  
    
  2. root가 아닌 다른 사용자로 Docker를 실행하고 있다면, 새 디렉터리에 대한 적절한 권한을 사용자에게 부여합니다.

  3. 생성한 디렉터리의 경로를 설정하는 새로운 환경 변수 $GITLAB_HOME을 구성합니다:

    export GITLAB_HOME=/srv/gitlab  
    
  4. 선택적으로, 모든 미래의 터미널 세션에 적용되도록 쉘의 프로필에 GITLAB_HOME 환경 변수를 추가할 수 있습니다:

    • Bash: ~/.bash_profile
    • ZSH: ~/.zshrc

GitLab 컨테이너는 지속적인 데이터를 저장하기 위해 호스트 마운트 볼륨을 사용합니다:

로컬 위치 컨테이너 위치 용도
$GITLAB_HOME/data /var/opt/gitlab 애플리케이션 데이터를 저장합니다.
$GITLAB_HOME/logs /var/log/gitlab 로그를 저장합니다.
$GITLAB_HOME/config /etc/gitlab GitLab 구성 파일을 저장합니다.

사용할 GitLab 버전 및 에디션 찾기

운영 환경에서는 배포를 특정 GitLab 버전에 고정해야 합니다.

사용하려는 버전을 선택하고 사용 가능한 버전을 검토하려면 Docker 태그 페이지를 확인하세요:

태그 이름은 다음으로 구성됩니다:

gitlab/gitlab-ee:<version>-ee.0

여기서 <version>은 GitLab 버전으로, 예를 들어 16.5.3입니다. 버전 이름에는 항상 <major>.<minor>.<patch>가 포함됩니다.

테스트 목적으로는 latest 태그를 사용할 수 있으며, 예를 들어 gitlab/gitlab-ee:latest는 최신 안정 릴리스를 가리킵니다.

다음 예제는 안정적인 Enterprise Edition 버전을 사용합니다.

릴리스 후보(RC) 또는 야간 이미지를 사용하려면 대신 gitlab/gitlab-ee:rc 또는 gitlab/gitlab-ee:nightly를 사용하세요.

Community Edition을 설치하려면 eece로 변경하세요.

설치

다음 방법으로 GitLab Docker 이미지를 실행할 수 있습니다:

Docker Compose를 사용하여 GitLab 설치

Docker Compose를 사용하여 Docker 기반 GitLab 설치를 구성, 설치 및 업그레이드할 수 있습니다:

  1. Docker Compose 설치합니다.
  2. docker-compose.yml 파일을 생성합니다. 예를 들어:

    version: '3.6'
    services:
      gitlab:
        image: gitlab/gitlab-ee:<version>-ee.0
        container_name: gitlab
        restart: always
        hostname: 'gitlab.example.com'
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            # gitlab.rb 구성의 다른 항목을 여기 추가하세요. 각 항목은 별도의 줄에 작성
            external_url 'https://gitlab.example.com'
        ports:
          - '80:80'
          - '443:443'
          - '22:22'
        volumes:
          - '$GITLAB_HOME/config:/etc/gitlab'
          - '$GITLAB_HOME/logs:/var/log/gitlab'
          - '$GITLAB_HOME/data:/var/opt/gitlab'
        shm_size: '256m'
    

    참고: GITLAB_OMNIBUS_CONFIG 변수가 어떻게 작동하는지 보려면 Docker 컨테이너 사전 구성 섹션을 읽어보세요.

    다음은 GitLab이 사용자 정의 HTTP 및 SSH 포트에서 실행되는 다른 docker-compose.yml 예입니다. GITLAB_OMNIBUS_CONFIG 변수가 ports 섹션과 일치하는지 확인하세요:

    version: '3.6'
    services:
      gitlab:
        image: gitlab/gitlab-ee:<version>-ee.0
        container_name: gitlab
        restart: always
        hostname: 'gitlab.example.com'
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            external_url 'http://gitlab.example.com:8929'
            gitlab_rails['gitlab_shell_ssh_port'] = 2424
        ports:
          - '8929:8929'
          - '443:443'
          - '2424:22'
        volumes:
          - '$GITLAB_HOME/config:/etc/gitlab'
          - '$GITLAB_HOME/logs:/var/log/gitlab'
          - '$GITLAB_HOME/data:/var/opt/gitlab'
        shm_size: '256m'
    

    이 구성은 --publish 8929:8929 --publish 2424:22를 사용하는 것과 같습니다.

  3. docker-compose.yml 파일과 같은 디렉토리에서 GitLab을 시작합니다:

    docker compose up -d
    

GitLab 설치하기 - Docker Engine 사용

대안으로, Docker Engine을 사용하여 GitLab을 설치할 수 있습니다.

  1. GITLAB_HOME 변수를 설정한 경우, 필요에 따라 디렉토리를 조정하고 이미지를 실행하세요:

    • SELinux를 사용하지 않는 경우, 다음 명령어를 실행하세요:

       sudo docker run --detach \
         --hostname gitlab.example.com \
         --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'" \
         --publish 443:443 --publish 80:80 --publish 22:22 \
         --name gitlab \
         --restart always \
         --volume $GITLAB_HOME/config:/etc/gitlab \
         --volume $GITLAB_HOME/logs:/var/log/gitlab \
         --volume $GITLAB_HOME/data:/var/opt/gitlab \
         --shm-size 256m \
         gitlab/gitlab-ee:<version>-ee.0
      

      이 명령어는 GitLab 컨테이너를 다운로드하고 시작하며, 필요한 포트를 게시하여 SSH, HTTP 및 HTTPS에 접근할 수 있게 해줍니다. 모든 GitLab 데이터는 $GITLAB_HOME의 하위 디렉토리로 저장됩니다. 컨테이너는 시스템 재부팅 후 자동으로 재시작됩니다.

    • SELinux를 사용하는 경우, 대신 다음을 실행하세요:

       sudo docker run --detach \
         --hostname gitlab.example.com \
         --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'" \
         --publish 443:443 --publish 80:80 --publish 22:22 \
         --name gitlab \
         --restart always \
         --volume $GITLAB_HOME/config:/etc/gitlab:Z \
         --volume $GITLAB_HOME/logs:/var/log/gitlab:Z \
         --volume $GITLAB_HOME/data:/var/opt/gitlab:Z \
         --shm-size 256m \
         gitlab/gitlab-ee:<version>-ee.0
      

      이 명령어는 Docker 프로세스가 마운트된 볼륨에 구성 파일을 생성할 수 있는 충분한 권한을 갖도록 보장합니다.

  2. Kerberos 통합을 사용하는 경우, Kerberos 포트를 게시해야 합니다 (예: --publish 8443:8443).

    이를 실패하게 되면 Kerberos와 Git 작업이 불가능합니다. 초기화 과정은 시간이 오래 걸릴 수 있습니다. 이 과정을 확인하려면:

    sudo docker logs -f gitlab
    

    컨테이너가 시작된 후, gitlab.example.com을 방문할 수 있습니다. Docker 컨테이너가 쿼리에 응답하기 시작하는 데 시간이 걸릴 수 있습니다.

  3. GitLab URL을 방문하고, 사용자 이름 root로 로그인합니다. 그리고 다음 명령어에서 가져온 비밀번호로 로그인하세요:

    sudo docker exec -it gitlab grep 'Password:' 
    /etc/gitlab/initial_root_password
    

참고:

비밀번호 파일은 24시간 후 첫 번째 컨테이너 재시작 시 자동으로 삭제됩니다.

GitLab 설치하기 - Docker Swarm 모드 사용

Docker Swarm 모드를 사용하면 스웜 클러스터에서 Docker로 GitLab 설치를 구성하고 배포할 수 있습니다.

스웜 모드에서 Docker secretsDocker configurations를 활용하여 GitLab 인스턴스를 효율적이고 안전하게 배포할 수 있습니다. Secrets는 초기 루트 비밀번호를 안전하게 전달하는 데 사용할 수 있으며, 환경 변수로 노출되지 않도록 합니다. Configurations는 GitLab 이미지를 가능한 한 일반적으로 유지하는 데 도움을 줄 수 있습니다.

다음은 비밀 및 구성을 사용하여 스택으로 네 개의 러너와 함께 GitLab을 배포하는 예제입니다.

  1. Docker 스웜 설정합니다.
  2. docker-compose.yml 파일을 생성합니다:

    version: "3.6"
    services:
      gitlab:
        image: gitlab/gitlab-ee:<version>-ee.0
        container_name: gitlab
        restart: always
        hostname: 'gitlab.example.com'
        ports:
          - "22:22"
          - "80:80"
          - "443:443"
        volumes:
          - $GITLAB_HOME/data:/var/opt/gitlab
          - $GITLAB_HOME/logs:/var/log/gitlab
          - $GITLAB_HOME/config:/etc/gitlab
        shm_size: '256m'
        environment:
          GITLAB_OMNIBUS_CONFIG: "from_file('/omnibus_config.rb')"
        configs:
          - source: gitlab
            target: /omnibus_config.rb
        secrets:
          - gitlab_root_password
      gitlab-runner:
        image: gitlab/gitlab-runner:alpine
        deploy:
          mode: replicated
          replicas: 4
    configs:
      gitlab:
        file: ./gitlab.rb
    secrets:
      gitlab_root_password:
        file: ./root_password.txt
    

    복잡성을 줄이기 위해 위의 예제는 network 구성을 제외합니다. 공식 Compose 파일 참조에서 더 많은 정보를 찾을 수 있습니다.

  3. gitlab.rb 파일을 생성합니다:

    external_url 'https://my.domain.com/'
    gitlab_rails['initial_root_password'] = File.read('/run/secrets/gitlab_root_password').gsub("\n", "")
    
  4. 비밀번호를 포함한 root_password.txt 파일을 생성합니다:

    MySuperSecretAndSecurePassw0rd!
    
  5. docker-compose.yml와 동일한 디렉토리에 있는지 확인하고, 실행합니다:

    docker stack deploy --compose-file docker-compose.yml mystack
    

Docker를 설치한 후, GitLab 인스턴스를 구성해야 합니다.