Docker를 사용하여 GitLab 설치하기
GitLab Docker 이미지는 모든 필요한 서비스를 단일 컨테이너에서 실행하는 GitLab의 단일 이미지입니다.
GitLab 공식 Docker 이미지를 다음에서 찾을 수 있습니다:
Docker 이미지에는 메일 전송 에이전트(MTA)가 포함되어 있지 않습니다. 권장하는 해결책은 별도의 컨테이너에서 실행되는 MTA(예: 포스트픽스 또는 센드메일)를 추가하는 것입니다. 또 다른 옵션으로는 GitLab 컨테이너에 MTA를 직접 설치할 수 있지만, 이렇게 하면 업그레이드 또는 재시작 후에 MTA를 재설치해야 할 수 있어 유지 관리 부담이 생깁니다.
GitLab Docker 이미지를 Kubernetes에 배포하지 않는 것이 좋습니다. 이렇게 하면 단일 장애 지점이 생깁니다. Kubernetes에 GitLab을 배포하려면 GitLab Helm 차트 또는 GitLab Operator를 대신 사용해야 합니다.
경고: Windows용 Docker는 공식적으로 지원되지 않습니다. 볼륨 권한과 같은 알려진 문제뿐만 아니라 잠재적으로 다른 문제도 있습니다. Windows용 Docker를 실행하려는 경우, 도움말 페이지에서 커뮤니티 리소스(IRC 또는 포럼과 같은) 링크를 참조하여 다른 사용자로부터 도움을 요청하세요.
전제 조건
GitLab Docker 이미지를 사용하려면:
- Docker를 설치해야 합니다.
- 유효한 외부 접근 가능한 호스트 이름을 사용해야 합니다.
localhost를 사용하지 마십시오.
SSH 포트 구성
GitLab은 Git과 SSH를 통해 상호 작용하기 위해 SSH를 사용합니다. 기본적으로 GitLab은 포트 22를 사용합니다.
GitLab Docker 이미지를 사용할 때 다른 포트를 사용하려면 다음 중 하나를 선택할 수 있습니다:
- 서버의 SSH 포트를 변경합니다(권장).
- GitLab Shell SSH 포트를 변경합니다.
서버의 SSH 포트 변경
GitLab에서 다른 SSH 구성 변경을 하지 않고 서버의 SSH 포트를 변경할 수 있습니다. 이 경우, SSH 클론 URL은 ssh://git@gitlab.example.com/user/project.git과 같습니다.
서버의 SSH 포트를 변경하려면:
-
편집기로
/etc/ssh/sshd_config를 열고 SSH 포트를 변경합니다:Port = 2424 -
파일을 저장하고 SSH 서비스를 재시작합니다:
sudo systemctl restart ssh -
새 터미널 세션을 열고 새 포트를 사용하여 서버에 SSH로 연결할 수 있는지 확인합니다.
GitLab Shell SSH 포트 변경
서버의 기본 SSH 포트를 변경하고 싶지 않은 경우, GitLab이 Git over SSH 푸시에 사용하는 다른 SSH 포트를 구성할 수 있습니다. 이 경우, SSH 클론 URL은 ssh://git@gitlab.example.com:<portNumber>/user/project.git과 같습니다.
자세한 내용은 GitLab Shell SSH 포트 변경을 참조하십시오.
볼륨 위치 설정
모든 것을 설정하기 전에, 구성, 로그 및 데이터 파일이 저장될 디렉토리를 만드세요. 이 디렉토리는 사용자의 홈 디렉토리 아래(예: ~/gitlab-docker)이거나 /srv/gitlab과 같은 디렉토리일 수 있습니다. 해당 디렉토리를 만들려면:
sudo mkdir -p /srv/gitlab
root 이외의 사용자로 Docker를 실행하는 경우, 해당 디렉토리에 적절한 권한이 부여되었는지 확인하십시오.
새로운 환경 변수 $GITLAB_HOME을 구성된 디렉토리 경로로 설정하는 것입니다:
export GITLAB_HOME=/srv/gitlab
터미널의 프로필에 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는 최신 안정 배포판을 가리킵니다.
다음 예시에서는 안정적인 엔터프라이즈 에디션 버전을 사용하지만, RC(릴리스 후보) 또는 nightly 이미지를 사용하려면 gitlab/gitlab-ee:rc 또는 gitlab/gitlab-ee:nightly를 대신 사용하세요.
커뮤니티 에디션을 설치하려면 ee 대신 ce를 사용하세요.
설치
GitLab Docker 이미지는 여러 방법으로 실행할 수 있습니다:
Docker 엔진을 사용하여 GitLab 설치
이 디렉토리를 조정하여 요구사항에 맞게 설정할 수 있습니다.
GITLAB_HOME 변수를 설정한 후에 이미지를 실행할 수 있습니다:
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:<버전>-ee.0
이 명령은 GitLab 컨테이너를 다운로드하고 시작하며,
SSH, HTTP 및 HTTPS에 접근하는 데 필요한 포트를
공개(publishes)합니다. 모든 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:<버전>-ee.0
이 명령은 마운트된 볼륨에 구성 파일을 생성할 수 있는 충분한 권한을 Docker 프로세스가 가지고 있는지 확인합니다.
만약 Kerberos 통합을 사용하는 경우,
Kerberos 포트도 공개(publish)해야 합니다 (예: --publish 8443:8443).
이를 놓치면 Kerberos를 사용한 Git 작업이 불가능합니다.
초기화 프로세스는 시간이 오래 걸릴 수 있습니다. 이를 다음 명령으로 추적(track)할 수 있습니다:
sudo docker logs -f gitlab
컨테이너를 시작한 후에 gitlab.example.com을 방문할 수 있습니다.
Docker 컨테이너가 쿼리에 응답하기까지는 시간이 걸릴 수 있습니다.
GitLab URL을 방문하고, 사용자 이름 root와
다음 명령에서 얻은 비밀번호로 로그인할 수 있습니다:
sudo docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password
참고: 비밀번호 파일은 24시간 후 첫 번째 컨테이너 재시작 시 자동으로 삭제됩니다.
Docker Compose를 사용하여 GitLab 설치
Docker Compose를 사용하면 Docker 기반의 GitLab 설치를 쉽게 구성, 설치 및 업그레이드할 수 있습니다:
- Docker Compose 설치.
-
docker-compose.yml파일을 만듭니다:version: '3.6' services: gitlab: image: gitlab/gitlab-ee:<버전>-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' -
docker-compose.yml과 동일한 디렉터리에 있는지 확인하고 GitLab을 시작합니다:docker compose up -d
참고:
GITLAB_OMNIBUS_CONFIG 변수가 어떻게 작동하는지 알아보려면
사전 구성된 Docker 컨테이너 섹션을 확인하십시오.
아래에는 HTTP 및 SSH 포트에서 실행 중인 GitLab을 갖는
다른 docker-compose.yml 예제가 있습니다. GITLAB_OMNIBUS_CONFIG 변수가
ports 섹션과 일치하는지에 주목하십시오:
version: '3.6'
services:
gitlab:
image: gitlab/gitlab-ee:<버전>-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:2424'
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:2424를 사용하는 것과 동일합니다.
Docker 스왐 모드를 사용하여 GitLab 설치
Docker 스왜 모드를 사용하면 스왜 커스터에 Docker 기반의 GitLab 설치를 쉽게 구성하고 배포할 수 있습니다.
스왜 모드에서는 Docker secrets 및 Docker configurations을 활용하여 GitLab 인스턴스를 효율적으로 그리고 안전하게 배포할 수 있습니다. Secrets을 사용하면 초기 루트 암호를 환경 변수로 노출시키지 않고 안전하게 전달할 수 있습니다. Configurations을 사용하면 GitLab 이미지를 가능한 한 일반적으로 유지할 수 있습니다.
다음은 시크릿과 설정을 사용하여 4개의 러너를 가진 스택으로 GitLab을 배포하는 예시입니다.
- Docker 스왜 구성을 수행합니다.
-
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 file reference에서 찾을 수 있습니다. -
gitlab.rb파일을 생성합니다:external_url 'https://my.domain.com/' gitlab_rails['initial_root_password'] = File.read('/run/secrets/gitlab_root_password').gsub("\n", "") -
암호가 포함된
root_password.txt파일을 생성합니다:MySuperSecretAndSecurePassw0rd! -
동일한 디렉토리에 있는
docker-compose.yml파일과 함께 다음을 실행합니다:docker stack deploy --compose-file docker-compose.yml mystack
구성
이 컨테이너는 공식 리눅스 패키지를 사용하므로 모든 구성은 유일한 구성 파일인 /etc/gitlab/gitlab.rb에서 수행됩니다.
GitLab 구성 파일에 액세스하려면 실행 중인 컨테이너의 쉘 세션을 시작할 수 있습니다. 이렇게 하면 모든 디렉토리를 탐색하고 즐겨 사용하는 텍스트 편집기를 사용할 수 있습니다:
sudo docker exec -it gitlab /bin/bash
또는 직접 /etc/gitlab/gitlab.rb 파일을 편집할 수도 있습니다:
sudo docker exec -it gitlab editor /etc/gitlab/gitlab.rb
/etc/gitlab/gitlab.rb를 열면 external_url을 유효한 URL로 설정해야 합니다.
GitLab에서 이메일을 받으려면 GitLab Docker 이미지에 SMTP 서버가 설치되어 있지 않으므로 SMTP 설정을 구성해야 합니다. 또한 HTTPS 활성화에 관심이 있을 수 있습니다.
원하는 모든 변경 사항을 적용한 후 GitLab을 다시 구성하려면 컨테이너를 다시 시작해야 합니다:
sudo docker restart gitlab
GitLab은 컨테이너 시작시 자체적으로 재구성됩니다. GitLab을 구성하는 더 많은 옵션은 구성 문서를 확인하십시오.
Docker 컨테이너 사전 구성
Docker 이미지에 환경 변수 GITLAB_OMNIBUS_CONFIG를 추가하여 GitLab Docker 이미지를 사전 구성할 수 있습니다. 이 변수에는 gitlab.rb 설정을 포함할 수 있으며 컨테이너의 gitlab.rb 파일을 로드하기 전에 해당 설정이 평가됩니다. 이 동작을 통해 외부 GitLab URL을 구성하고 데이터베이스 구성 또는 Linux package template에서 다른 옵션을 설정할 수 있습니다. GITLAB_OMNIBUS_CONFIG에 포함된 설정은 gitlab.rb 구성 파일에 기록되지 않으며 로드될 때 평가됩니다. 여러 설정을 제공하려면 콜론(;)으로 구분합니다.
다음은 컨테이너를 시작하는 동안 외부 URL을 설정하고 LFS를 활성화하는 예시입니다:
sudo docker run --detach \
--hostname gitlab.example.com \
--env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'; gitlab_rails['lfs_enabled'] = true;" \
--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
매번 docker run 명령을 실행할 때마다 GITLAB_OMNIBUS_CONFIG 옵션을 제공해야 합니다. GITLAB_OMNIBUS_CONFIG의 내용은 연속적인 실행 사이에 보존되지 않습니다.
공용 IP 주소에서 GitLab 실행
도커를 사용하여 IP 주소를 수정하고 모든 트래픽을 GitLab 컨테이너로 전달하도록 설정할 수 있습니다.
IP 198.51.100.1에서 GitLab을 노출하려면:
sudo docker run --detach \
--hostname gitlab.example.com \
--env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com'" \
--publish 198.51.100.1:443:443 \
--publish 198.51.100.1:80:80 \
--publish 198.51.100.1: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 인스턴스에는 http://198.51.100.1/ 및 https://198.51.100.1/에서 액세스할 수 있습니다.
다른 포트에서 GitLab 노출
GitLab은 컨테이너 내에서 일부 포트를 차지할 것입니다.
80 (HTTP), 443 (HTTPS), 또는 22 (SSH)와 다른 호스트 포트를 사용하려면 docker run 명령에 별도의 --publish 지시문을 추가해야 합니다.
예를 들어, 웹 인터페이스를 호스트의 포트 8929로, SSH 서비스를 포트 2424로 노출하려면:
-
다음과 같은
docker run명령을 사용합니다:sudo docker run --detach \ --hostname gitlab.example.com \ --env GITLAB_OMNIBUS_CONFIG="external_url 'http://gitlab.example.com:8929'; gitlab_rails['gitlab_shell_ssh_port'] = 2424" \ --publish 8929:8929 --publish 2424:2424 \ --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참고: 포트를 노출하는 형식은
호스트포트:컨테이너포트입니다. 자세한 내용은 Docker 문서의 들어오는 포트 노출을 참조하십시오. -
실행 중인 컨테이너에 들어갑니다:
sudo docker exec -it gitlab /bin/bash -
에디터를 사용하여
/etc/gitlab/gitlab.rb를 열고external_url을 설정합니다:# HTTP의 경우 external_url "http://gitlab.example.com:8929" 또는 # HTTPS의 경우 (https를 주목해 주세요) external_url "https://gitlab.example.com:8929"이 URL에 지정된 포트는 Docker에 의해 호스트에 노출된 포트와 일치해야 합니다. 또한, 만약 NGINX의 listen 포트가 명시적으로 설정되지 않은 경우,
nginx['listen_port']에서 가져올 것입니다. 자세한 내용은 NGINX 문서를 참조하십시오. -
SSH 포트를 설정합니다:
gitlab_rails['gitlab_shell_ssh_port'] = 2424 -
마지막으로, GitLab을 다시 구성합니다:
gitlab-ctl reconfigure
위의 예시를 따르면, 웹 브라우저에서 <호스트IP>:8929로 GitLab에 접근하고, SSH를 사용하여 포트 2289로 push할 수 있게 됩니다.
다른 포트를 사용하는 docker-compose.yml 예시는 Docker compose 섹션에서 찾을 수 있습니다.
여러 데이터베이스 연결 구성
GitLab 16.0에서 GitLab은 동일한 PostgreSQL 데이터베이스를 가리키는 두 개의 데이터베이스 연결을 기본값으로 사용합니다.
어떠한 이유로 인해 단일 데이터베이스 연결로 전환하고 싶다면:
-
컨테이너 내부의
/etc/gitlab/gitlab.rb을 편집합니다:sudo docker exec -it gitlab editor /etc/gitlab/gitlab.rb -
다음 라인을 추가합니다:
gitlab_rails['databases']['ci']['enable'] = false -
컨테이너를 다시 시작합니다:
sudo docker restart gitlab
권장되는 다음 단계
설치를 완료한 후, 권장되는 다음 단계를 고려해보세요. 이에는 인증 옵션 및 가입 제한 등이 포함됩니다.
업그레이드
대부분의 경우에는 GitLab을 업그레이드하는 것은 최신 Docker 이미지 태그를 다운로드하는 것만큼 쉽습니다.
Docker Engine을 사용하여 GitLab 업그레이드
Docker Engine을 사용하여 설치한 경우 GitLab을 업그레이드하려면:
-
실행 중인 컨테이너를 중지하세요:
sudo docker stop gitlab -
기존 컨테이너를 제거하세요:
sudo docker rm gitlab -
새 이미지를 가져오세요:
sudo docker pull gitlab/gitlab-ee:<version>-ee.0 -
GITLAB_HOME환경 변수가 정의되었는지 확인하세요:echo $GITLAB_HOME -
이전에 지정한 것과 동일한 옵션으로 컨테이너를 다시 생성하세요:
sudo docker run --detach \ --hostname 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은 재구성하고 자체를 업그레이드합니다.
버전 간에 업그레이드할 때 GitLab 업그레이드 권장 사항을 참조하세요.
Docker compose를 사용하여 GitLab 업그레이드
Docker Compose을 사용하여 설치한 경우 GitLab을 업그레이드하려면:
-
docker-compose.yml을 편집하고 가져올 버전을 변경하세요. -
최신 릴리스를 다운로드하고 GitLab 인스턴스를 업그레이드하세요:
docker compose pull docker compose up -d
커뮤니티 에디션을 엔터프라이즈 에디션으로 전환
기존 Docker 기반의 GitLab 커뮤니티 에디션 (CE) 컨테이너를 GitLab 엔터프라이즈 에디션 (EE) 컨테이너로 전환할 수 있습니다. 이는 버전을 업그레이드하는 것과 동일한 방식으로 진행됩니다.
우리는 CE의 동일한 버전에서 EE로 변환하는 것을 권장합니다 (예: CE 14.1에서 EE 14.1로). 이것은 명시적으로 필요한 것은 아니며 표준 업그레이드 (예: CE 14.0에서 EE 14.1로)가 작동해야 합니다. 다음 단계는 동일한 버전을 업그레이드하는 것으로 가정합니다.
-
현재 CE 컨테이너를 중지하고 제거하거나 이름을 바꿉니다.
-
GitLab EE로 새 컨테이너를 생성하려면
docker run명령 또는docker-compose.yml파일에서ce를ee로 바꾸세요. 그러나 CE 컨테이너의 이름, 포트 및 파일 매핑, 버전은 재사용합니다.
GitLab 다운그레이드
업그레이드 후 GitLab을 다운그레이드하려면:
-
다운그레이드할 버전을 지정하여 업그레이드 절차를 따르세요.
-
업그레이드의 일환으로 만든 데이터베이스 백업을 복원하세요.
- 복원이 필요한 이유: 업그레이드 중에 만들어진 데이터베이스 데이터 및 스키마 변경 (마이그레이션)을 되돌리기 위해 필요합니다.
- GitLab 백업은 정확히 동일한 버전과 에디션으로 복원되어야 합니다.
-
Docker 이미지에 대한 복원 단계를 따르되,
Puma와 Sidekiq을 중지하는 것까지만 수행하세요. 데이터베이스만 복원해야 하므로
gitlab-backup restore명령줄 인수에SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state를 추가하세요.
GitLab 백업
다음 명령어로 GitLab 백업을 생성할 수 있습니다:
docker exec -t <container name> gitlab-backup create
GitLab을 백업하고 복원하는 방법에 대해 더 알아보세요.
참고:
만약 구성이 GITLAB_OMNIBUS_CONFIG 환경 변수를 통해 완전히 제공되며
즉, gitlab.rb 파일에 구성이 직접 설정되지 않은 경우에는
gitlab.rb 파일을 백업할 필요가 없습니다.
경고:
GitLab 비밀 파일을 백업하는 것이 권장됩니다.
백업을 피하기 위한 복잡한 단계를 피하기 위해 필요합니다.
비밀 파일은 컨테이너 내부의 /etc/gitlab/gitlab-secrets.json에 저장되거나
컨테이너 호스트의 $GITLAB_HOME/config/gitlab-secrets.json에 저장됩니다.
데이터베이스 백업 생성
문제가 발생할 경우 GitLab 업그레이드를 롤백하기 위해 데이터베이스 백업이 필요합니다.
docker exec -t <container name> gitlab-backup create SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state
백업은 /var/opt/gitlab/backups에 작성되며, 이는 도커에 의해 마운트된 볼륨에 있어야 합니다.
문제 해결
다음 정보는 Linux 패키지와 Docker를 사용한 설치에서 문제가 발생할 경우 도움이 될 것입니다.
잠재적 문제 진단
컨테이너 로그 확인:
sudo docker logs gitlab
실행 중인 컨테이너에 접속:
sudo docker exec -it gitlab /bin/bash
컨테이너 내에서는 일반적으로 Linux 패키지 설치와 같이 GitLab 컨테이너를 관리할 수 있습니다.
500 내부 오류
도커 이미지를 업데이트하는 동안 모든 경로에서 500 페이지가 표시되는 문제가 발생할 수 있습니다. 이 경우 문제를 해결하기 위해 컨테이너를 다시 시작해 보세요:
sudo docker restart gitlab
권한 문제
이전 GitLab 도커 이미지에서 업데이트하는 경우 권한 문제가 발생할 수 있습니다. 이 문제는 이전 이미지의 사용자가 올바르게 보존되지 않은 경우에 발생합니다. 모든 파일에 대한 권한을 수정하는 스크립트가 있습니다.
컨테이너를 수정하려면 update-permissions를 실행한 후 컨테이너를 다시 시작하세요:
sudo docker exec gitlab update-permissions
sudo docker restart gitlab
Windows/Mac: Error executing action run on resource ruby_block[directory resource: /data/GitLab]
이 오류는 Windows 또는 Mac에서 Docker Toolbox 및 Docker 볼륨을 사용하는 경우에 발생하며, /c/Users 볼륨이 VirtualBox 공유 폴더로 마운트되어 있고 모든 POSIX 파일 시스템 기능을 지원하지 않을 때 발생합니다. 디렉토리 소유권과 권한은 다시 마운트하지 않고 변경할 수 없으며 이로 인해 GitLab에서 실패합니다.
권장하는 해결책은 플랫폼의 기본 Docker 설치를 사용하는 것입니다. 이를 사용할 수 없는 경우(Windows 10 홈 에디션 또는 Windows 7/8), Docker Toolbox의 boot2docker에 대해 VirtualBox 공유 대신 NFS 마운트를 설정하는 대체 솔루션이 있습니다.
Linux ACL 문제
Docker 호스트에서 파일 ACL을 사용하는 경우, GitLab이 작동하려면 docker 그룹이 볼륨에 대한 완전한 액세스 권한이 필요합니다:
getfacl $GITLAB_HOME
# file: $GITLAB_HOME
# owner: XXXX
# group: XXXX
user::rwx
group::rwx
group:docker:rwx
mask::rwx
default:user::rwx
default:group::rwx
default:group:docker:rwx
default:mask::rwx
default:other::r-x
이것들이 올바르지 않은 경우 다음과 같이 설정하세요:
sudo setfacl -mR default:group:docker:rwx $GITLAB_HOME
기본 그룹은 docker입니다. 그룹을 변경했다면 명령을 업데이트하세요.
도커 컨테이너에서 충분한 공간이 없는 ‘/dev/shm’ 마운트
GitLab은 /-/metrics에서 프라메테우스 메트릭스 엔드포인트를 제공하여 GitLab의 상태 및 성능에 관한 다양한 통계를 노출시킵니다. 이를 위해 필요한 파일은 임시 파일 시스템(예: /run 또는 /dev/shm)에 작성됩니다.
기본값으로, Docker는 공유 메모리 디렉토리(``/dev/shm`으로 마운트됨)에 64MB를 할당합니다. 이는 생성된 프라메테우스 메트릭스 관련 파일을 모두 보유하기에는 충분하지 않으며 다음과 같은 오류 로그가 생성됩니다:
writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/gauge_all_sidekiq_0-1.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
writing value to /dev/shm/gitlab/sidekiq/histogram_sidekiq_0-0.db failed with unmapped file
프라메테우스 메트릭스를 비활성화하는 것 외에도 이 문제를 해결하는 권장 솔루션은 공유 메모리 크기를 최소 256MB로 증가하는 것입니다. docker run을 사용하는 경우 --shm-size 256m 플래그를 전달하여 수행할 수 있습니다. docker-compose.yml 파일을 사용하는 경우 shm_size 키를 사용할 수 있습니다.
Docker 컨테이너가 json-file로 공간을 과다 사용함
Docker는 기본 로깅 드라이버로 json-file을 사용합니다, 이 드라이버는 기본적으로 로그 로테이션을 수행하지 않습니다. 이로 인해 로테이션 부재로 인해 json-file 드라이버에 의해 저장된 로그 파일이 많은 출력을 생성하는 컨테이너의 디스크 공간을 상당량 소비할 수 있습니다. 이는 디스크 공간 고갈로 이어질 수 있습니다. 이 문제를 해결하기 위해 가능한 경우 로깅 드라이버로 journald를 사용하거나 네이티브 로테이션 지원을 갖는 다른 지원되는 드라이버를 사용하세요.
Docker 시작 시 버퍼 오버플로 오류
이 버퍼 오버플로 오류가 발생하면, /var/log/gitlab에서 이전 로그 파일을 청소해야 합니다:
buffer overflow detected : terminated
xargs: tail: terminated by signal 6
이전 로그 파일을 제거하면 오류가 수정되고 인스턴스가 깨끗한 상태에서 시작됩니다.
ThreadError 스레드 생성 불가, 조작이 허용되지 않음
can't create Thread: Operation not permitted
이 오류는 새로운 glibc 버전으로 빌드된 컨테이너를 새로운 clone3 함수를 지원하지 않는 호스트에서 실행할 때 발생합니다. GitLab 16.0 이상에서는 이러한 새로운 glibc로 빌드된 Ubuntu 22.04 Linux 패키지를 컨테이너 이미지에 포함합니다.
이 문제는 Docker 20.10.10 등의 새로운 컨테이너 런타임 도구로 수정할 수 있습니다.
이 문제를 해결하려면, Docker를 20.10.10 버전 이상으로 업데이트하세요.
도움말