CI CD

GitLab 설치 방식: Omnibus vs Docker 어떤 방식을 선택해야 할까?

JohnnyDeveloper 2026. 1. 19. 17:22

GitLab 설치 방식 완벽 가이드: Omnibus vs Docker

GitLab 설치 방식 완벽 가이드

Omnibus vs Docker: 어떤 방식을 선택해야 할까?

Omnibus Package Docker Container 비교 분석

💡

이 글의 대상

GitLab을 처음 설치하거나, Omnibus와 Docker 중 어떤 방식을 선택할지 고민하는 개발자 및 DevOps 엔지니어를 위한 가이드입니다.

GitLab 설치 방식 개요

GitLab을 설치하는 방법은 크게 두 가지입니다:

📦

Omnibus Package

모든 컴포넌트가 하나의 패키지로 번들된 방식입니다.

GitLab, PostgreSQL, Redis, NGINX가 하나의 패키지
gitlab-ctl 명령어로 통합 관리
/etc/gitlab/gitlab.rb 하나로 모든 설정

🐳

Docker Container

각 서비스가 별도 컨테이너로 분리된 방식입니다.

GitLab, PostgreSQL, Redis가 각각 컨테이너
Docker Compose로 관리
환경 변수 또는 볼륨으로 설정

Omnibus Package 방식

아키텍처

Omnibus GitLab 구조

GitLab Omnibus Package

GitLab Rails

PostgreSQL

Redis

NGINX

Gitaly

Sidekiq

↑ 모든 컴포넌트가 하나의 시스템 프로세스 그룹으로 실행

설치 방법

# Ubuntu/Debian
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash
sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee

# CentOS/RHEL
curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.rpm.sh | sudo bash
sudo EXTERNAL_URL="https://gitlab.example.com" yum install gitlab-ee

주요 관리 명령어

# GitLab 재설정 (gitlab.rb 변경 후 필수)
sudo gitlab-ctl reconfigure

# 서비스 재시작
sudo gitlab-ctl restart

# 특정 서비스만 재시작
sudo gitlab-ctl restart nginx
sudo gitlab-ctl restart sidekiq

# 상태 확인
sudo gitlab-ctl status

# 로그 확인
sudo gitlab-ctl tail
sudo gitlab-ctl tail nginx

# 백업
sudo gitlab-backup create

# 복원
sudo gitlab-backup restore BACKUP=1610123456_2026_01_19

설정 파일 구조

Omnibus의 가장 큰 장점은 모든 설정이 하나의 파일에 집중된다는 점입니다.

# /etc/gitlab/gitlab.rb

## 외부 URL 설정
external_url 'https://gitlab.example.com'

## PostgreSQL 설정
postgresql['shared_buffers'] = "256MB"
postgresql['max_connections'] = 200

## Redis 설정
redis['maxmemory'] = "2gb"

## NGINX 설정
nginx['listen_port'] = 80
nginx['listen_https'] = true

## GitLab Rails 설정
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'
gitlab_rails['time_zone'] = 'Asia/Seoul'

## 백업 설정
gitlab_rails['backup_keep_time'] = 604800 # 7일

✅

설정 변경 후 반드시 실행

/etc/gitlab/gitlab.rb를 수정한 후에는 반드시 sudo gitlab-ctl reconfigure를 실행해야 변경사항이 적용됩니다.

장단점

✅ 장점

설치 간편: 한 줄 명령어로 완료
중앙 집중 설정: gitlab.rb 하나로 모든 설정
통합 관리: gitlab-ctl로 모든 서비스 제어
자동 업데이트: 패키지 매니저로 업그레이드
안정성: GitLab 팀이 최적화한 구성
백업 간편: gitlab-backup 명령어 하나로 완료

❌ 단점

리소스 사용: 모든 서비스가 항상 실행
유연성 제한: 외부 DB 연동이 복잡
버전 고정: 번들된 PostgreSQL/Redis 버전 고정
다중 인스턴스 어려움: 한 서버에 여러 GitLab 설치 불가
커스터마이징 제한: 내부 구성 변경 어려움

Docker Container 방식

아키텍처

Docker GitLab 구조

GitLab Container

gitlab/gitlab-ee

PostgreSQL Container

postgres:14

Redis Container

redis:7-alpine

↑ 각 서비스가 독립적인 컨테이너로 실행 (Docker 네트워크로 연결)

설치 방법 (Docker Compose)

# docker-compose.yml
version: '3.8'

services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.example.com'
        gitlab_rails['time_zone'] = 'Asia/Seoul'
    ports:
      - '80:80'
      - '443:443'
      - '22:22'
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    networks:
      - gitlab

  postgresql:
    image: 'postgres:14-alpine'
    environment:
      POSTGRES_DB: gitlabhq_production
      POSTGRES_USER: gitlab
      POSTGRES_PASSWORD: secure_password
    volumes:
      - './postgresql:/var/lib/postgresql/data'
    networks:
      - gitlab

  redis:
    image: 'redis:7-alpine'
    volumes:
      - './redis:/data'
    networks:
      - gitlab

networks:
  gitlab:
    driver: bridge

주요 관리 명령어

# 컨테이너 시작
docker-compose up -d

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f gitlab
docker-compose logs -f postgresql

# 컨테이너 재시작
docker-compose restart gitlab

# 컨테이너 내부 접속
docker exec -it gitlab bash

# GitLab 백업 (컨테이너 내부)
docker exec -t gitlab gitlab-backup create

# 컨테이너 중지
docker-compose down

장단점

✅ 장점

서비스 분리: 각 컴포넌트 독립 관리
유연성: DB/Redis 버전 자유 선택
스케일 아웃: 서비스별 스케일링 가능
격리: 컨테이너 간 완벽 격리
다중 인스턴스: 한 서버에 여러 GitLab 가능
이식성: docker-compose.yml로 쉽게 이전

❌ 단점

설정 복잡: docker-compose.yml 작성 필요
네트워크 관리: 컨테이너 간 통신 설정
볼륨 관리: 데이터 영속성 직접 관리
업데이트 복잡: 각 이미지 버전 관리
트러블슈팅 어려움: 여러 로그 확인 필요
백업 복잡: 여러 볼륨 백업 필요

비교 분석

핵심 차이점

항목	Omnibus	Docker
설치 난이도	⭐ 쉬움 (한 줄)	⭐⭐⭐ 보통 (Compose 작성)
설정 관리	✅ gitlab.rb 하나	⚠️ Compose + 환경변수
서비스 관리	✅ gitlab-ctl 통합	⚠️ docker-compose 개별
리소스 사용	⚠️ 높음 (모든 서비스 실행)	✅ 효율적 (필요한 것만)
업데이트	✅ 패키지 매니저	⚠️ 이미지 태그 변경
백업/복원	✅ gitlab-backup 명령어	⚠️ 여러 볼륨 관리
유연성	⚠️ 제한적	✅ 높음
스케일링	⚠️ 수직 확장만	✅ 수평/수직 모두
다중 인스턴스	❌ 불가능	✅ 가능
안정성	✅ 매우 높음	⭐⭐⭐ 보통

메모리 사용량 비교

구성	Omnibus (최소)	Docker (최소)
GitLab	2GB	2GB
PostgreSQL	512MB (포함)	256MB (별도)
Redis	256MB (포함)	128MB (별도)
NGINX	128MB (포함)	포함 또는 별도
총합	~3GB	~2.5GB

💡

실제 권장 메모리

GitLab 공식 문서는 최소 4GB, 권장 8GB를 제안합니다. 위 수치는 각 컴포넌트의 최소 요구사항이며, 실제 운영 시에는 여유분이 필요합니다.

선택 가이드

Omnibus를 선택해야 하는 경우

🚀

빠른 시작이 필요

프로토타입이나 POC를 위해 빠르게 GitLab을 설치하고 싶을 때

🎯

단일 인스턴스 운영

한 서버에 하나의 GitLab만 운영하고, 외부 DB 연동 불필요

📦

통합 관리 선호

gitlab-ctl 하나로 모든 서비스를 관리하고 싶을 때

🛡️

안정성 최우선

GitLab 팀이 검증한 기본 구성으로 안정적 운영

Docker를 선택해야 하는 경우

🔧

유연한 구성 필요

PostgreSQL/Redis 버전을 자유롭게 선택하거나 외부 서비스 연동

📊

마이크로서비스 환경

이미 Docker/Kubernetes로 인프라를 관리하고 있을 때

🎭

다중 인스턴스

한 서버에 여러 GitLab 인스턴스를 운영해야 할 때

⚖️

스케일링

서비스별로 독립적인 스케일링이 필요할 때

실전 예시: Omnibus 서버

이 서버는 Omnibus 방식으로 설치되었습니다. 실제 사용 사례를 살펴봅시다.

현재 서버 구성 확인

# GitLab 버전 확인
sudo gitlab-rake gitlab:env:info

# 출력 예시:
# System:         Ubuntu 22.04
# GitLab:         16.7.0-ee
# PostgreSQL:     14.10
# Redis:          7.0.12

# 실행 중인 서비스 확인
sudo gitlab-ctl status

# 출력 예시:
# run: gitaly: (pid 12345) 1234s; run: log: (pid 12346) 1234s
# run: gitlab-workhorse: (pid 12347) 1234s; run: log: (pid 12348) 1234s
# run: logrotate: (pid 12349) 1234s; run: log: (pid 12350) 1234s
# run: nginx: (pid 12351) 1234s; run: log: (pid 12352) 1234s
# run: postgresql: (pid 12353) 1234s; run: log: (pid 12354) 1234s
# run: redis: (pid 12355) 1234s; run: log: (pid 12356) 1234s
# run: sidekiq: (pid 12357) 1234s; run: log: (pid 12358) 1234s

일반적인 설정 변경 시나리오

gitlab.rb 파일 열기

sudo vim /etc/gitlab/gitlab.rb

설정 변경

# 예: 이메일 발신자 변경
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

# 예: 시간대 변경
gitlab_rails['time_zone'] = 'Asia/Seoul'

# 예: NGINX 포트 변경
nginx['listen_port'] = 8080

변경사항 적용

sudo gitlab-ctl reconfigure

# 필요시 재시작
sudo gitlab-ctl restart

확인

sudo gitlab-ctl status
sudo gitlab-rake gitlab:check

Omnibus의 장점이 빛나는 순간

✅ 실제 경험

백업 시나리오: Docker 방식이라면 GitLab, PostgreSQL, Redis 각각의 데이터를 백업해야 하지만, Omnibus는 단 하나의 명령어로 완료됩니다.

# Omnibus: 1줄로 완전 백업
sudo gitlab-backup create

# Docker: 여러 단계 필요
docker exec gitlab gitlab-backup create
docker exec postgresql pg_dump ...
docker exec redis redis-cli save
# + 각 볼륨 복사

마이그레이션 가이드

Omnibus → Docker 마이그레이션

⚠️

주의사항

운영 중인 GitLab을 마이그레이션하는 것은 다운타임이 발생합니다. 충분한 테스트 후 진행하세요.

Omnibus에서 백업 생성

sudo gitlab-backup create
sudo cp /etc/gitlab/gitlab.rb ~/gitlab.rb.backup
sudo cp /etc/gitlab/gitlab-secrets.json ~/gitlab-secrets.json.backup

Docker Compose 준비

위의 docker-compose.yml 예시를 참고하여 작성

백업 파일을 Docker 볼륨에 복사

docker-compose up -d
docker cp backup_file.tar gitlab:/var/opt/gitlab/backups/
docker cp gitlab-secrets.json gitlab:/etc/gitlab/

복원 실행

docker exec -it gitlab gitlab-backup restore BACKUP=backup_file

트러블슈팅

Omnibus 관련 이슈

문제: reconfigure가 실패함

# 로그 확인
sudo tail -f /var/log/gitlab/reconfigure/*.log

# 강제 재설정
sudo gitlab-ctl reconfigure --force

문제: 특정 서비스가 시작 안 됨

# 서비스 로그 확인
sudo gitlab-ctl tail postgresql

# 서비스 재시작
sudo gitlab-ctl restart postgresql

# HUP 시그널 전송 (설정 리로드)
sudo gitlab-ctl hup postgresql

Docker 관련 이슈

문제: 컨테이너 간 통신 실패

# 네트워크 확인
docker network inspect gitlab_gitlab

# 컨테이너 IP 확인
docker inspect gitlab | grep IPAddress

# 연결 테스트
docker exec gitlab ping postgresql

정리

상황	권장 방식
소규모 팀 (10명 미만)	✅ Omnibus
중대형 팀 (10~100명)	✅ Omnibus
대규모 엔터프라이즈 (100명+)	⚖️ 둘 다 가능 (요구사항에 따라)
빠른 POC/프로토타입	✅ Omnibus
외부 DB 연동 필요	✅ Docker
Kubernetes 환경	✅ Docker (Helm Chart)
다중 GitLab 인스턴스	✅ Docker
간편한 백업/복원	✅ Omnibus
서비스별 스케일링	✅ Docker

💡

결론

대부분의 경우 Omnibus를 권장합니다. GitLab 팀이 최적화한 구성으로 안정적이고, 설정과 관리가 간편합니다. Docker는 Kubernetes 환경, 다중 인스턴스, 또는 특별한 커스터마이징이 필요한 경우에 선택하세요.

참고 자료

GitLab Omnibus 공식 문서: https://docs.gitlab.com/omnibus/
GitLab Docker 공식 문서: https://docs.gitlab.com/ee/install/docker.html
GitLab 설치 방법 비교: https://about.gitlab.com/install/

⚡ 핵심 요약

Omnibus: 모든 컴포넌트 번들 + gitlab-ctl + gitlab.rb
Docker: 서비스 분리 + docker-compose + 환경변수
Omnibus 장점: 설치 간편, 통합 관리, 안정성
Docker 장점: 유연성, 스케일링, 다중 인스턴스
권장: 특별한 이유가 없다면 Omnibus 선택

'CI CD' 카테고리의 다른 글

GitLab에 왜 데이터베이스가 필요할까? (0)	2026.01.19
GitLab CI/CD 파이프라인 구축 가이드 (0)	2025.12.16

현재글GitLab 설치 방식: Omnibus vs Docker 어떤 방식을 선택해야 할까?

죠니의 개발일기

죠니의 기술 블로그 입니다.

bun, rootless, 타입스크립트, Python, CI/CD, spring boot, pm2, podman, 유효성 검사, docker, 비동기 프로그래밍, 클러스터링, cifs, GIT, node.js, Kotlin, zod, DevOps, PowerShell, Version Control,

Today :
Yesterday :

« 2026/04 »
일	월	화	수	목	금	토
			1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30

GitLab 설치 방식: Omnibus vs Docker 어떤 방식을 선택해야 할까?

GitLab 설치 방식 완벽 가이드

GitLab 설치 방식 개요

Omnibus Package

Docker Container

Omnibus Package 방식

아키텍처

설치 방법

주요 관리 명령어

설정 파일 구조

장단점

✅ 장점

❌ 단점

Docker Container 방식

아키텍처

설치 방법 (Docker Compose)

주요 관리 명령어

장단점

✅ 장점

❌ 단점

비교 분석

핵심 차이점

메모리 사용량 비교

선택 가이드

Omnibus를 선택해야 하는 경우

빠른 시작이 필요

단일 인스턴스 운영

통합 관리 선호

안정성 최우선

Docker를 선택해야 하는 경우

유연한 구성 필요

마이크로서비스 환경

다중 인스턴스

스케일링

실전 예시: Omnibus 서버

현재 서버 구성 확인

일반적인 설정 변경 시나리오

gitlab.rb 파일 열기

설정 변경

변경사항 적용

확인

Omnibus의 장점이 빛나는 순간

✅ 실제 경험

마이그레이션 가이드

Omnibus → Docker 마이그레이션

Omnibus에서 백업 생성

Docker Compose 준비

백업 파일을 Docker 볼륨에 복사

복원 실행

트러블슈팅

Omnibus 관련 이슈

문제: reconfigure가 실패함

문제: 특정 서비스가 시작 안 됨

Docker 관련 이슈

문제: 컨테이너 간 통신 실패

정리

참고 자료

⚡ 핵심 요약

'CI CD' 카테고리의 다른 글

'CI CD'의 다른글

관련글

티스토리툴바