GitLab 서버를 직접 구축하기 위해 구글링을 시작하면 대부분 Ubuntu 기준의 Omnibus 패키지 설명만 가득합니다. 저 또한 그 문서를 믿고 FreeBSD에서 pkg install을 시도했다가, 리눅스와는 사뭇 다른 서비스 구조와 복잡하게 얽힌 Ruby 의존성 문제 앞에서 당혹스러웠던 기억이 있습니다. FreeBSD에서의 GitLab은 단순히 패키지 하나를 올리는 작업이 아니라, PostgreSQL과 Redis를 비롯한 여러 컴포넌트를 조율하는 ‘오케스트레이션’에 가깝습니다. 이 글에서는 제가 수많은 빌드 에러와 서비스 중단을 겪으며 정립한, FreeBSD 환경에서의 GitLab CE 셀프 호스팅 최적화 가이드를 공유합니다.
1. 설치 전에 반드시 확인할 서버 조건
GitLab은 Jenkins보다도 자원 사용량이 큰 편이라, 테스트 서버처럼 가볍게 시작했다가 로그인 화면조차 느려지는 경우가 자주 있습니다. 특히 메모리 부족은 설치 직후보다 사용자와 프로젝트가 늘어날 때 더 크게 드러납니다.
최소 기준으로는 4GB 메모리보다 여유 있게 보는 편이 좋고, 실제 운영이라면 8GB 이상을 권장하는 경우가 많습니다. 여기에 스왑 영역도 함께 고려해야 합니다.
먼저 확인할 항목
freebsd-version
pkg update
pkg upgrade
메모리 / 디스크 / 스왑 상태 점검
특히 디스크는 저장소 용량만 보는 것이 아니라 백업 전략까지 함께 봐야 합니다. Git 저장소, CI 아티팩트, 로그 파일이 계속 쌓이기 때문입니다.
대부분은 CPU보다 디스크 정리 시점을 더 늦게 알아차립니다. 설치 직후엔 괜찮아 보여도 운영 몇 달 뒤 여기서 차이가 납니다.
놓치기 쉬운 포인트는 “설치 가능 여부”와 “장기 운영 가능 여부”가 완전히 다르다는 점입니다.
2. PostgreSQL, Redis, Ruby 등 필수 구성 준비
조회까진 했는데 여기서 가장 많이 멈추는 부분은 의존성 설치 순서입니다. GitLab은 단일 서비스처럼 보이지만 실제로는 PostgreSQL, Redis, Ruby, Git, 웹 서버가 함께 움직여야 합니다.
우선 필수 패키지를 준비합니다.
기본 패키지 예시
pkg install postgresql15-server
pkg install redis
pkg install ruby
pkg install git nginx
설치 후에는 PostgreSQL과 Redis를 먼저 활성화합니다. GitLab보다 데이터베이스와 캐시 서비스가 먼저 안정적으로 떠 있어야 이후 설정이 덜 꼬입니다.
서비스 등록
sysrc postgresql_enable=YES
sysrc redis_enable=YES
처음 보면 GitLab 설치가 핵심처럼 느껴지지만, 실제로는 PostgreSQL 초기 설정에서 더 자주 막힙니다. 사용자 생성이나 권한 설정이 어긋나면 나중에 오류 메시지가 훨씬 복잡하게 나타납니다.
겉으로는 GitLab 문제처럼 보여도 원인은 대부분 DB 연결 실패인 경우가 많습니다.
헷갈리기 쉬운 부분은 패키지 설치보다 서비스 간 연결 순서입니다.
3. GitLab CE 설치와 기본 설정
FreeBSD에서는 Linux용 Omnibus GitLab 패키지를 그대로 사용할 수 없기 때문에, ports 기반 설치나 개별 구성 방식이 필요합니다. 이 부분을 모르고 공식 Linux 설치 문서를 그대로 따라가다 중단되는 경우가 많습니다.
설치 방식은 운영 정책에 따라 다르지만, 중요한 것은 경로와 권한을 명확히 정리하는 것입니다. Git 저장소 위치, 로그 디렉터리, 업로드 경로를 나중에 옮기려면 작업이 커집니다.
관리자 계정 생성과 초기 접근 정책도 이 단계에서 함께 정리해야 합니다. 특히 외부 가입 허용 여부를 기본값 그대로 두는 실수가 생각보다 자주 발생합니다.
초기 설정 시 확인 권장 항목
관리자 계정 / 회원가입 정책 / 저장소 경로 / 백업 경로 / 로그 보관 정책
대부분 조건보다 처음 어떤 기본값을 그대로 두었는지가 나중에 더 큰 운영 부담이 됩니다.
여기서 갈리는 핵심은 설치 완료가 아니라 “처음부터 관리 가능한 구조로 시작했는가”입니다.
4. Nginx 리버스 프록시와 HTTPS 적용
서비스는 실행되는데 접속이 불안정하거나 HTTPS가 제대로 적용되지 않는 경우가 많습니다. 대부분은 리버스 프록시 설정과 포트 흐름을 명확히 정리하지 않은 상황입니다.
GitLab은 내부 서비스 포트와 외부 공개 포트를 분리해서 운영하는 경우가 많습니다. 이때 Nginx를 앞단에 두고 SSL 종료를 처리하면 관리가 훨씬 편해집니다.
특히 사내 환경에서는 인증서 갱신 정책까지 함께 봐야 합니다. 설치만 성공하고 인증서 만료를 놓치는 경우가 실제로 더 위험합니다.
함께 확인할 항목
listen 포트 / reverse proxy / SSL 인증서 / 방화벽 / 외부 접근 정책
브라우저 접속이 된다고 바로 끝난 것이 아닙니다. Git clone, Webhook, Runner 등록까지 정상 동작해야 실제 운영 기준에 가까워집니다.
대부분 웹 접속 확인까지만 하고 Git over HTTPS 단계에서 다시 막히게 됩니다.
놓치기 쉬운 포인트는 “로그인 성공”이 아니라 개발 흐름 전체가 이어지는지 확인하는 것입니다.
5. 운영 단계에서 자주 발생하는 문제
GitLab은 설치보다 유지가 훨씬 어렵습니다. 느려졌다는 느낌이 들기 시작하면 이미 로그, 백업, 디스크 사용량에서 신호가 먼저 나오는 경우가 많습니다.
특히 Runner 연결 문제, Sidekiq 지연, PostgreSQL 성능 저하, Redis 메모리 사용량은 자주 확인해야 합니다. 사용자가 늘수록 작은 설정 차이가 크게 체감됩니다.
백업도 단순 압축이 아니라 “복구 가능한지”를 기준으로 봐야 합니다. 백업 파일이 있다는 것과 실제 복원이 되는 것은 다른 이야기입니다.
운영 시 필수 점검 항목
DB 백업 / 로그 회전 / 디스크 사용량 / SSL 갱신 / Runner 상태 / 관리자 계정 분리
실제로는 장애보다 복구 준비 부족이 더 오래 서버를 멈추게 만듭니다.
헷갈리기 쉬운 부분은 “현재 정상 동작”과 “장애 발생 시 복구 가능”이 같지 않다는 점입니다.
6. 자주 묻는 질문
Q1. FreeBSD에서 Omnibus GitLab을 그대로 설치할 수 있나요?
일반적으로 Linux용 Omnibus 패키지를 그대로 사용하는 방식은 적합하지 않습니다. FreeBSD에서는 ports 기반 접근이나 개별 서비스 구성 방식이 현실적입니다.
Q2. PostgreSQL 버전은 최신으로 맞추는 게 좋은가요?
무조건 최신보다 GitLab 지원 범위와 호환성을 먼저 확인하는 편이 안전합니다. 지원 범위를 벗어나면 예상보다 복구가 어려워질 수 있습니다.
Q3. Redis 없이도 운영 가능한가요?
실무 운영 기준에서는 사실상 함께 사용하는 구조를 전제로 보는 편이 좋습니다. 성능과 세션 처리 안정성에서 차이가 큽니다.
Q4. HTTPS는 나중에 붙여도 되나요?
가능은 하지만 초기에 구조를 함께 잡는 편이 훨씬 편합니다. 특히 Webhook과 Runner 연동 단계에서 다시 수정해야 할 일이 줄어듭니다.
Q5. 백업은 어느 경로만 복사하면 끝인가요?
저장소만이 아니라 DB, 업로드 파일, 설정 파일까지 함께 봐야 합니다. 복원 테스트를 해보지 않으면 실제 장애 때 예상과 다를 수 있습니다.
마무리
FreeBSD에서 GitLab을 운영한다는 것은 단순히 Git 저장소를 만드는 것이 아니라, 하나의 거대한 개발 플랫폼을 관리하는 일입니다. 설치가 끝났다고 안심하기보다, 실제 데이터가 쌓였을 때 PostgreSQL의 퍼포먼스는 어떠한지, Redis의 메모리 점유율은 안정적인지를 지속적으로 모니터링해야 합니다. 특히 나중에 관리하기 쉬운 구조를 선택하는 것이 가장 중요하다는 제 조언은, 수차례의 버전 업그레이드와 백업 복구 테스트를 거치며 얻은 값진 교훈이기도 합니다. GitLab은 한 번 설치하고 잊어버리는 도구가 아니라, 관리자의 손길에 따라 그 견고함이 결정되는 운영 시스템임을 잊지 마세요. 오늘 구축한 이 안정적인 환경이 여러분 팀의 개발 생산성을 지탱하는 든든한 뿌리가 되길 바랍니다.
※ GitLab 버전, FreeBSD ports 상태, PostgreSQL 및 Redis 지원 범위는 시점에 따라 달라질 수 있습니다. 실제 운영 적용 전에는 공식 문서와 현재 패키지 환경을 함께 확인하시기 바랍니다.