Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션

요약

두 가지 방법 중 하나를 사용하여 기존 Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션하세요. 기존 데이터 디렉터리 재사용: 기존 데이터 디렉터리를 Docker 볼륨 경로로 이동합니다. 백업 후 복원: Linux 패키지 인스턴스에서 GitLab 백업을 생성하고, 새 Docker 인스턴스를 설정한 후 복원합니다.

두 가지 방법 중 하나를 사용하여 기존 Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션하세요.

기존 데이터 디렉터리 재사용: 기존 데이터 디렉터리를 Docker 볼륨 경로로 이동합니다. 전체 백업 및 복원 과정 없이 데이터를 그대로 유지하려면 이 방법을 사용하세요.
백업 후 복원: Linux 패키지 인스턴스에서 GitLab 백업을 생성하고, 새 Docker 인스턴스를 설정한 후 복원합니다. 필요 시 롤백을 지원하는 깔끔한 마이그레이션을 원한다면 이 방법을 사용하세요.

사전 조건#

Linux 패키지 인스턴스와 Docker 이미지의 GitLab 버전이 일치해야 합니다. 필요한 경우 Docker로 마이그레이션하기 전에 Linux 패키지 인스턴스를 업그레이드하세요.
타깃 서버에 Docker가 설치되어 있어야 합니다.

기존 데이터 디렉터리 재사용#

기존 데이터 디렉터리를 재사용하여 Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션합니다.

Linux 패키지 인스턴스 중지#

모든 GitLab 서비스를 중지합니다.

sudo gitlab-ctl stop

볼륨 디렉터리 준비#

볼륨 디렉터리 준비 방법은 Docker가 실행되는 위치에 따라 다릅니다.

Docker가 Linux 패키지 인스턴스와 동일한 서버에서 실행되는 경우, 디렉터리를 복사하지 않고 기존 디렉터리를 직접 마운트할 수 있습니다. Docker Compose 파일에서 볼륨 경로를 Linux 패키지 위치로 설정하세요.
```
volumes:
  - '/etc/gitlab:/etc/gitlab'
  - '/var/log/gitlab:/var/log/gitlab'
  - '/var/opt/gitlab:/var/opt/gitlab'
```
다른 서버로 이동하거나 Docker 볼륨을 Linux 패키지 경로와 분리하려는 경우, 먼저 디렉터리를 새 위치에 복사하세요.

$GITLAB_HOME을 타깃 디렉터리로 설정합니다.
```
export GITLAB_HOME=/srv/gitlab
sudo mkdir -p $GITLAB_HOME
```
데이터, 로그, 구성 디렉터리를 복사(또는 이동)합니다.
```
sudo cp -a /var/opt/gitlab $GITLAB_HOME/data
sudo cp -a /var/log/gitlab $GITLAB_HOME/logs
sudo cp -a /etc/gitlab     $GITLAB_HOME/config
```
이동하려면 cp -a 대신 mv를 사용하세요.

[!warning] 컨테이너를 시작하기 전에 호스트 디렉터리의 소유권을 root:root로 변경하지 마세요. 그렇게 하면 컨테이너가 시작되지 않으며, update-permissions 스크립트도 이후에 소유권을 수정하지 못합니다.

리포지터리 디렉터리가 존재하며 실제 디렉터리인지(깨진 심볼릭 링크가 아닌지) 확인하세요.
```
ls -la $GITLAB_HOME/data/git-data/repositories
```
디렉터리가 없거나 깨진 심볼릭 링크인 경우 생성하세요.
```
sudo mkdir -p $GITLAB_HOME/data/git-data/repositories
```

사용자 및 그룹 식별자 정렬#

GitLab Docker 이미지에는 update-permissions라는 내장 스크립트가 포함되어 있어 모든 GitLab 디렉터리에 올바른 소유권을 설정합니다. Linux 패키지 인스턴스가 Docker 이미지가 기대하는 것과 다른 UID를 사용한 경우(배포판마다 다른 OS 기본값이거나 명시적으로 구성된 값인 경우), 컨테이너를 시작하기 전에 볼륨을 마운트한 임시 컨테이너에서 update-permissions를 실행하세요. 이렇게 하면 첫 번째 시작 전에 소유권이 수정됩니다.

docker run --rm \
  -v <config_path>:/etc/gitlab \
  -v <logs_path>:/var/log/gitlab \
  -v <data_path>:/var/opt/gitlab \
  --entrypoint /bin/bash \
  gitlab/gitlab-ee:<version> \
  -c "update-permissions"

<config_path>, <logs_path>, <data_path>는 볼륨 디렉터리 준비에서 확인한 호스트 경로로 교체하세요.

Docker에서 GitLab 시작#

설치 지침을 따라 준비한 디렉터리를 마운트하는 Docker Compose 파일 또는 Docker Engine 명령을 생성하세요.

volumes:
  - '$GITLAB_HOME/config:/etc/gitlab'
  - '$GITLAB_HOME/logs:/var/log/gitlab'
  - '$GITLAB_HOME/data:/var/opt/gitlab'

컨테이너가 시작된 후 reconfigure를 실행합니다.

docker exec -it <container_name> gitlab-ctl reconfigure

설치를 확인합니다.

docker exec -it <container_name> gitlab-rake gitlab:check

Linux 패키지 인스턴스 백업 후 Docker 인스턴스에 복원#

Linux 패키지 인스턴스에서 백업 생성#

Linux 패키지 인스턴스를 중지하기 전에 백업을 생성합니다.

sudo gitlab-backup create

시크릿 파일을 안전한 위치에 복사합니다.

sudo cp /etc/gitlab/gitlab-secrets.json /your/backup/location/

자세한 내용은 GitLab 백업을 참조하세요.

Linux 패키지 인스턴스 중지#

모든 GitLab 서비스를 중지합니다.

sudo gitlab-ctl stop

Docker 인스턴스 설정#

설치 지침을 따라 새 Docker 인스턴스를 설정합니다. $GITLAB_HOME을 볼륨을 위해 생성한 디렉터리로 설정합니다. 예를 들면 다음과 같습니다.

export GITLAB_HOME=/srv/gitlab

컨테이너를 한 번 시작하여 볼륨 디렉터리를 초기화한 후, 복원 전에 중지합니다.

docker compose up -d
docker compose stop

백업 복원#

Docker 데이터 볼륨에 백업 아카이브를 복사합니다.

sudo cp <timestamp>_gitlab_backup.tar $GITLAB_HOME/data/backups/

Docker 구성 볼륨에 시크릿 파일을 복사합니다.

sudo cp gitlab-secrets.json $GITLAB_HOME/config/gitlab-secrets.json

컨테이너를 시작하고 복원을 실행합니다.

docker compose start
docker exec -it <container_name> gitlab-backup restore BACKUP=<timestamp>

복원이 완료된 후 reconfigure하고 재시작합니다.

docker exec -it <container_name> gitlab-ctl reconfigure
docker exec -it <container_name> gitlab-ctl restart

설치를 확인합니다.

docker exec -it <container_name> gitlab-rake gitlab:check

문제 해결#

Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션할 때 다음과 같은 문제가 발생할 수 있습니다.

시작 후 권한 오류#

컨테이너는 시작되었지만 권한 오류가 보고되는 경우 다음을 실행하세요.

sudo docker exec <container_name> update-permissions
sudo docker restart <container_name>

이 오류는 Linux 패키지 인스턴스가 Docker 이미지가 기대하는 것과 다른 UID를 시스템 계정에 사용했을 때 발생합니다. 이를 방지하려면 사용자 및 그룹 식별자 정렬에 설명된 대로 시작하기 전에 update-permissions를 실행하세요.

다른 인스턴스의 데이터 재사용 시 오류#

다른 인스턴스의 데이터를 재사용할 때 다음과 같은 문제가 발생할 수 있습니다.

시작 시 stat: missing operand 오류#

이 오류는 컨테이너가 git-data/repositories 디렉터리를 찾지 못할 때 발생합니다.

stat: missing operand
Expected process to exit with [0], but received '1'
Ran stat --printf='%U' $(readlink -f /var/opt/gitlab/git-data/repositories) returned 1

호스트에서 누락된 디렉터리를 생성한 후 컨테이너를 재시작합니다.

sudo mkdir -p $GITLAB_HOME/data/git-data/repositories
sudo docker restart <container_name>

컨테이너가 즉시 종료되고 재시작 루프로 인해 docker exec 차단#

컨테이너가 시작 직후 종료되면 docker exec를 사용하여 조사하거나 update-permissions를 실행할 수 없습니다. 대신 사용자 및 그룹 식별자 정렬의 명령을 사용하여 update-permissions를 직접 실행하세요. 이 명령은 볼륨을 마운트한 임시 컨테이너를 시작하여 메인 컨테이너가 실행 중이지 않아도 소유권을 수정합니다.

Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션

GitLab v19.1

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-06-19

요약

두 가지 방법 중 하나를 사용하여 기존 Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션하세요.

기존 데이터 디렉터리 재사용: 기존 데이터 디렉터리를 Docker 볼륨 경로로 이동합니다. 전체 백업 및 복원 과정 없이 데이터를 그대로 유지하려면 이 방법을 사용하세요.
백업 후 복원: Linux 패키지 인스턴스에서 GitLab 백업을 생성하고, 새 Docker 인스턴스를 설정한 후 복원합니다. 필요 시 롤백을 지원하는 깔끔한 마이그레이션을 원한다면 이 방법을 사용하세요.

사전 조건#

Linux 패키지 인스턴스와 Docker 이미지의 GitLab 버전이 일치해야 합니다. 필요한 경우 Docker로 마이그레이션하기 전에 Linux 패키지 인스턴스를 업그레이드하세요.
타깃 서버에 Docker가 설치되어 있어야 합니다.

기존 데이터 디렉터리 재사용#

기존 데이터 디렉터리를 재사용하여 Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션합니다.

Linux 패키지 인스턴스 중지#

모든 GitLab 서비스를 중지합니다.

sudo gitlab-ctl stop

볼륨 디렉터리 준비#

볼륨 디렉터리 준비 방법은 Docker가 실행되는 위치에 따라 다릅니다.

Docker가 Linux 패키지 인스턴스와 동일한 서버에서 실행되는 경우, 디렉터리를 복사하지 않고 기존 디렉터리를 직접 마운트할 수 있습니다. Docker Compose 파일에서 볼륨 경로를 Linux 패키지 위치로 설정하세요.
```
volumes:
  - '/etc/gitlab:/etc/gitlab'
  - '/var/log/gitlab:/var/log/gitlab'
  - '/var/opt/gitlab:/var/opt/gitlab'
```
다른 서버로 이동하거나 Docker 볼륨을 Linux 패키지 경로와 분리하려는 경우, 먼저 디렉터리를 새 위치에 복사하세요.

$GITLAB_HOME을 타깃 디렉터리로 설정합니다.
```
export GITLAB_HOME=/srv/gitlab
sudo mkdir -p $GITLAB_HOME
```
데이터, 로그, 구성 디렉터리를 복사(또는 이동)합니다.
```
sudo cp -a /var/opt/gitlab $GITLAB_HOME/data
sudo cp -a /var/log/gitlab $GITLAB_HOME/logs
sudo cp -a /etc/gitlab     $GITLAB_HOME/config
```
이동하려면 cp -a 대신 mv를 사용하세요.

[!warning] 컨테이너를 시작하기 전에 호스트 디렉터리의 소유권을 root:root로 변경하지 마세요. 그렇게 하면 컨테이너가 시작되지 않으며, update-permissions 스크립트도 이후에 소유권을 수정하지 못합니다.

리포지터리 디렉터리가 존재하며 실제 디렉터리인지(깨진 심볼릭 링크가 아닌지) 확인하세요.
```
ls -la $GITLAB_HOME/data/git-data/repositories
```
디렉터리가 없거나 깨진 심볼릭 링크인 경우 생성하세요.
```
sudo mkdir -p $GITLAB_HOME/data/git-data/repositories
```

사용자 및 그룹 식별자 정렬#

docker run --rm \
  -v <config_path>:/etc/gitlab \
  -v <logs_path>:/var/log/gitlab \
  -v <data_path>:/var/opt/gitlab \
  --entrypoint /bin/bash \
  gitlab/gitlab-ee:<version> \
  -c "update-permissions"

<config_path>, <logs_path>, <data_path>는 볼륨 디렉터리 준비에서 확인한 호스트 경로로 교체하세요.

Docker에서 GitLab 시작#

설치 지침을 따라 준비한 디렉터리를 마운트하는 Docker Compose 파일 또는 Docker Engine 명령을 생성하세요.

volumes:
  - '$GITLAB_HOME/config:/etc/gitlab'
  - '$GITLAB_HOME/logs:/var/log/gitlab'
  - '$GITLAB_HOME/data:/var/opt/gitlab'

컨테이너가 시작된 후 reconfigure를 실행합니다.

docker exec -it <container_name> gitlab-ctl reconfigure

설치를 확인합니다.

docker exec -it <container_name> gitlab-rake gitlab:check

Linux 패키지 인스턴스 백업 후 Docker 인스턴스에 복원#

Linux 패키지 인스턴스에서 백업 생성#

Linux 패키지 인스턴스를 중지하기 전에 백업을 생성합니다.

sudo gitlab-backup create

시크릿 파일을 안전한 위치에 복사합니다.

sudo cp /etc/gitlab/gitlab-secrets.json /your/backup/location/

자세한 내용은 GitLab 백업을 참조하세요.

Linux 패키지 인스턴스 중지#

모든 GitLab 서비스를 중지합니다.

sudo gitlab-ctl stop

Docker 인스턴스 설정#

설치 지침을 따라 새 Docker 인스턴스를 설정합니다. $GITLAB_HOME을 볼륨을 위해 생성한 디렉터리로 설정합니다. 예를 들면 다음과 같습니다.

export GITLAB_HOME=/srv/gitlab

컨테이너를 한 번 시작하여 볼륨 디렉터리를 초기화한 후, 복원 전에 중지합니다.

docker compose up -d
docker compose stop

백업 복원#

Docker 데이터 볼륨에 백업 아카이브를 복사합니다.

sudo cp <timestamp>_gitlab_backup.tar $GITLAB_HOME/data/backups/

Docker 구성 볼륨에 시크릿 파일을 복사합니다.

sudo cp gitlab-secrets.json $GITLAB_HOME/config/gitlab-secrets.json

컨테이너를 시작하고 복원을 실행합니다.

docker compose start
docker exec -it <container_name> gitlab-backup restore BACKUP=<timestamp>

복원이 완료된 후 reconfigure하고 재시작합니다.

docker exec -it <container_name> gitlab-ctl reconfigure
docker exec -it <container_name> gitlab-ctl restart

설치를 확인합니다.

docker exec -it <container_name> gitlab-rake gitlab:check

문제 해결#

Linux 패키지 GitLab 인스턴스를 Docker로 마이그레이션할 때 다음과 같은 문제가 발생할 수 있습니다.

시작 후 권한 오류#

컨테이너는 시작되었지만 권한 오류가 보고되는 경우 다음을 실행하세요.

sudo docker exec <container_name> update-permissions
sudo docker restart <container_name>

다른 인스턴스의 데이터 재사용 시 오류#

다른 인스턴스의 데이터를 재사용할 때 다음과 같은 문제가 발생할 수 있습니다.

시작 시 stat: missing operand 오류#

이 오류는 컨테이너가 git-data/repositories 디렉터리를 찾지 못할 때 발생합니다.

stat: missing operand
Expected process to exit with [0], but received '1'
Ran stat --printf='%U' $(readlink -f /var/opt/gitlab/git-data/repositories) returned 1

호스트에서 누락된 디렉터리를 생성한 후 컨테이너를 재시작합니다.

sudo mkdir -p $GITLAB_HOME/data/git-data/repositories
sudo docker restart <container_name>