[인프라/DevOps] Docker Compose로 나만의 GitLab 서버 구축하기: CE·EE 선택부터 SSH 포트 충돌·502 에러·백업까지 완벽 가이드

사내 인프라 스크립트, 자동화 코드, 개인 프로젝트 소스 코드를 외부 Git 호스팅 서비스에 두기 부담스러울 때가 있습니다. 이럴 때 자체 서버나 NAS 환경에 GitLab을 직접 올려두면 비공개 저장소, 이슈 트래킹, 위키, 그리고 CI/CD 파이프라인까지 한곳에서 독립적으로 운영할 수 있습니다.

이번 포스팅에서는 Docker Compose를 이용해 GitLab을 구축하는 전 과정을 단계별로 정리합니다. CE와 EE 이미지 선택 기준부터 실제 운영 환경에서 가장 많이 겪는 호스트 SSH(22번) 포트 충돌, 초기 부팅 지연 및 502 에러, 외부 HTTPS/리버스 프록시 연동 주의점, 그리고 백업·업그레이드 전략까지 실전 관점으로 상세히 다룹니다.

1. 구축 전 필수 체크리스트 및 CE vs EE 이미지 선택

GitLab은 단일 프로세스가 아니라 웹 서버, 백그라운드 워커, 데이터베이스, Redis 등 여러 컴포넌트가 함께 구동되는 구조이기 때문에 사양과 이미지를 먼저 확인해야 합니다.

1.1 권장 하드웨어 및 소프트웨어 사양

  • 메모리(RAM): 최소 4GB 이상 (스왑 메모리 병행 권장), 안정적인 실제 운영을 위해서는 8GB 이상 권장
  • 스토리지: 저장소 데이터와 백업 파일이 쌓이므로 여유 있는 볼륨 확보 (SSD/NVMe 권장)
  • 소프트웨어: Docker Engine 및 Docker Compose(v2 docker compose 기준) 설치 완료
  • 포트 계획: 컨테이너 내부는 기본적으로 HTTP 80, HTTPS 443, SSH 22 포트를 사용합니다. 호스트 서버의 기본 SSH가 이미 22번 포트를 점유하고 있다면 호스트 측 포트를 분리 매핑해야 합니다.

1.2 GitLab CE vs EE, 어떤 이미지를 써야 할까?

결론부터 말씀드리면 gitlab/gitlab-ee 이미지로 구축하셔도 전혀 상관없으며, 오히려 GitLab 공식 문서에서도 gitlab-ee 이미지 사용을 권장합니다. 유료 라이선스 키를 등록하지 않은 상태의 EE(Enterprise Edition)는 내부적으로 CE(Community Edition)와 100% 동일한 무료 기능으로 동작하기 때문입니다.

구분GitLab CE (gitlab/gitlab-ce)GitLab EE (gitlab/gitlab-ee)
라이선스 및 소스 구조순수 오픈소스 코드(MIT 라이선스)만 포함오픈소스 코드 + 상용 엔터프라이즈 기능 코드 포함
무료 사용 가능 여부100% 무료라이선스 미등록 시 무료 티어(CE와 동일 기능)로 작동
추후 유료 기능 확장유료 기능(Premium/Ultimate) 사용 시 이미지 전체를 EE로 마이그레이션해야 함라이선스 키만 입력하면 재설치 없이 즉시 유료 기능 활성화
보안 패치 및 릴리즈동일 시점 릴리즈동일 시점 릴리즈 (공식 문서 기본 권장 이미지)
이미지 용량 및 리소스EE 대비 근소하게 가벼움엔터프라이즈 코드가 포함되어 이미지 크기가 약간 더 큼 (런타임 메모리 차이는 미미)
  • gitlab/gitlab-ee 추천 환경: 향후 조직 규모가 커지거나, 평가판(Trial) 또는 유료 라이선스의 고급 기능(다중 승인자 규칙, 보안 스캔 등)을 활용할 가능성이 조금이라도 있는 경우 (본 가이드의 예시도 확장성을 고려해 gitlab-ee 기준으로 작성했습니다.)
  • gitlab/gitlab-ce 추천 환경: 엄격한 오픈소스 컴플라이언스 정책상 독점 코드가 포함된 바이너리를 배제해야 하거나, 개인 홈랩에서 순수 커뮤니티 버전만 유지하고 싶은 경우

2. 단계별 구축 가이드 (Step-by-Step)

Step 1. 영구 저장소(Persistent Volume) 디렉터리 생성

컨테이너를 재생성하거나 이미지를 업그레이드하더라도 Git 저장소, 설정 파일, 로그가 유실되지 않도록 호스트에 볼륨 디렉터리를 먼저 만듭니다.

Bash

mkdir -p ~/gitlab/config ~/gitlab/logs ~/gitlab/data
cd ~/gitlab
  • ./config (/etc/gitlab): gitlab.rb, gitlab-secrets.json, SSL 인증서 및 초기 root 비밀번호 파일 위치
  • ./logs (/var/log/gitlab): Nginx, Rails, Sidekiq, PostgreSQL 등 각종 컴포넌트 로그 위치
  • ./data (/var/opt/gitlab): 실제 Git 리포지토리, 데이터베이스, 업로드 파일, 백업 데이터 위치

Step 2. docker-compose.yml 작성

작업 디렉터리(~/gitlab)에 docker-compose.yml 파일을 생성합니다. 아래 예시는 공식 권장 이미지(gitlab/gitlab-ee:latest)를 기준으로, 호스트 SSH 포트 충돌을 피하기 위해 외부 2222 포트를 컨테이너 22번 포트에 연결한 구성입니다.

YAML

services:
  gitlab:
    image: gitlab/gitlab-ee:latest   # 순수 오픈소스만 원할 경우 gitlab/gitlab-ce:latest 로 변경 가능
    container_name: gitlab
    restart: unless-stopped
    hostname: 'gitlab.yourdomain.com'
    ports:
      - '443:443'   
      - '2222:22'     # Git SSH 접속 포트 (호스트 22번 포트 충돌 방지)
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.yourdomain.com:8080'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    shm_size: '256m'

리버스 프록시 / 터널 연동 시 체크포인트 외부 도메인에 HTTPS를 적용하고 앞단에 리버스 프록시(Nginx, Synology Reverse Proxy)나 Cloudflare Tunnel을 두는 구조라면, 프록시/터널이 HTTPS를 종단하는지 또는 백엔드로 어떤 프로토콜/포트를 넘기는지에 맞춰 external_url과 ports 설정을 환경에 맞게 조정해야 합니다. 또한 SSH로 git clone이나 git push를 사용할 때는 포트가 2222로 분리되어 있으므로 ssh://[email protected]:2222/group/repo.git 형태로 접속하거나 SSH config에 포트를 지정해야 합니다.

Step 3. 컨테이너 실행 및 초기 부팅 로그 확인

작성한 docker-compose.yml로 GitLab 컨테이너를 백그라운드에서 실행합니다.

Bash

docker compose up -d

최초 실행 시에는 내부 설정 반영(gitlab-ctl reconfigure)과 초기 DB 구성이 진행되므로 보통 3분에서 10분 이상(서버 사양에 따라 더 길어질 수 있음) 소요됩니다. 아래 명령으로 초기화 진행 상황을 실시간으로 확인하세요.

Bash

docker logs -f gitlab

로그가 멈추지 않고 길게 흐르다가 서비스들이 정상 기동되면 브라우저 접속 준비가 끝난 것입니다. (로그 확인을 종료할 때는 Ctrl + C를 누릅니다.)

Step 4. 초기 root 비밀번호 확인 및 보안 설정

초기화가 완료되면 설정한 주소로 접속합니다. 기본 관리자 계정명은 root이며, 초기 비밀번호는 ./config/initial_root_password (컨테이너 내 /etc/gitlab/initial_root_password)에 자동 생성됩니다.

Bash

docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password

로그인 후에는 반드시 아래 두 가지를 먼저 처리하는 것이 좋습니다.

  1. root 계정 비밀번호 즉시 변경: 우측 상단 프로필 메뉴 → Edit profile → Password에서 강력한 비밀번호로 변경합니다. (초기 비밀번호 파일은 24시간 뒤 reconfigure 실행 시 자동 삭제되므로 바로 변경해 두는 것이 안전합니다.)
  2. 외부 회원가입 비활성화: 외부망이나 공유 네트워크에 노출된 환경이라면 Admin Area(관리자 영역) → Settings → General → Sign-up restrictions에서 Allow new user accounts 체크를 해제해 무단 계정 생성을 막습니다.

3. 실전 트러블슈팅 및 운영 노하우

1. 접속 시 502 에러가 발생하는 경우

  • 초기화 미완료: docker compose up -d 직후에는 아직 내부 서비스(Puma, Workhorse 등)가 다 올라오기 전이라 502 화면이 뜰 수 있습니다. docker compose logs -f gitlab으로 기동이 끝날 때까지 기다려 보세요.
  • 메모리 부족(OOM): RAM이 부족하면 일부 데몬이 제대로 기동되지 않거나 커널에 의해 종료되면서 502가 발생합니다. free -h로 가용 메모리와 스왑 상태를 확인하고, 불필요한 컨테이너를 정리하거나 메모리/스왑을 확보해야 합니다.

2. 포트 22 충돌 및 SSH 접속 이슈

  • 호스트 OS가 이미 SSH(22번 포트)를 사용 중이라면 0.0.0.0:22->22/tcp: bind: address already in use 오류가 발생합니다.
  • 이때는 ports에서 '2222:22'로 매핑하고 GITLAB_OMNIBUS_CONFIG의 gitlab_rails['gitlab_shell_ssh_port'] = 2222 값을 일치시켜야 웹 UI의 Clone 안내 URL과 실제 접속 포트가 어긋나지 않습니다.

3. 백업과 업그레이드 원칙

  • 핵심 파일 및 데이터 백업: ./config/gitlab-secrets.json, ./config/gitlab.rb, 그리고 백업 데이터(./data/backups/)는 반드시 별도 저장소나 외부 백업 위치에 주기적으로 복사해 두어야 합니다. 특히 gitlab-secrets.json이 유실되면 데이터베이스 내 암호화된 값(CI/CD 변수, 2FA 토큰, 통합 설정 등)을 복호화할 수 없게 됩니다.
  • 안전한 버전 업그레이드: 운영 중인 환경에서 latest 태그로 무작정 한 번에 여러 메이저/마이너 버전을 건너뛰면 DB 마이그레이션 오류가 생길 수 있습니다. 업그레이드 전 백업을 먼저 수행한 뒤, GitLab 공식 업그레이드 경로(Upgrade Path)를 확인하며 단계적으로 버전 태그를 지정해 올리는 것이 안전합니다.

4. 마치며

Docker Compose를 활용하면 별도의 복잡한 호스트 패키지 설치 없이도 GitLab 환경을 깔끔하게 격리하고 관리할 수 있습니다. 기본 저장소와 계정 세팅을 마쳤다면, 다음 단계로 GitLab Runner를 연동해 CI/CD 자동화 파이프라인을 구성하거나 주기적인 백업 자동화 및 외부 접속 보안 강화를 붙여 나만의 개발 인프라를 완성해 보시기 바랍니다.

코멘트

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다