GitLab에 Docker Registry 서버 만들기

사내 또는 고객사 환경에서 Docker Registry가 필요할 때 AWS ECR이나 ACR 같은

퍼블릭 Registry를 사용하지 못하는 경우가 있습니다.
이번 글에서는 GitLab에 내장된 Registry 기능을 활성화하여 자체 Docker Registry를 구성하는 방법을 정리했습니다.

핵심 목표는 이미 만들어진 Docker 이미지를 외부 고객사에게 제공하기 위한 Registry 서버 구축입니다.

 

---

1. 구성 개요

✔ 사용 환경

• GitLab 이미지: gitlab/gitlab-ce:18.4.3-ce.0
• Docker Compose 기반 설치
• GitLab + Registry 동일 컨테이너에서 운영
• HTTPS 적용 가능 (선택)
• 외부 Nginx Proxy 적용 가능 (선택)

✔ 목적

• GitLab의 소스 관리 기능 뿐만 아니라 Docker Registry 기능도 사용
• 이미지 제공용 Private Registry 구축

✔ 대안

• AWS ECR
• Azure ACR
• Docker Registry
• Nexus Repository Docker Hosted

그러나 폐쇄망 또는 고객사 요구사항에 따라 GitLab Registry가 가장 단순하고 빠름.

---

2. GitLab CE 설치 (Docker Compose)

📁 2-1. .env 파일

IMGAGE=gitlab/gitlab-ce
TAG=18.4.3-ce.0

PORT=8084
CONTAINER_NAME=gitlab

GITLAB_HOSTNAME=gitlab.example.com (예시)
GITLAB_EXTERNAL_URL=http://gitlab.example.com (예시)

Registry

GITLAB_REGISTRY_URL=docker.example.com (예시)
GITLAB_REGISTRY_PORT=5000

GitLab Ports

GITLAB_HTTP_PORT=8080
GITLAB_SSH_PORT=8022

SHM_SIZE=512m

📁 2-2. docker-compose.yml 파일

services:
  gitlab:
  image: ${IMGAGE}:${TAG}
  container_name: ${CONTAINER_NAME}
  restart: always
  hostname: ${GITLAB_HOSTNAME}
  ports:
    - ${GITLAB_HTTP_PORT}:80
    # - 443:443  # 필요 시 활성화 (ex. gitlab 내장 nginx로 인증서 적용 시)
    - ${GITLAB_SSH_PORT}:22
    - ${GITLAB_REGISTRY_PORT}:${GITLAB_REGISTRY_PORT}

  volumes:
    - ./gitlab/config:/etc/gitlab
    - ./gitlab/logs:/var/log/gitlab
    - ./gitlab/data:/var/opt/gitlab

  shm_size: ${SHM_SIZE}

3. GitLab Registry 활성화

📄 3-1. gitlab.rb 수정

registry_external_url 'https://docker.example.com'
gitlab_rails['registry_enabled'] = true
gitlab_rails['registry_host'] = "docker.example.com"
gitlab_rails['registry_port'] = "5000"
gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"
gitlab_rails['registry_api_url'] = "https://docker.example.com"
gitlab_rails['registry_issuer'] = "docker.example.com"

registry['enable'] = true
registry['registry_http_addr'] = "0.0.0.0:5000"

registry_nginx['enable'] = false

 

- gitlab 설정값 반영 (재설정)

docker exec -it gitlab gitlab-ctl reconfigure

4. Registry 도메인 구성

GitLab UI와 Registry는 서로 다른 도메인을 사용해도 문제 없습니다.

GitLab: gitlab.example.com

Registry: docker.example.com:5000

 

5. Docker Registry 사용법

Gitlab의 Private Registry서버의 Docker Image는 다음과 같이 표기됩니다.

https://docker.example.com/group/project/image_name:tag
#  레지스트리 서버 도메인     /  그룹 / 프로젝트 / 이미지   :  태그

 

- gitlab UI에서 접속하여 Docker Registry 환경을 세팅해봅시다.

0) (Gitlab 최초 생성 시) Groups 생성하기

  - (로그인 후 첫 화면에서) Create Group - Ctreate Group

 

  - 내용은 아무거나 기입해도 상관없음

 

1) Docker Image가 저장될 Registry project 생성

 

 

 

 

2) Registry 생성 여부 확인하기
(사이드바)Deploy - Container Registry

- 위와 같이 사이드바에서 조회된다면 구축 완료. (Registry 설정이 활성화 되어있지 않다면 조회가 안됨.)

 

3) 사용하기

# 로그인
docker login docker.example.com:5000


# 이미지 태깅 (기존 이미지 : 레지스트리에 푸시할 이미지 형식)
## 레지스트리 이미지 이름 형식 : Registry_host/group/project/image_name:tag
docker tag myapp:latest docker.example.com:5000/project/myapp:latest


# 이미지 Push
docker push docker.example.com:5000/project/myapp:latest

예시

 

 

6. (옵션) HTTPS 사용을 권장합니다.

HTTP-only 환경이라면 Docker 설정에 insecure registry 추가 필요:

nano /etc/docker/daemon.json

 

•  아래 내용 기입

{
"insecure-registries": ["xgen-docker.example.com:5000"]
}

 

7. (옵션) Nginx Reverse Proxy 구성

server {
listen 443 ssl;
server_name docker.example.com;

ssl_certificate /etc/ssl/certs/fullchain.pem;
ssl_certificate_key /etc/ssl/private/privkey.pem;

location /v2/ {
    proxy_pass http://127.0.0.1:5000/v2/;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

 

8. 문제 해결 포인트

 

✔ Registry 로그 위치

/var/log/gitlab/registry/current

✔ GitLab Rails 로그 위치

/var/log/gitlab/gitlab-rails/production.log
✔ 인증 실패 Top 3 원인

• registry_issuer 불일치
• SSL 인증서 문제
• JWT 토큰 검증 오류

마무리

GitLab CE Registry는 별도 Registry 서버 없이 내장 기능으로 Private Registry를 쉽게 구성할 수 있어 폐쇄망 환경에서 유리합니다.
실제 고객사 이미지 배포용 Registry 구성 경험을 바탕으로 작성한 내용이며
운영 환경에 따라 SSL, 프록시 등 다양한 커스터마이징을 적용할 수 있습니다.