GitLab 개요¶

GitLab Community Edition(CE)을 기준으로 설치 및 운영을 위한 전체 구조와 기본 원칙을 정의함.

1. GitLab의 역할¶

GitLab은 소스 코드 관리와 협업을 위한 통합 DevOps 플랫폼임.

주요 기능은 다음과 같음:

Git 기반 소스 코드 관리 (Repository)
이슈 및 프로젝트 관리
CI/CD 파이프라인
Container Registry
사용자 및 권한 관리

등등.

2. 기본 아키텍처¶

GitLab은 단일 애플리케이션이 아니라 여러 구성요소로 이루어진 시스템임.

대표 구성요소:

Nginx
- GitLab 패키지에 포함된 웹 서버
- HTTP 요청 수신 및 reverse proxy 역할 수행
- 외부 Reverse Proxy(Nginx)를 사용하는 경우, GitLab 내부 Nginx는 백엔드 역할로 동작함
GitLab Workhorse
- 파일 업로드, 다운로드, Git HTTP 처리
Puma
- Rails 애플리케이션 실행
PostgreSQL
- 데이터베이스
Redis
- 캐시 및 세션 관리
Gitaly
- Git 저장소 처리

기본 요청 흐름:

2.1 단일 서버 환경¶

Client → Nginx → Workhorse → Puma → DB/Redis/Gitaly

2.2 Reverse Proxy 환경¶

Client → Reverse Proxy → GitLab Nginx → Workhorse → Puma → DB/Redis/Gitaly

3. 배포 방식¶

GitLab은 다음과 같은 방식으로 설치할 수 있음.

3-1. Linux package¶

GitLab 공식 패키지
모든 구성요소 포함
설치 및 업그레이드가 단순함

👉 기본 운영 환경에서는 Linux package 사용을 권장함

3-2. Docker¶

컨테이너 기반 배포
빠른 테스트 및 단일 인스턴스 운영에 적합

3-3. Source install¶

직접 빌드 및 구성
고급 커스터마이징이 필요한 경우에만 사용

4. 네트워크 구성 방식¶

GitLab은 다양한 네트워크 구조에서 운영될 수 있음.

4-1. 단일 서버 직접 노출¶

Client → GitLab Server

가장 단순한 구조
테스트 또는 소규모 환경에 적합

4-2. Reverse Proxy 뒤 운영¶

Client → Reverse Proxy → GitLab

TLS 종료
도메인 기반 라우팅
보안 정책 적용
GitLab 서버를 외부로 직접 노출하지 않음
내부 서비스 보호 (Gateway 패턴)

👉 실무 환경에서 가장 일반적으로 사용되는 방식임

4-3. Load Balancer / 분산 구조¶

Client → Load Balancer → Multiple GitLab Nodes

고가용성(HA)
대규모 트래픽 대응

5. 저장소 및 데이터 구조¶

GitLab은 다음과 같은 데이터를 관리함:

Git Repository
데이터베이스
업로드 파일
CI/CD artifacts
로그

데이터는 OS 영역과 분리하여 관리하는 것을 권장함.

예시:

/gitlab
 ├── data       # /var/opt/gitlab
 ├── logs       # /var/log/gitlab
 ├── packages   # /var/opt/gitlab/gitlab-rails/shared/packages
 ├── artifacts  # /var/opt/gitlab/gitlab-rails/shared/artifacts
 ├── uploads    # /var/opt/gitlab/gitlab-rails/uploads
 ├── lfs        # /var/opt/gitlab/gitlab-rails/shared/lfs-objects
 └── backups    # /var/opt/gitlab/backups, backup_path

※ 경로는 환경에 따라 자유롭게 변경 가능함

※ GitLab Omnibus 패키지의 기본 경로는 다음과 같음:

Data: /var/opt/gitlab
Log: /var/log/gitlab
Config: /etc/gitlab

운영 환경에서는 별도 디스크 또는 경로로 분리하는 것을 권장함

6. 주요 운영 원칙¶

6-1. external_url 기준 설정¶

GitLab은 external_url 값을 기준으로 동작함
GitLab 내부 URL 생성(redirect, clone URL 등)에 사용됨
반드시 사용자 접근 URL과 일치해야 함

6-2. Reverse Proxy 환경 고려¶

X-Forwarded-* 헤더 전달 필요
trusted proxy 설정 필요
Host 헤더 유지 필요 (proxy_set_header Host $host)

6-3. 메일 시스템 구성¶

SMTP 기반 메일 설정을 권장함
계정 생성, 알림, 비밀번호 재설정에 필수

6-4. SSH 정책 분리¶

Git SSH와 관리자 SSH를 분리하는 것을 권장함
포트 또는 접근 정책 기준으로 구분 가능함
Git SSH는 개발자 접근 기준으로 허용
관리자 SSH는 최소 IP 기준으로 제한 (/32 권장)

6-5. 데이터 백업 필수¶

GitLab 운영에서 백업은 선택이 아니라 필수임
정기 백업 및 복구 검증 필요

6-6. 업그레이드 관리¶

GitLab은 정기적인 업그레이드가 필요함
버전 간 호환성 및 migration 고려 필요

6-7. Gateway 기반 접근 통제¶

외부 사용자는 Reverse Proxy를 통해서만 GitLab에 접근해야 함
GitLab 서버는 내부망에서만 접근 가능하도록 구성함
직접 접근 경로는 방화벽으로 차단해야 함

7. 적용 범위¶

다음 환경을 모두 포함함:

온프레미스 서버
클라우드 인스턴스
단일 서버 구성
Reverse Proxy 환경
Load Balancer 환경

특정 인프라에 종속되지 않는 범용 기준을 제공함.