Ubuntu 16.04에 GitLab CE 설치 방법

무엇을 할 것인가

필요한 패키지 설치
GitLab(omnibus) 설치
GitLab 접근용 URL 구성
Let’s Encrypt SSL 및 DHParam 생성
Nginx HTTPS 활성화
UFW 방화벽 구성
GitLab 후속 설정(초기 비밀번호 재설정, 사용자/SSH 키 설정)
동작 확인(프로젝트 생성, 첫 커밋 푸시)

중요: 이 가이드는 Ubuntu 16.04 x86_64(64비트)를 기준으로 작성되었습니다. 서버에 루트 권한이 필요합니다. 최소 메모리 2GB 권장입니다.

설치 전 요구사항

Ubuntu 16.04 Server - 64비트
최소 RAM 2GB
루트 권한 또는 sudo 사용 가능 계정

1단계 - Ubuntu 필수 패키지 설치

먼저 서버에 루트로 로그인한 뒤 패키지 목록을 갱신합니다.

ssh root@GitLabServer  
apt-get update

그 다음 GitLab 설치에 필요한 curl, openssh-server, ca-certificates, postfix 등을 설치합니다.

sudo apt install curl openssh-server ca-certificates postfix

postfix 설치 중 구성 옵션이 나오면 ‘Internet Site’를 선택합니다. 이후 메일 발신에 사용할 호스트명(도메인)을 입력합니다.

Postfix 구성 화면에서 인터넷 사이트 선택 및 호스트명 입력을 보여주는 스크린샷입니다.

Postfix 호스트명 입력 화면 예시입니다.

중요: SMTP(메일) 설정은 GitLab의 알림 및 비밀번호 복구에 필요합니다. 내부 전용 설치라면 별도 메일 게이트웨이를 사용해도 됩니다.

2단계 - GitLab 설치(omnibus 패키지 사용)

Omnibus 패키지는 GitLab 실행에 필요한 모든 컴포넌트를 한 번에 설치합니다. GitLab 저장소를 등록합니다.

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

GitLab 저장소를 추가하는 예시 출력 화면입니다.

그 다음 GitLab CE를 설치합니다.

sudo apt install gitlab-ce

설치가 진행되는 동안 여러 패키지와 서비스를 자동으로 설치·구성합니다. 설치 완료 후 완료 메시지가 표시됩니다.

GitLab 설치 진행과 완료 예시 화면입니다.

3단계 - GitLab 기본 URL 설정

웹에서 접근할 도메인(URL)을 설정합니다. 예제에서는 gitlab.hakase-labs.co를 사용하지만 실제 환경에서는 본인의 도메인을 사용하세요. 처음에는 HTTP로 설정해도 됩니다(이후 HTTPS로 변경).

GitLab 설정 파일은 /etc/gitlab/gitlab.rb 입니다.

cd /etc/gitlab  
vim gitlab.rb

파일에서 9번째 줄쯤에 있는 external_url 값을 다음처럼 변경합니다.

external_url 'http://gitlab.hakase-labs.co'

파일을 저장하고 종료합니다. 이후 HTTPS 인증서를 준비한 뒤 external_url을 https로 변경합니다.

4단계 - Let’s Encrypt SSL 및 DHPARAM 생성

HTTPS를 활성화하기 위해 Let’s Encrypt 무료 인증서를 사용합니다. 먼저 certbot(또는 letsencrypt) 툴을 설치합니다.

sudo apt install letsencrypt -y

인증서 생성 명령:

letsencrypt certonly -d gitlab.hakase-labs.co

이메일 주소를 입력하고 Let’s Encrypt 약관에 동의합니다.

Let's Encrypt 인증서 생성 명령 실행 예시 화면입니다.

Let's Encrypt TOS 동의 화면입니다.

성공하면 /etc/letsencrypt/live/gitlab.hakase-labs.co/ 경로에 인증서 파일이 생성됩니다.

인증서 생성 완료 시 출력 예시입니다.

다음으로 GitLab에 사용할 DH 파라미터 파일을 생성합니다.

mkdir -p /etc/gitlab/ssl/
sudo openssl dhparam -out /etc/gitlab/ssl/dhparams.pem 2048

OpenSSL로 DH 파라미터 파일을 생성하는 과정 예시입니다.

생성된 인증서(및 개인 키)와 dhparams 파일의 권한을 600으로 설정합니다.

chmod 600 /etc/gitlab/ssl/*

중요: /etc/gitlab/ssl 디렉터리는 GitLab이 읽을 수 있어야 하며, 권한은 제한되어야 합니다.

5단계 - Nginx HTTPS 활성화 및 GitLab 설정 적용

이제 /etc/gitlab/gitlab.rb 파일로 돌아가 external_url을 https로 바꾸고 Nginx 관련 설정을 추가합니다.

cd /etc/gitlab/  
vim gitlab.rb

external_url 값을 다음과 같이 변경합니다.

external_url 'https://gitlab.hakase-labs.co'

그리고 아래 설정을 추가합니다.

nginx['redirect_http_to_https'] = true  
nginx['ssl_certificate'] = "/etc/letsencrypt/live/gitlab.hakase-labs.co/fullchain.pem"  
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/gitlab.hakase-labs.co/privkey.pem"  
nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem"

저장 후 재구성을 적용합니다.

sudo gitlab-ctl reconfigure

재구성 완료 메시지가 나오면 HTTPS 설정이 적용된 것입니다.

gitlab-ctl reconfigure 실행 결과 예시입니다.

중요: Let’s Encrypt 인증서는 90일마다 갱신해야 합니다. 자동 갱신 스크립트를 cron 또는 systemd 타이머로 설정하는 것을 권장합니다.

6단계 - UFW 방화벽 구성

GitLab을 외부에서 접속할 수 있도록 HTTP/HTTPS 포트를 허용합니다. 먼저 UFW를 활성화합니다.

ufw enable

SSH, HTTP, HTTPS 포트를 허용합니다.

ufw allow ssh  
ufw allow http  
ufw allow https

설정 상태를 확인합니다.

ufw status

UFW에서 HTTP/HTTPS 허용 예시 화면입니다.

UFW 규칙 상태 확인 예시 화면입니다.

중요: UFW를 활성화하기 전에 현재 SSH 연결이 유지되는지, 관리 접근 경로가 차단되지 않는지 확인하세요.

7단계 - GitLab 설치 후 초기 설정

웹 브라우저에서 https://gitlab.hakase-labs.co 에 접속하면 HTTPS로 리다이렉트되어 로그인 화면이 나타납니다. 기본 관리자 계정은 ‘root’이며, 초기 로그인 시 비밀번호 재설정 절차가 진행됩니다.

설치 후 기본 비밀번호 재설정 화면 예시입니다.

로그인 후 다음 기본 작업을 수행합니다.

프로필 설정(이름, 이메일 변경)

프로필 설정 화면 예시입니다.

사용자 이름 변경 및 업데이트

사용자 이름 변경 화면 예시입니다.

SSH 키 추가: 로컬에서 ssh-keygen으로 공개 키(id_rsa.pub)를 생성한 뒤 붙여넣기

ssh-keygen

SSH 키 생성 예시 화면입니다.

GitLab에 SSH 공개키를 추가하는 화면 예시입니다.

시스템 설정: Admin 영역에서 프로젝트 수 제한, 가입 제한(도메인 화이트리스트) 등 기본 정책 설정

시스템 설정 및 제한 구성 화면 예시입니다.

가입 제한과 프로젝트 제한 설정 예시 화면입니다.

8단계 - 동작 확인(테스트)

새 프로젝트 생성: 상단 플러스(+) 아이콘으로 프로젝트를 만들고, 공개성(visibility)과 이름을 설정합니다.

새 프로젝트 생성 화면 예시입니다.

로컬에서 Git 설정 및 첫 커밋 푸시

git config --global user.name "hakase"  
git config --global user.email "[email protected]"

git clone https://[email protected]/hakase/howtoforge.git  
cd howtoforge/  
vim README.md

git add .  
git commit -m 'Add README.md file by hakase-labs'  
git push origin master

푸시 시 사용자 인증을 요구하면 웹에서 설정한 계정 비밀번호를 사용합니다.

첫 푸시 결과 화면 예시입니다.

웹 UI에서 리포지토리에 README.md가 추가되었는지 확인합니다.

웹에서 새로 생성된 리포지토리와 파일이 보이는 예시입니다.

축하합니다 — GitLab CE가 Ubuntu 16.04 서버에 성공적으로 설치되었습니다.

운영·관리자 체크리스트

도메인 및 DNS A 레코드가 GitLab 서버를 가리키는지 확인
방화벽에서 22, 80, 443 포트 허용 여부 확인
/etc/gitlab/gitlab.rb의 external_url이 올바른지 확인
인증서 자동 갱신(cerbot renew) 스케줄링
정기 백업 설정(레포지토리, DB, 구성 파일)
로그 모니터링(gitlab-ctl tail)

역할별 빠른 체크리스트

관리자(Administrator): 시스템 설정, 백업/복원 전략, 사용자/그룹 관리, 인증(SSO) 설정
운영(DevOps): 모니터링, 업그레이드 계획, 리소스(메모리/디스크) 관리, 자동화 스크립트 작성
개발자(Developer): SSH 키 등록, 프로젝트 생성·권한 관리, CI/CD 파이프라인 구성

보안 하드닝 권장사항

HTTPS 강제화 및 HSTS 설정 적용
SSH 포트 기본 22 외에 추가 보안 정책(예: 인증서 기반 로그인 또는 포트 변경)은 신중히 적용
관리자 계정에 2단계 인증(2FA) 활성화
GitLab 업데이트를 주기적으로 적용하여 보안 패치를 반영
최소 권한 원칙(프로젝트·그룹 권한 제한) 적용
외부 접근에 대해 IP 화이트리스트 또는 VPN 적용 고려

문제 해결(트러블슈팅) 요약

GitLab 서비스 상태 확인:

sudo gitlab-ctl status

로그 확인(실시간):

sudo gitlab-ctl tail

재구성 필요 시:

sudo gitlab-ctl reconfigure

Nginx/포트 문제: UFW 상태 및 포트 리스닝 확인

ufw status
ss -tulpn | grep nginx

SSL 문제: /etc/letsencrypt/live/<도메인>/ 디렉터리와 권한 확인
인증서 갱신 실패: certbot renew –dry-run 로 테스트
메일 발송 실패: postfix 로그(/var/log/mail.log) 확인 및 SMTP 설정 점검

대체 설치 방법 및 비교

Omnibus 패키지(이 문서의 방법): 가장 빠르고 관리가 쉬움(추천, 소규모/중견 규모)
Docker 기반 설치: 컨테이너화 장점(격리, 배포 편의성). 공식 GitLab Docker 이미지를 사용해 복제 가능한 환경 구성 가능
소스에서 직접 설치(omnibus 미사용): 세부 커스터마이즈 가능하지만 복잡도 및 유지보수 비용이 높음
GitLab.com SaaS: 자체 인프라 운영 부담 없음(호스팅된 서비스 선호 시)
GitLab EE(Enterprise Edition): 엔터프라이즈 기능 필요 시 유료 업그레이드 고려

간단 비교(정성적): omnibus 예측 가능한 설치·업데이트 쉬움 | Docker 이식성 + 격리 | 소스 설치 유연성 높지만 관리 복잡

호환성 및 마이그레이션 팁

Ubuntu 16.04는 오래된 배포판입니다. 가능하면 Ubuntu 18.04/20.04 LTS로 업그레이드하는 것을 권장합니다. GitLab 패키지의 최신 버전은 최신 OS에서 더 잘 지원됩니다.
업그레이드 시 GitLab의 백업(백엔드 DB와 레포지토리)을 반드시 생성하고, 업그레이드/마이그레이션 절차를 단계별로 진행하세요.

작은 운영 방법론(검증 절차)

변경 전 전체 백업 생성
테스트 환경에서 변경 사항 적용
비업무 시간에 프로덕션 적용
적용 후 기본 동작(로그인, 레포지토리 접근, 푸시/풀) 점검

언제 이 방법이 적절하지 않은가(한계)

대규모(수천 사용자, 고가용성 필요) 환경에서는 단일 서버 Omnibus 설치는 한계가 있습니다. HA(High Availability) 구성이나 Geo replication 같은 고급 아키텍처가 필요합니다.
지속적 배포/인프라 코드화가 중요한 조직은 Docker/Kubernetes 기반 배포가 더 유리할 수 있습니다.

간단 용어집

Omnibus: GitLab이 동작하는 데 필요한 모든 컴포넌트를 하나로 묶어 설치하는 패키지
external_url: GitLab 웹 UI가 사용하는 기본 URL 설정
DHParam: TLS 연결의 암호화 강화를 위한 수학적 파라미터 파일
certbot/letsencrypt: 무료 SSL 인증서를 발급·갱신해 주는 도구

검증 항목(가동 확인)

https:/// 접속 시 SSL이 유효한지 확인
로그인한 뒤 프로젝트 생성 및 Git push가 정상 동작하는지 확인
ssh 접속(SSH 키 등록 후 git clone/ssh URL 사용)이 정상 동작하는지 확인
백업 및 복원 절차를 테스트

참고 링크

요약

이 가이드는 Ubuntu 16.04에 GitLab CE(Omnibus)를 설치하고 HTTPS, 방화벽, 초기 설정, 기본 테스트를 완료하는 방법을 설명합니다.
운영을 위해 인증서 자동 갱신, 정기 백업, 보안 하드닝(2FA, HSTS), 모니터링을 적용하세요.
대규모 또는 고가용성 환경은 다른 배포 모델(HA, Docker/Kubernetes, EE)을 고려하세요.

Ubuntu 16.04에 GitLab CE 설치 가이드