소스 코드 직접 컴파일 설치

요약

이 문서는 소스 파일을 사용해 프로덕션 GitLab 서버를 구축하는 공식 설치 가이드입니다. 이 가이드는 다양한 경우를 다루고 필요한 명령을 모두 담고 있어 분량이 깁니다. 이 가이드에서 버그나 오류를 발견하면 머지 리퀘스트를 제출합니다.

이 문서는 소스 파일을 사용해 프로덕션 GitLab 서버를 구축하는 공식 설치 가이드입니다. Debian/Ubuntu 운영 체제를 대상으로 작성했고 해당 환경에서 검증했습니다. 하드웨어 및 운영 체제 요구 사항은 requirements.md를 참고합니다. RHEL/CentOS에 설치하려면 Linux 패키지를 사용합니다. 그 밖의 여러 설치 방식은 기본 설치 페이지를 참고합니다.

이 가이드는 다양한 경우를 다루고 필요한 명령을 모두 담고 있어 분량이 깁니다. 아래 단계는 동작이 확인된 절차입니다. 이 가이드에서 벗어날 때는 주의합니다. GitLab 이 자신의 환경에 대해 전제하는 사항을 위반하지 않도록 합니다. 예를 들어 디렉터리 위치를 바꾸거나 서비스를 잘못된 사용자로 실행해 권한 문제를 겪는 경우가 많습니다.

이 가이드에서 버그나 오류를 발견하면 머지 리퀘스트를 제출합니다. 제출 방법은 다음 문서를 따릅니다. 기여 가이드.

Linux 패키지 설치 검토#

자체 컴파일 설치는 작업량이 많고 오류가 발생하기 쉬우므로, 빠르고 안정적인 Linux 패키지 설치(deb/rpm)를 권장합니다.

Linux 패키지가 더 안정적인 이유 중 하나는 GitLab 프로세스 중 하나가 중단되면 runit으로 다시 시작한다는 점입니다. 사용량이 많은 GitLab 인스턴스에서는 Sidekiq 백그라운드 워커의 메모리 사용량이 시간이 지나면서 늘어납니다. Linux 패키지는 메모리를 과도하게 사용하는 경우 Sidekiq를 정상적으로 종료하여 이 문제를 해결합니다. 종료 후에는 runit 이 Sidekiq가 실행 중이 아님을 감지하고 다시 시작합니다. 자체 컴파일 설치는 프로세스 감시에 runit을 사용하지 않으므로 Sidekiq를 종료할 수 없고 메모리 사용량이 시간이 지나면서 늘어납니다.

설치할 버전 선택#

설치하려는 GitLab 버전의 브랜치(예: 16-0-stable)에서 이 설치 가이드를 확인합니다. 브랜치는 GitLab 왼쪽 위(메뉴 바 아래)의 버전 드롭다운 목록에서 선택할 수 있습니다.

가장 높은 번호의 stable 브랜치가 무엇인지 분명하지 않으면 GitLab 블로그에서 버전별 설치 가이드 링크를 확인합니다.

소프트웨어 요구 사항#

소프트웨어	최소 버전	참고
Ruby	`3.2.x`	GitLab 16.7부터 17.4 까지는 Ruby 3.1 이 필요합니다. GitLab 17.5 이상에서는 Ruby 3.2가 필요합니다. Ruby는 표준 MRI 구현을 사용해야 합니다. JRuby와 Rubinius도 좋은 선택이지만, GitLab은 네이티브 확장을 사용하는 Gem을 여럿 필요로 합니다.
RubyGems	`3.5.x`	특정 RubyGems 버전이 반드시 필요하지는 않지만, 알려진 성능 개선을 적용하려면 업데이트하는 것이 좋습니다.
Go	`1.22.x`	GitLab 17.1 이상에서는 Go 1.22 이상이 필요합니다.
Git	`2.47.x`	GitLab 17.7 이상에서는 Git 2.47.x 이상이 필요합니다. Gitaly가 제공하는 Git 버전을 사용합니다.
Node.js	`20.13.x`	GitLab 17.0 이상에서는 Node.js 20.13 이상이 필요합니다.
PostgreSQL	`16.x`	GitLab 18.0 이상에서는 PostgreSQL 16 이상이 필요합니다.

GitLab 디렉터리 구조#

설치 단계를 진행하면서 다음 디렉터리가 생성됩니다.

|-- home
|   |-- git
|       |-- .ssh
|       |-- gitlab
|       |-- gitlab-shell
|       |-- repositories

/home/git/.ssh - OpenSSH 설정이 들어 있습니다. 구체적으로는 GitLab Shell 이 관리하는 authorized_keys 파일이 있습니다.
/home/git/gitlab - GitLab 핵심 소프트웨어입니다.
/home/git/gitlab-shell - GitLab의 핵심 애드온 구성 요소입니다. SSH 클론을 비롯한 기능을 담당합니다.
/home/git/repositories - 네임스페이스별로 정리된 모든 프로젝트의 베어 리포지터리입니다. 이 디렉터리에는 모든 프로젝트에서 푸시·풀하는 Git 리포지터리가 보관됩니다. 프로젝트의 중요한 데이터가 있는 영역입니다. 백업을 유지합니다.

리포지터리의 기본 위치는 GitLab의 config/gitlab.yml과 GitLab Shell의 config.yml에서 설정할 수 있습니다.

이 디렉터리를 지금 수동으로 만들 필요는 없으며, 그렇게 하면 설치 후반에 오류가 발생할 수 있습니다.

설치 워크플로#

GitLab 설치는 다음 구성 요소를 설정하는 과정으로 이루어집니다.

패키지 및 의존성.
Ruby.
RubyGems.
Go.
Node.
시스템 사용자.
데이터베이스.
Redis.
GitLab.
NGINX.

1. 패키지 및 의존성#

sudo#

sudo는 Debian에 기본으로 설치되어 있지 않습니다. 시스템을 최신 상태로 업데이트한 뒤 설치합니다.

# run as root!
apt-get update -y
apt-get upgrade -y
apt-get install sudo -y

빌드 의존성#

필요한 패키지를 설치합니다(Ruby와 Ruby gem의 네이티브 확장을 컴파일하는 데 필요합니다).

sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev \
  libreadline-dev libncurses5-dev libffi-dev curl openssh-server libxml2-dev libxslt-dev \
  libcurl4-openssl-dev libicu-dev libkrb5-dev logrotate rsync python3-docutils pkg-config cmake \
  runit-systemd

Note

GitLab은 OpenSSL 1.1 버전이 필요합니다. 사용하는 Linux 배포판에 다른 버전의 OpenSSL 이 포함되어 있으면 1.1을 직접 설치해야 할 수 있습니다.

Git#

다음과 같은 Gitaly가 제공하는 Git 버전을 사용합니다.

항상 GitLab 이 요구하는 버전입니다.
정상 동작에 필요한 커스텀 패치가 포함될 수 있습니다.

필요한 의존성을 설치합니다.

sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential git-core

Gitaly 리포지터리를 클론하고 Git을 컴파일합니다. <X-Y-stable>은 설치하려는 GitLab 버전에 해당하는 stable 브랜치로 바꿉니다. 예를 들어 GitLab 19.2를 설치하려면 브랜치 이름 19-2-stable을 사용합니다.
```
git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly
cd /tmp/gitaly
sudo make git GIT_PREFIX=/usr/local
```
필요하다면 시스템 Git과 그 의존성을 제거할 수 있습니다.
```
sudo apt remove -y git-core
sudo apt autoremove
```

나중에 config/gitlab.yml을 편집할 때 Git 경로를 변경해야 합니다.

변경 전:
```
git:
  bin_path: /usr/bin/git
```
변경 후:
```
git:
  bin_path: /usr/local/bin/git
```

GraphicsMagick#

커스텀 파비콘이 동작하려면 GraphicsMagick을 설치해야 합니다.

sudo apt-get install -y graphicsmagick

메일 서버#

메일 알림을 받으려면 메일 서버를 설치합니다. Debian에는 기본적으로 exim4가 포함되어 있지만 이 메일 서버에는 문제가 있고, Ubuntu에는 메일 서버가 포함되어 있지 않습니다. 권장하는 메일 서버는 postfix 이며 다음 명령으로 설치할 수 있습니다.

sudo apt-get install -y postfix

그런 다음 Internet Site를 선택하고 Enter를 눌러 호스트명을 확인합니다.

ExifTool#

GitLab Workhorse 는 업로드된 이미지에서 EXIF 데이터를 제거하기 위해 exiftool 이 필요합니다.

sudo apt-get install -y libimage-exiftool-perl

2. Ruby#

GitLab을 실행하려면 Ruby 인터프리터가 필요합니다. 최소 Ruby 요구 사항은 요구 사항 절을 참고합니다.

RVM, rbenv, chruby 같은 Ruby 버전 관리자는 GitLab에서 원인을 파악하기 어려운 문제를 일으킬 수 있습니다. 대신 공식 소스 코드에서 Ruby를 설치합니다.

3. RubyGems#

Ruby에 번들로 포함된 것보다 최신 버전의 RubyGems가 필요한 경우가 있습니다.

특정 버전으로 업데이트하려면 다음과 같이 실행합니다.

gem update --system 3.4.12

최신 버전으로 업데이트하려면 다음과 같이 실행합니다.

gem update --system

4. Go#

GitLab에는 Go로 작성된 데몬이 여럿 있습니다. GitLab을 설치하려면 Go 컴파일러를 설치해야 합니다. 다음 안내는 64비트 Linux를 사용한다고 가정합니다. 다른 플랫폼용 다운로드는 Go 다운로드 페이지에서 확인할 수 있습니다.

# Remove former Go installation folder
sudo rm -rf /usr/local/go

curl --remote-name --location --progress-bar "https://go.dev/dl/go1.22.5.linux-amd64.tar.gz"
echo '904b924d435eaea086515bc63235b192ea441bd8c9b198c507e85009e6e4c7f0  go1.22.5.linux-amd64.tar.gz' | shasum -a256 -c - && \
  sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
rm go1.22.5.linux-amd64.tar.gz

5. Node#

GitLab은 JavaScript 자산을 컴파일하는 데 Node를, JavaScript 의존성을 관리하는 데 Yarn을 사용합니다. 현재 최소 요구 사항은 다음과 같습니다.

node 20.x 릴리스(v20.13.0 이상). 그 밖의 Node.js LTS 버전으로도 자산을 빌드할 수 있지만, 동작을 보장하는 것은 Node.js 20.x 뿐입니다.
yarn = v1.22.x(Yarn 2는 아직 지원하지 않습니다)

여러 배포판에서 공식 패키지 리포지터리가 제공하는 버전은 오래되었으므로, 다음 명령으로 설치해야 합니다.

# install node v20.x
curl --location "https://deb.nodesource.com/setup_20.x" | sudo bash -
sudo apt-get install -y nodejs

npm install --global yarn

이 단계에서 문제가 생기면 node와 yarn 공식 사이트를 참고합니다.

6. 시스템 사용자#

GitLab 용 git 사용자를 생성합니다.

sudo adduser --disabled-login --gecos 'GitLab' git

7. 데이터베이스#

Note

PostgreSQL만 지원합니다. GitLab 18.0 이상에서는 PostgreSQL 16 이상이 필요합니다.

데이터베이스 패키지를 설치합니다.

Ubuntu 22.04 이상인 경우:

sudo apt install -y postgresql postgresql-client libpq-dev postgresql-contrib

Ubuntu 20.04 이하에서는 사용 가능한 PostgreSQL 이 최소 버전 요구 사항을 충족하지 않습니다. PostgreSQL 리포지터리를 추가해야 합니다.

sudo curl --fail --silent --show-error --output /etc/apt/keyrings/postgresql.asc \
          --url "https://www.postgresql.org/media/keys/ACCC4CF8.asc"
echo "deb [ signed-by=/etc/apt/keyrings/postgresql.asc ] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" |
     sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get -y install postgresql-16

설치하려는 GitLab 버전이 현재 사용하는 PostgreSQL 버전을 지원하는지 확인합니다.
```
psql --version
```
PostgreSQL 서비스를 시작하고 서비스가 실행 중인지 확인합니다.
```
sudo service postgresql start
sudo service postgresql status
```

GitLab 용 데이터베이스 사용자를 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"

pg_trgm 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

btree_gist 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"

plpgsql 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS plpgsql;"

GitLab 프로덕션 데이터베이스를 생성하고 해당 데이터베이스의 모든 권한을 부여합니다.
```
sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
```
새 사용자로 새 데이터베이스에 접속해 봅니다.
```
sudo -u git -H psql -d gitlabhq_production
```

pg_trgm 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'pg_trgm'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

btree_gist 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'btree_gist'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

plpgsql 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'plpgsql'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

데이터베이스 세션을 종료합니다.
```
gitlabhq_production> \q
```

8. Redis#

최소 Redis 요구 사항은 요구 사항 페이지를 참고합니다.

다음 명령으로 Redis를 설치합니다.

sudo apt-get install redis-server

설치가 끝나면 Redis를 설정합니다.

# Configure redis to use sockets
sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig

# Disable Redis listening on TCP by setting 'port' to 0
sudo sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf

# Enable Redis socket for default Debian / Ubuntu path
echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf

# Grant permission to the socket to all members of the redis group
echo 'unixsocketperm 770' | sudo tee -a /etc/redis/redis.conf

# Add git to the redis group
sudo usermod -aG redis git

systemd로 Redis 감시#

배포판이 systemd init을 사용하고 다음 명령의 출력이 notify 이면 아무것도 변경하지 않아야 합니다.

systemctl show --value --property=Type redis-server.service

출력이 notify가 아니면 다음을 실행합니다.

# Configure Redis to not daemonize, but be supervised by systemd instead and disable the pidfile
sudo sed -i \
         -e 's/^daemonize yes$/daemonize no/' \
         -e 's/^supervised no$/supervised systemd/' \
         -e 's/^pidfile/# pidfile/' /etc/redis/redis.conf
sudo chown redis:redis /etc/redis/redis.conf

# Make the same changes to the systemd unit file
sudo mkdir -p /etc/systemd/system/redis-server.service.d
sudo tee /etc/systemd/system/redis-server.service.d/10fix_type.conf <
# Reload the redis service
sudo systemctl daemon-reload

# Activate the changes to redis.conf
sudo systemctl restart redis-server.service

Redis를 감독 없이 두기#

시스템이 SysV init를 사용한다면 다음 명령을 실행합니다.

# Create the directory which contains the socket
sudo mkdir -p /var/run/redis
sudo chown redis:redis /var/run/redis
sudo chmod 755 /var/run/redis

# Persist the directory which contains the socket, if applicable
if [ -d /etc/tmpfiles.d ]; then
  echo 'd  /var/run/redis  0755  redis  redis  10d  -' | sudo tee -a /etc/tmpfiles.d/redis.conf
fi

# Activate the changes to redis.conf
sudo service redis-server restart

9. GitLab#

# We'll install GitLab into the home directory of the user "git"
cd /home/git

소스 클론#

Community Edition을 클론합니다.

# Clone GitLab repository
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-foss.git -b <X-Y-stable> gitlab

Enterprise Edition을 클론합니다.

# Clone GitLab repository
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b <X-Y-stable-ee> gitlab

<X-Y-stable>은 설치하려는 버전에 해당하는 stable 브랜치로 반드시 바꿉니다. 예를 들어 11.8을 설치하려면 브랜치 이름으로 11-8-stable을 사용합니다.

Warning

"최신 개발" 버전을 원한다면 <X-Y-stable>을 master로 바꿀 수 있지만, 운영 서버에는 절대 master를 설치하지 않습니다.

설정하기#

# Go to GitLab installation folder
cd /home/git/gitlab

# Copy the example GitLab config
sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml

# Update GitLab config file, follow the directions at top of the file
sudo -u git -H editor config/gitlab.yml

# Copy the example secrets file
sudo -u git -H cp config/secrets.yml.example config/secrets.yml
sudo -u git -H chmod 0600 config/secrets.yml

# Make sure GitLab can write to the log/ and tmp/ directories
sudo chown -R git log/
sudo chown -R git tmp/
sudo chmod -R u+rwX,go-w log/
sudo chmod -R u+rwX tmp/

# Make sure GitLab can write to the tmp/pids/ and tmp/sockets/ directories
sudo chmod -R u+rwX tmp/pids/
sudo chmod -R u+rwX tmp/sockets/

# Create the public/uploads/ directory
sudo -u git -H mkdir -p public/uploads/

# Make sure only the GitLab user has access to the public/uploads/ directory
# now that files in public/uploads are served by gitlab-workhorse
sudo chmod 0700 public/uploads

# Change the permissions of the directory where CI job logs are stored
sudo chmod -R u+rwX builds/

# Change the permissions of the directory where CI artifacts are stored
sudo chmod -R u+rwX shared/artifacts/

# Change the permissions of the directory where GitLab Pages are stored
sudo chmod -R ug+rwX shared/pages/

# Copy the example Puma config
sudo -u git -H cp config/puma.rb.example config/puma.rb

# Refer to https://github.com/puma/puma#configuration for more information.
# You should scale Puma workers and threads based on the number of CPU
# cores you have available. You can get that number via the `nproc` command.
sudo -u git -H editor config/puma.rb

# Configure Redis connection settings
sudo -u git -H cp config/resque.yml.example config/resque.yml
sudo -u git -H cp config/cable.yml.example config/cable.yml

# Change the Redis socket path if you are not using the default Debian / Ubuntu configuration
sudo -u git -H editor config/resque.yml config/cable.yml

gitlab.yml과 puma.rb를 모두 사용 환경에 맞게 수정합니다.

HTTPS를 사용하려면 추가 단계를 HTTPS 사용에서 참고합니다.

GitLab 데이터베이스(DB) 설정 구성#

Note

main: 섹션만 있는 database.yml은 더 이상 사용되지 않습니다. database.yml에는 main:과 ci: 섹션이 모두 있어야 합니다.

sudo -u git cp config/database.yml.postgresql config/database.yml

# Remove host, username, and password lines from config/database.yml.
# Once modified, the `production` settings will be as follows:
#
#   production:
#     main:
#       adapter: postgresql
#       encoding: unicode
#       database: gitlabhq_production
#     ci:
#       adapter: postgresql
#       encoding: unicode
#       database: gitlabhq_production
#       database_tasks: false
#
sudo -u git -H editor config/database.yml

# Remote PostgreSQL only:
# Update username/password in config/database.yml.
# You only need to adapt the production settings (first part).
# If you followed the database guide then please do as follows:
# Change 'secure password' with the value you have given to $password
# You can keep the double quotes around the password
sudo -u git -H editor config/database.yml

# Uncomment the `ci:` sections in config/database.yml.
# Ensure the `database` value in `ci:` matches the database value in `main:`.

# Make config/database.yml readable to git only
sudo -u git -H chmod o-rwx config/database.yml

database.yml에는 main:과 ci: 두 섹션이 있어야 합니다. ci: 연결은 같은 데이터베이스를 가리켜야 합니다.

Gem 설치#

Note

Bundler 1.5.2 부터는 bundle install -jN(N은 프로세서 코어 수)을 실행해 gem을 병렬로 설치할 수 있고, 완료 시간이 눈에 띄게 줄어듭니다(약 60% 단축). 코어 수는 nproc으로 확인합니다. 자세한 내용은 이 글을 참고합니다.

bundle 이 설치되어 있는지 확인합니다(bundle -v 실행).

>= 1.5.2. 일부 이슈가 1.5.2에서 수정되었기 때문입니다.
< 2.x.

gem을 설치합니다(사용자 인증에 Kerberos를 사용하려면 다음 명령의 --without 옵션에서 kerberos를 제외합니다).

sudo -u git -H bundle config set --local deployment 'true'
sudo -u git -H bundle config set --local without 'development test kerberos'
sudo -u git -H bundle config path /home/git/gitlab/vendor/bundle
sudo -u git -H bundle install

GitLab Shell 설치#

GitLab Shell은 GitLab 전용으로 개발된 SSH 액세스 및 리포지터리 관리 소프트웨어입니다.

# Run the installation task for gitlab-shell:
sudo -u git -H bundle exec rake gitlab:shell:install RAILS_ENV=production

# By default, the gitlab-shell config is generated from your main GitLab config.
# You can review (and modify) the gitlab-shell config as follows:
sudo -u git -H editor /home/git/gitlab-shell/config.yml

HTTPS를 사용하려면 추가 단계를 HTTPS 사용에서 참고합니다.

호스트 이름이 해당 머신 자체에서 확인되도록 적절한 DNS 레코드를 두거나 /etc/hosts에 줄("127.0.0.1 hostname")을 추가합니다. 예를 들어 GitLab을 리버스 프록시 뒤에 두는 경우 이 작업이 필요할 수 있습니다. 호스트 이름이 확인되지 않으면 최종 설치 점검이 Check GitLab API access: FAILED. code: 401로 실패하고, 커밋 푸시는 [remote rejected] master -> master (hook declined)로 거부됩니다.

GitLab Workhorse 설치#

GitLab-Workhorse는 GNU Make를 사용합니다. 다음 명령은 권장 위치인 /home/git/gitlab-workhorse에 GitLab-Workhorse를 설치합니다.

sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production

Enterprise Edition에 GitLab-Elasticsearch-indexer 설치#

GitLab-Elasticsearch-Indexer는 GNU Make를 사용합니다. 다음 명령은 권장 위치인 /home/git/gitlab-elasticsearch-indexer에 GitLab-Elasticsearch-Indexer를 설치합니다.

sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elasticsearch-indexer]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elasticsearch-indexer,https://example.com/gitlab-elasticsearch-indexer.git]" RAILS_ENV=production

먼저 첫 번째 매개변수로 지정한 경로에 소스 코드를 가져오고, 그 아래 bin 디렉터리에 바이너리를 빌드합니다. 그다음 gitlab.yml의 production -> elasticsearch -> indexer_path 설정이 그 바이너리를 가리키도록 수정합니다.

GitLab Pages 설치#

GitLab Pages는 GNU Make를 사용합니다. 이 단계는 선택 사항이며, GitLab에서 정적 사이트를 호스팅하려는 경우에만 필요합니다. 다음 명령은 /home/git/gitlab-pages에 GitLab Pages를 설치합니다. GitLab Pages 데몬은 여러 방식으로 실행할 수 있으므로, 추가 설정 단계는 사용 중인 GitLab 버전의 관리 가이드를 참고합니다.

cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

Gitaly 설치#

# Create and restrict access to the git repository data directory
sudo install -d -o git -m 0700 /home/git/repositories

# Fetch Gitaly source with Git and compile with Go
cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories,https://example.com/gitaly.git]" RAILS_ENV=production

다음으로 Gitaly가 설정되었는지 확인합니다.

# Restrict Gitaly socket access
sudo chmod 0700 /home/git/gitlab/tmp/sockets/private
sudo chown git /home/git/gitlab/tmp/sockets/private

# If you are using non-default settings, you need to update config.toml
cd /home/git/gitaly
sudo -u git -H editor config.toml

Gitaly 설정에 대한 자세한 내용은 Gitaly 문서를 참고합니다.

서비스 설치#

GitLab은 이식성이 높고 널리 지원되는 SysV init 스크립트를 계속 지원해 왔지만, 지금은 systemd가 서비스 관리의 표준이며 모든 주요 Linux 배포판에서 사용됩니다. 가능하다면 네이티브 systemd 서비스를 사용해 자동 재시작, 더 나은 샌드박싱, 리소스 제어를 활용합니다.

systemd 유닛 설치#

init로 systemd를 사용하는 경우 다음 단계를 따릅니다. 그 외에는 SysV init 스크립트 단계를 따릅니다.

서비스 파일을 복사하고 systemd가 인식하도록 systemctl daemon-reload를 실행합니다.

cd /home/git/gitlab
sudo mkdir -p /usr/local/lib/systemd/system
sudo cp lib/support/systemd/* /usr/local/lib/systemd/system/
sudo systemctl daemon-reload

GitLab 이 제공하는 유닛은 Redis와 PostgreSQL의 실행 위치에 대해 거의 가정하지 않습니다.

GitLab을 다른 디렉터리에 설치했거나 기본 사용자가 아닌 사용자로 설치했다면, 유닛의 해당 값도 함께 변경해야 합니다.

예를 들어 Redis와 PostgreSQL을 GitLab과 같은 머신에서 실행한다면 다음과 같이 합니다.

Puma 서비스를 편집합니다.

sudo systemctl edit gitlab-puma.service

열린 편집기에서 다음 내용을 추가하고 파일을 저장합니다.

[Unit]
Wants=redis-server.service postgresql.service
After=redis-server.service postgresql.service

Sidekiq 서비스를 편집합니다.

sudo systemctl edit gitlab-sidekiq.service

다음 내용을 추가하고 파일을 저장합니다.

[Unit]
Wants=redis-server.service postgresql.service
After=redis-server.service postgresql.service

systemctl edit는 드롭인 설정 파일을 /etc/systemd/system/<name of the unit>.d/override.conf에 설치하므로, 이후 유닛 파일을 업데이트해도 로컬 설정이 덮어써지지 않습니다. 드롭인 설정 파일을 나누려면 앞의 스니펫을 /etc/systemd/system/<name of the unit>.d/ 아래의 .conf 파일에 추가합니다.

systemctl edit를 쓰지 않고 유닛 파일을 직접 수정했거나 드롭인 설정 파일을 추가했다면, 변경 사항을 적용하기 위해 다음 명령을 실행합니다.

sudo systemctl daemon-reload

부팅 시 GitLab 이 시작되도록 설정합니다.

sudo systemctl enable gitlab.target

SysV init 스크립트 설치#

SysV init 스크립트를 사용하는 경우 다음 단계를 따릅니다. systemd를 사용한다면 systemd 유닛 단계를 따릅니다.

init 스크립트(/etc/init.d/gitlab)를 내려받습니다.

cd /home/git/gitlab
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab

기본이 아닌 폴더나 사용자로 설치하는 경우에는 defaults 파일을 복사해 편집합니다.

sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab

GitLab을 다른 디렉터리에 설치했거나 기본 사용자가 아닌 사용자로 설치했다면 /etc/default/gitlab에서 해당 설정을 변경합니다. /etc/init.d/gitlab은 업그레이드 시 변경되므로 수정하지 않습니다.

부팅 시 GitLab 이 시작되도록 설정합니다.

sudo update-rc.d gitlab defaults 21
# or if running this on a machine running systemd
sudo systemctl daemon-reload
sudo systemctl enable gitlab.service

Logrotate 설정#

sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab

Gitaly 시작#

다음 섹션을 진행하려면 Gitaly가 실행 중이어야 합니다.

systemd로 Gitaly를 시작합니다.

sudo systemctl start gitlab-gitaly.service

SysV에서 Gitaly를 수동으로 시작합니다.

gitlab_path=/home/git/gitlab
gitaly_path=/home/git/gitaly

sudo -u git -H sh -c "$gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \
  $gitaly_path/_build/bin/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 &"

데이터베이스 초기화 및 고급 기능 활성화#

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
# Type 'yes' to create the database tables.

# or you can skip the question by adding force=yes
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes

# When done, you see 'Administrator account created:'

다음 명령과 같이 환경 변수 GITLAB_ROOT_PASSWORD와 GITLAB_ROOT_EMAIL로 관리자(root) 비밀번호와 이메일을 지정할 수 있습니다. 비밀번호를 지정하지 않아 기본값이 설정된 경우에는 설치가 끝나고 서버에 처음 로그인할 때까지 GitLab을 공개 인터넷에 노출하지 않습니다. 첫 로그인 시 기본 비밀번호를 반드시 변경하게 됩니다. GITLAB_ACTIVATION_CODE 환경 변수에 활성화 코드를 지정하면 이때 Enterprise Edition 구독을 활성화할 수도 있습니다.

sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail GITLAB_ACTIVATION_CODE=yourcode

`secrets.yml` 보호#

secrets.yml 파일에는 세션과 보안 변수의 암호화 키가 저장됩니다. secrets.yml은 안전한 곳에 백업하되, 데이터베이스 백업과 같은 위치에는 두지 않습니다. 그렇지 않으면 백업 중 하나가 유출될 때 시크릿도 함께 노출됩니다.

애플리케이션 상태 확인#

GitLab과 그 환경이 올바르게 구성되었는지 확인합니다.

sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production

애셋 컴파일#

sudo -u git -H yarn install --production --pure-lockfile
sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production

rake가 JavaScript heap out of memory 오류로 실패하면 다음과 같이 NODE_OPTIONS를 지정해 실행합니다.

sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096"

GitLab 인스턴스 시작#

# For systems running systemd
sudo systemctl start gitlab.target

# For systems running SysV init
sudo service gitlab start

10. NGINX#

NGINX는 GitLab 이 공식적으로 지원하는 웹 서버입니다. NGINX를 웹 서버로 사용할 수 없거나 사용하지 않으려면 GitLab recipes를 참고합니다.

설치#

sudo apt-get install -y nginx

사이트 구성#

예제 사이트 설정 파일을 복사합니다.

sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab

설정 파일을 사용 환경에 맞게 수정합니다. 특히 git 이외의 사용자로 설치하는 경우에는 GitLab 경로가 일치하는지 확인합니다.

# Change YOUR_SERVER_FQDN to the fully-qualified
# domain name of your host serving GitLab.
#
# Remember to match your paths to GitLab, especially
# if installing for a user other than 'git'.
#
# If using Ubuntu default nginx install:
# either remove the default_server from the listen line
# or else sudo rm -f /etc/nginx/sites-enabled/default
sudo editor /etc/nginx/sites-available/gitlab

GitLab Pages를 활성화하려면 별도의 NGINX 설정을 사용해야 합니다. 필요한 설정은 GitLab Pages 관리 가이드에서 모두 확인합니다.

HTTPS를 사용하려면 gitlab NGINX 설정을 gitlab-ssl로 교체합니다. HTTPS 설정에 대한 자세한 내용은 HTTPS 사용을 참고합니다.

NGINX가 GitLab-Workhorse 소켓을 읽으려면 GitLab 사용자 소유인 이 소켓을 www-data 사용자가 읽을 수 있어야 합니다. 소켓이 전체 읽기 가능하면, 예를 들어 기본값인 0755 권한이면 이 조건이 충족됩니다. 또한 www-data는 상위 디렉터리를 나열할 수 있어야 합니다.

테스트 구성#

gitlab 또는 gitlab-ssl NGINX 구성 파일을 다음 명령으로 검증합니다:

sudo nginx -t

syntax is okay와 test is successful 메시지가 출력되어야 합니다. 오류 메시지가 출력되면 표시된 오류 메시지를 참고하여 gitlab 또는 gitlab-ssl NGINX 구성 파일에 오타가 없는지 확인합니다.

설치된 버전이 1.12.1보다 높은지 확인합니다:

nginx -v

버전이 더 낮으면 다음 오류가 발생할 수 있습니다:

nginx: [emerg] unknown "start$temp=[filtered]$rest" variable
nginx: configuration file /etc/nginx/nginx.conf test failed

재시작#

# For systems running systemd
sudo systemctl restart nginx.service

# For systems running SysV init
sudo service nginx restart

설치 후 작업#

애플리케이션 상태 재확인#

빠뜨린 항목이 없는지 다음 명령으로 더 철저히 점검합니다:

sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production

모든 항목이 녹색이면 GitLab 설치에 성공한 것입니다.

Note

gitlab:check에 SANITIZE=true 환경 변수를 지정하면 점검 명령 출력에서 프로젝트 이름을 제외합니다.

최초 로그인#

첫 GitLab 로그인을 위해 웹 브라우저에서 YOUR_SERVER에 접속합니다.

설정 중에 root 비밀번호를 지정하지 않았다면 초기 관리자 계정의 비밀번호를 입력하는 비밀번호 재설정 화면으로 이동합니다. 원하는 비밀번호를 입력하면 다시 로그인 화면으로 이동합니다.

기본 계정의 사용자 이름은 root 입니다. 앞서 만든 비밀번호를 입력하여 로그인합니다. 로그인 후에는 원한다면 사용자 이름을 변경할 수 있습니다.

GitLab을 시작하고 중지하는 방법은 다음과 같습니다:

systemd 유닛: sudo systemctl start gitlab.target 또는 sudo systemctl stop gitlab.target을 사용합니다.
SysV init 스크립트: sudo service gitlab start 또는 sudo service gitlab stop을 사용합니다.

권장 다음 단계#

설치를 마친 후에는 인증 옵션과 신규 사용자 계정 제한을 포함한 권장 다음 단계를 검토하는 것이 좋습니다.

고급 설정 팁#

상대 URL 지원#

상대 URL로 GitLab을 구성하는 방법은 상대 URL 문서를 참고합니다.

HTTPS 사용#

HTTPS로 GitLab을 사용하려면 다음과 같이 합니다:

gitlab.yml에서 다음을 수행합니다:
1. 섹션 1의 port 옵션을 443으로 설정합니다.
2. 섹션 1의 https 옵션을 true로 설정합니다.
GitLab Shell의 config.yml에서 다음을 수행합니다:
1. gitlab_url 옵션을 GitLab의 HTTPS 엔드포인트(예: https://git.example.com)로 설정합니다.
2. ca_file 또는 ca_path 옵션으로 인증서를 설정합니다.
gitlab 구성 대신 gitlab-ssl NGINX 예제 구성을 사용합니다.
1. YOUR_SERVER_FQDN을 업데이트합니다.
2. ssl_certificate와 ssl_certificate_key를 업데이트합니다.
3. 구성 파일을 검토하고 다른 보안 및 성능 향상 기능의 적용을 검토합니다.

자체 서명 인증서 사용은 권장하지 않습니다. 반드시 사용해야 한다면 표준 절차에 따라 자체 서명 SSL 인증서를 생성합니다:

mkdir -p /etc/nginx/ssl/
cd /etc/nginx/ssl/
sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key
sudo chmod o-r gitlab.key

이메일 회신 활성화#

설정 방법은 "이메일 회신" 문서를 참고합니다.

LDAP 인증#

config/gitlab.yml에서 LDAP 인증을 구성할 수 있습니다. 이 파일을 편집한 후에는 GitLab을 재시작합니다.

커스텀 OmniAuth 공급자 사용#

OmniAuth 통합 문서를 참고합니다.

프로젝트 빌드#

GitLab은 프로젝트를 빌드할 수 있습니다. 이 기능을 사용하려면 빌드를 수행할 러너가 필요합니다. 설치 방법은 GitLab Runner 섹션을 참고합니다.

신뢰할 수 있는 프록시 추가#

별도 머신에서 리버스 프록시를 사용한다면 해당 프록시를 신뢰할 수 있는 프록시 목록에 추가하는 것이 좋습니다. 그렇지 않으면 사용자가 프록시의 IP 주소에서 로그인한 것으로 표시됩니다.

섹션 1의 trusted_proxies 옵션을 수정하여 config/gitlab.yml에 신뢰할 수 있는 프록시를 추가할 수 있습니다. 파일을 저장하고 GitLab을 재구성하면 변경 사항이 적용됩니다.

URL에 잘못 인코딩된 문자 때문에 문제가 발생하면 오류: 리버스 프록시 사용 시 404 Not Found를 참고합니다.

커스텀 Redis 연결#

표준이 아닌 포트나 다른 호스트의 Redis 서버에 연결하려면 config/resque.yml 파일에서 연결 문자열을 구성할 수 있습니다.

# example
production:
  url: redis://redis.example.tld:6379

소켓으로 Redis 서버에 연결하려면 config/resque.yml 파일에서 unix: URL 스킴과 Redis 소켓 파일 경로를 사용합니다.

# example
production:
  url: unix:/path/to/redis/socket

또한 config/resque.yml 파일에서 환경 변수를 사용할 수 있습니다:

# example
production:
  url: <%= ENV.fetch('GITLAB_REDIS_URL') %>

커스텀 SSH 연결#

표준이 아닌 포트에서 SSH를 실행한다면 GitLab 사용자의 SSH 구성을 변경해야 합니다.

# Add to /home/git/.ssh/config
host localhost          # Give your setup a name (here: override localhost)
    user git            # Your remote git user
    port 2222           # Your port number
    hostname 127.0.0.1; # Your server name or IP

config/gitlab.yml 파일에서 대응하는 옵션(예: ssh_user, ssh_host, admin_uri)도 변경해야 합니다.

추가 마크업 스타일#

항상 지원되는 Markdown 스타일 외에도 GitLab 이 표시할 수 있는 리치 텍스트 파일이 있습니다. 다만 이를 위해 의존성을 설치해야 할 수 있습니다. 자세한 내용은 github-markup gem README를 참고합니다.

Prometheus 서버 설정#

config/gitlab.yml에서 Prometheus 서버를 구성할 수 있습니다:

# example
prometheus:
  enabled: true
  server_address: '10.1.2.3:9090'

문제 해결#

메시지: `You appear to have cloned an empty repository.`#

GitLab 이 호스팅하는 리포지터리를 클론할 때 이 메시지가 표시된다면 오래된 NGINX 또는 Apache 구성이거나, GitLab Workhorse 인스턴스가 없거나 잘못 구성되었을 가능성이 높습니다. Go 설치, GitLab Workhorse 설치, NGINX 구성을 올바르게 마쳤는지 다시 확인합니다.

`google-protobuf` 오류: `LoadError: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.14' not found`#

일부 플랫폼에서 특정 버전의 google-protobuf gem을 사용할 때 발생할 수 있습니다. 해결 방법은 이 gem의 소스 전용 버전을 설치하는 것입니다.

먼저 설치된 GitLab 이 요구하는 google-protobuf의 정확한 버전을 확인해야 합니다:

cd /home/git/gitlab

# Only one of the following two commands will print something. It
# will look like: * google-protobuf (3.2.0)
bundle list | grep google-protobuf
bundle check | grep google-protobuf

다음 명령에서 3.2.0은 예시입니다. 앞서 확인한 버전 번호로 바꿉니다:

cd /home/git/gitlab
sudo -u git -H gem install google-protobuf --version 3.2.0 --platform ruby

마지막으로 google-protobuf 이 올바르게 로드되는지 테스트할 수 있습니다. 다음 명령은 OK를 출력해야 합니다.

sudo -u git -H bundle exec ruby -rgoogle/protobuf -e 'puts :OK'

gem install 명령이 실패하면 운영체제의 개발자 도구를 설치해야 할 수 있습니다.

Debian/Ubuntu에서는 다음과 같습니다:

sudo apt-get install build-essential libgmp-dev

RedHat/CentOS에서는 다음과 같습니다:

sudo yum groupinstall 'Development Tools'

GitLab 에셋 컴파일 오류#

에셋을 컴파일할 때 다음 오류 메시지가 표시될 수 있습니다:

Killed
error Command failed with exit code 137.

Yarn 이 메모리가 부족한 컨테이너를 종료할 때 발생할 수 있습니다. 해결 방법은 다음과 같습니다:

시스템 메모리를 최소 8GB로 늘립니다.

다음 명령으로 에셋을 정리합니다:

sudo -u git -H bundle exec rake gitlab:assets:clean RAILS_ENV=production NODE_ENV=production

yarn 명령을 다시 실행하여 충돌을 해결합니다:
```
sudo -u git -H yarn install --production --pure-lockfile
```

에셋을 다시 컴파일합니다:

sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production

소스 코드 직접 컴파일 설치

GitLab v19.4

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-09-18

요약

이 가이드에서 버그나 오류를 발견하면 머지 리퀘스트를 제출합니다. 제출 방법은 다음 문서를 따릅니다. 기여 가이드.

Linux 패키지 설치 검토#

자체 컴파일 설치는 작업량이 많고 오류가 발생하기 쉬우므로, 빠르고 안정적인 Linux 패키지 설치(deb/rpm)를 권장합니다.

설치할 버전 선택#

가장 높은 번호의 stable 브랜치가 무엇인지 분명하지 않으면 GitLab 블로그에서 버전별 설치 가이드 링크를 확인합니다.

소프트웨어 요구 사항#

소프트웨어	최소 버전	참고
Ruby	`3.2.x`	GitLab 16.7부터 17.4 까지는 Ruby 3.1 이 필요합니다. GitLab 17.5 이상에서는 Ruby 3.2가 필요합니다. Ruby는 표준 MRI 구현을 사용해야 합니다. JRuby와 Rubinius도 좋은 선택이지만, GitLab은 네이티브 확장을 사용하는 Gem을 여럿 필요로 합니다.
RubyGems	`3.5.x`	특정 RubyGems 버전이 반드시 필요하지는 않지만, 알려진 성능 개선을 적용하려면 업데이트하는 것이 좋습니다.
Go	`1.22.x`	GitLab 17.1 이상에서는 Go 1.22 이상이 필요합니다.
Git	`2.47.x`	GitLab 17.7 이상에서는 Git 2.47.x 이상이 필요합니다. Gitaly가 제공하는 Git 버전을 사용합니다.
Node.js	`20.13.x`	GitLab 17.0 이상에서는 Node.js 20.13 이상이 필요합니다.
PostgreSQL	`16.x`	GitLab 18.0 이상에서는 PostgreSQL 16 이상이 필요합니다.

GitLab 디렉터리 구조#

설치 단계를 진행하면서 다음 디렉터리가 생성됩니다.

|-- home
|   |-- git
|       |-- .ssh
|       |-- gitlab
|       |-- gitlab-shell
|       |-- repositories

/home/git/.ssh - OpenSSH 설정이 들어 있습니다. 구체적으로는 GitLab Shell 이 관리하는 authorized_keys 파일이 있습니다.
/home/git/gitlab - GitLab 핵심 소프트웨어입니다.
/home/git/gitlab-shell - GitLab의 핵심 애드온 구성 요소입니다. SSH 클론을 비롯한 기능을 담당합니다.
/home/git/repositories - 네임스페이스별로 정리된 모든 프로젝트의 베어 리포지터리입니다. 이 디렉터리에는 모든 프로젝트에서 푸시·풀하는 Git 리포지터리가 보관됩니다. 프로젝트의 중요한 데이터가 있는 영역입니다. 백업을 유지합니다.

리포지터리의 기본 위치는 GitLab의 config/gitlab.yml과 GitLab Shell의 config.yml에서 설정할 수 있습니다.

이 디렉터리를 지금 수동으로 만들 필요는 없으며, 그렇게 하면 설치 후반에 오류가 발생할 수 있습니다.

설치 워크플로#

GitLab 설치는 다음 구성 요소를 설정하는 과정으로 이루어집니다.

패키지 및 의존성.
Ruby.
RubyGems.
Go.
Node.
시스템 사용자.
데이터베이스.
Redis.
GitLab.
NGINX.

1. 패키지 및 의존성#

sudo#

sudo는 Debian에 기본으로 설치되어 있지 않습니다. 시스템을 최신 상태로 업데이트한 뒤 설치합니다.

# run as root!
apt-get update -y
apt-get upgrade -y
apt-get install sudo -y

빌드 의존성#

필요한 패키지를 설치합니다(Ruby와 Ruby gem의 네이티브 확장을 컴파일하는 데 필요합니다).

sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev \
  libreadline-dev libncurses5-dev libffi-dev curl openssh-server libxml2-dev libxslt-dev \
  libcurl4-openssl-dev libicu-dev libkrb5-dev logrotate rsync python3-docutils pkg-config cmake \
  runit-systemd

Note

GitLab은 OpenSSL 1.1 버전이 필요합니다. 사용하는 Linux 배포판에 다른 버전의 OpenSSL 이 포함되어 있으면 1.1을 직접 설치해야 할 수 있습니다.

Git#

다음과 같은 Gitaly가 제공하는 Git 버전을 사용합니다.

항상 GitLab 이 요구하는 버전입니다.
정상 동작에 필요한 커스텀 패치가 포함될 수 있습니다.

필요한 의존성을 설치합니다.

sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential git-core

Gitaly 리포지터리를 클론하고 Git을 컴파일합니다. <X-Y-stable>은 설치하려는 GitLab 버전에 해당하는 stable 브랜치로 바꿉니다. 예를 들어 GitLab 19.2를 설치하려면 브랜치 이름 19-2-stable을 사용합니다.
```
git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly
cd /tmp/gitaly
sudo make git GIT_PREFIX=/usr/local
```
필요하다면 시스템 Git과 그 의존성을 제거할 수 있습니다.
```
sudo apt remove -y git-core
sudo apt autoremove
```

나중에 config/gitlab.yml을 편집할 때 Git 경로를 변경해야 합니다.

변경 전:
```
git:
  bin_path: /usr/bin/git
```
변경 후:
```
git:
  bin_path: /usr/local/bin/git
```

GraphicsMagick#

커스텀 파비콘이 동작하려면 GraphicsMagick을 설치해야 합니다.

sudo apt-get install -y graphicsmagick

메일 서버#

sudo apt-get install -y postfix

그런 다음 Internet Site를 선택하고 Enter를 눌러 호스트명을 확인합니다.

ExifTool#

GitLab Workhorse 는 업로드된 이미지에서 EXIF 데이터를 제거하기 위해 exiftool 이 필요합니다.

sudo apt-get install -y libimage-exiftool-perl

2. Ruby#

GitLab을 실행하려면 Ruby 인터프리터가 필요합니다. 최소 Ruby 요구 사항은 요구 사항 절을 참고합니다.

RVM, rbenv, chruby 같은 Ruby 버전 관리자는 GitLab에서 원인을 파악하기 어려운 문제를 일으킬 수 있습니다. 대신 공식 소스 코드에서 Ruby를 설치합니다.

3. RubyGems#

Ruby에 번들로 포함된 것보다 최신 버전의 RubyGems가 필요한 경우가 있습니다.

특정 버전으로 업데이트하려면 다음과 같이 실행합니다.

gem update --system 3.4.12

최신 버전으로 업데이트하려면 다음과 같이 실행합니다.

gem update --system

4. Go#

# Remove former Go installation folder
sudo rm -rf /usr/local/go

curl --remote-name --location --progress-bar "https://go.dev/dl/go1.22.5.linux-amd64.tar.gz"
echo '904b924d435eaea086515bc63235b192ea441bd8c9b198c507e85009e6e4c7f0  go1.22.5.linux-amd64.tar.gz' | shasum -a256 -c - && \
  sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/
rm go1.22.5.linux-amd64.tar.gz

5. Node#

GitLab은 JavaScript 자산을 컴파일하는 데 Node를, JavaScript 의존성을 관리하는 데 Yarn을 사용합니다. 현재 최소 요구 사항은 다음과 같습니다.

node 20.x 릴리스(v20.13.0 이상). 그 밖의 Node.js LTS 버전으로도 자산을 빌드할 수 있지만, 동작을 보장하는 것은 Node.js 20.x 뿐입니다.
yarn = v1.22.x(Yarn 2는 아직 지원하지 않습니다)

여러 배포판에서 공식 패키지 리포지터리가 제공하는 버전은 오래되었으므로, 다음 명령으로 설치해야 합니다.

# install node v20.x
curl --location "https://deb.nodesource.com/setup_20.x" | sudo bash -
sudo apt-get install -y nodejs

npm install --global yarn

이 단계에서 문제가 생기면 node와 yarn 공식 사이트를 참고합니다.

6. 시스템 사용자#

GitLab 용 git 사용자를 생성합니다.

sudo adduser --disabled-login --gecos 'GitLab' git

7. 데이터베이스#

Note

PostgreSQL만 지원합니다. GitLab 18.0 이상에서는 PostgreSQL 16 이상이 필요합니다.

데이터베이스 패키지를 설치합니다.

Ubuntu 22.04 이상인 경우:

sudo apt install -y postgresql postgresql-client libpq-dev postgresql-contrib

Ubuntu 20.04 이하에서는 사용 가능한 PostgreSQL 이 최소 버전 요구 사항을 충족하지 않습니다. PostgreSQL 리포지터리를 추가해야 합니다.

sudo curl --fail --silent --show-error --output /etc/apt/keyrings/postgresql.asc \
          --url "https://www.postgresql.org/media/keys/ACCC4CF8.asc"
echo "deb [ signed-by=/etc/apt/keyrings/postgresql.asc ] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" |
     sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get -y install postgresql-16

설치하려는 GitLab 버전이 현재 사용하는 PostgreSQL 버전을 지원하는지 확인합니다.
```
psql --version
```
PostgreSQL 서비스를 시작하고 서비스가 실행 중인지 확인합니다.
```
sudo service postgresql start
sudo service postgresql status
```

GitLab 용 데이터베이스 사용자를 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;"

pg_trgm 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"

btree_gist 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS btree_gist;"

plpgsql 확장을 생성합니다.

sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS plpgsql;"

GitLab 프로덕션 데이터베이스를 생성하고 해당 데이터베이스의 모든 권한을 부여합니다.
```
sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;"
```
새 사용자로 새 데이터베이스에 접속해 봅니다.
```
sudo -u git -H psql -d gitlabhq_production
```

pg_trgm 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'pg_trgm'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

btree_gist 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'btree_gist'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

plpgsql 확장이 활성화되었는지 확인합니다.

SELECT true AS enabled
FROM pg_available_extensions
WHERE name = 'plpgsql'
AND installed_version IS NOT NULL;

확장이 활성화되어 있으면 다음과 같이 출력됩니다.

enabled
---------
 t
(1 row)

데이터베이스 세션을 종료합니다.
```
gitlabhq_production> \q
```

8. Redis#

최소 Redis 요구 사항은 요구 사항 페이지를 참고합니다.

다음 명령으로 Redis를 설치합니다.

sudo apt-get install redis-server

설치가 끝나면 Redis를 설정합니다.

# Configure redis to use sockets
sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig

# Disable Redis listening on TCP by setting 'port' to 0
sudo sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf

# Enable Redis socket for default Debian / Ubuntu path
echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf

# Grant permission to the socket to all members of the redis group
echo 'unixsocketperm 770' | sudo tee -a /etc/redis/redis.conf

# Add git to the redis group
sudo usermod -aG redis git

systemd로 Redis 감시#

배포판이 systemd init을 사용하고 다음 명령의 출력이 notify 이면 아무것도 변경하지 않아야 합니다.

systemctl show --value --property=Type redis-server.service

출력이 notify가 아니면 다음을 실행합니다.

# Configure Redis to not daemonize, but be supervised by systemd instead and disable the pidfile
sudo sed -i \
         -e 's/^daemonize yes$/daemonize no/' \
         -e 's/^supervised no$/supervised systemd/' \
         -e 's/^pidfile/# pidfile/' /etc/redis/redis.conf
sudo chown redis:redis /etc/redis/redis.conf

# Make the same changes to the systemd unit file
sudo mkdir -p /etc/systemd/system/redis-server.service.d
sudo tee /etc/systemd/system/redis-server.service.d/10fix_type.conf <
# Reload the redis service
sudo systemctl daemon-reload

# Activate the changes to redis.conf
sudo systemctl restart redis-server.service

Redis를 감독 없이 두기#

시스템이 SysV init를 사용한다면 다음 명령을 실행합니다.

# Create the directory which contains the socket
sudo mkdir -p /var/run/redis
sudo chown redis:redis /var/run/redis
sudo chmod 755 /var/run/redis

# Persist the directory which contains the socket, if applicable
if [ -d /etc/tmpfiles.d ]; then
  echo 'd  /var/run/redis  0755  redis  redis  10d  -' | sudo tee -a /etc/tmpfiles.d/redis.conf
fi

# Activate the changes to redis.conf
sudo service redis-server restart

9. GitLab#

# We'll install GitLab into the home directory of the user "git"
cd /home/git

소스 클론#

Community Edition을 클론합니다.

# Clone GitLab repository
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-foss.git -b <X-Y-stable> gitlab

Enterprise Edition을 클론합니다.

# Clone GitLab repository
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b <X-Y-stable-ee> gitlab

<X-Y-stable>은 설치하려는 버전에 해당하는 stable 브랜치로 반드시 바꿉니다. 예를 들어 11.8을 설치하려면 브랜치 이름으로 11-8-stable을 사용합니다.

Warning

"최신 개발" 버전을 원한다면 <X-Y-stable>을 master로 바꿀 수 있지만, 운영 서버에는 절대 master를 설치하지 않습니다.

설정하기#

# Go to GitLab installation folder
cd /home/git/gitlab

# Copy the example GitLab config
sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml

# Update GitLab config file, follow the directions at top of the file
sudo -u git -H editor config/gitlab.yml

# Copy the example secrets file
sudo -u git -H cp config/secrets.yml.example config/secrets.yml
sudo -u git -H chmod 0600 config/secrets.yml

# Make sure GitLab can write to the log/ and tmp/ directories
sudo chown -R git log/
sudo chown -R git tmp/
sudo chmod -R u+rwX,go-w log/
sudo chmod -R u+rwX tmp/

# Make sure GitLab can write to the tmp/pids/ and tmp/sockets/ directories
sudo chmod -R u+rwX tmp/pids/
sudo chmod -R u+rwX tmp/sockets/

# Create the public/uploads/ directory
sudo -u git -H mkdir -p public/uploads/

# Make sure only the GitLab user has access to the public/uploads/ directory
# now that files in public/uploads are served by gitlab-workhorse
sudo chmod 0700 public/uploads

# Change the permissions of the directory where CI job logs are stored
sudo chmod -R u+rwX builds/

# Change the permissions of the directory where CI artifacts are stored
sudo chmod -R u+rwX shared/artifacts/

# Change the permissions of the directory where GitLab Pages are stored
sudo chmod -R ug+rwX shared/pages/

# Copy the example Puma config
sudo -u git -H cp config/puma.rb.example config/puma.rb

# Refer to https://github.com/puma/puma#configuration for more information.
# You should scale Puma workers and threads based on the number of CPU
# cores you have available. You can get that number via the `nproc` command.
sudo -u git -H editor config/puma.rb

# Configure Redis connection settings
sudo -u git -H cp config/resque.yml.example config/resque.yml
sudo -u git -H cp config/cable.yml.example config/cable.yml

# Change the Redis socket path if you are not using the default Debian / Ubuntu configuration
sudo -u git -H editor config/resque.yml config/cable.yml

gitlab.yml과 puma.rb를 모두 사용 환경에 맞게 수정합니다.

HTTPS를 사용하려면 추가 단계를 HTTPS 사용에서 참고합니다.

GitLab 데이터베이스(DB) 설정 구성#

Note

main: 섹션만 있는 database.yml은 더 이상 사용되지 않습니다. database.yml에는 main:과 ci: 섹션이 모두 있어야 합니다.

sudo -u git cp config/database.yml.postgresql config/database.yml

# Remove host, username, and password lines from config/database.yml.
# Once modified, the `production` settings will be as follows:
#
#   production:
#     main:
#       adapter: postgresql
#       encoding: unicode
#       database: gitlabhq_production
#     ci:
#       adapter: postgresql
#       encoding: unicode
#       database: gitlabhq_production
#       database_tasks: false
#
sudo -u git -H editor config/database.yml

# Remote PostgreSQL only:
# Update username/password in config/database.yml.
# You only need to adapt the production settings (first part).
# If you followed the database guide then please do as follows:
# Change 'secure password' with the value you have given to $password
# You can keep the double quotes around the password
sudo -u git -H editor config/database.yml

# Uncomment the `ci:` sections in config/database.yml.
# Ensure the `database` value in `ci:` matches the database value in `main:`.

# Make config/database.yml readable to git only
sudo -u git -H chmod o-rwx config/database.yml

database.yml에는 main:과 ci: 두 섹션이 있어야 합니다. ci: 연결은 같은 데이터베이스를 가리켜야 합니다.

Gem 설치#

Note

bundle 이 설치되어 있는지 확인합니다(bundle -v 실행).

>= 1.5.2. 일부 이슈가 1.5.2에서 수정되었기 때문입니다.
< 2.x.

gem을 설치합니다(사용자 인증에 Kerberos를 사용하려면 다음 명령의 --without 옵션에서 kerberos를 제외합니다).

sudo -u git -H bundle config set --local deployment 'true'
sudo -u git -H bundle config set --local without 'development test kerberos'
sudo -u git -H bundle config path /home/git/gitlab/vendor/bundle
sudo -u git -H bundle install

GitLab Shell 설치#

GitLab Shell은 GitLab 전용으로 개발된 SSH 액세스 및 리포지터리 관리 소프트웨어입니다.

# Run the installation task for gitlab-shell:
sudo -u git -H bundle exec rake gitlab:shell:install RAILS_ENV=production

# By default, the gitlab-shell config is generated from your main GitLab config.
# You can review (and modify) the gitlab-shell config as follows:
sudo -u git -H editor /home/git/gitlab-shell/config.yml

HTTPS를 사용하려면 추가 단계를 HTTPS 사용에서 참고합니다.

GitLab Workhorse 설치#

GitLab-Workhorse는 GNU Make를 사용합니다. 다음 명령은 권장 위치인 /home/git/gitlab-workhorse에 GitLab-Workhorse를 설치합니다.

sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production

Enterprise Edition에 GitLab-Elasticsearch-indexer 설치#

GitLab-Elasticsearch-Indexer는 GNU Make를 사용합니다. 다음 명령은 권장 위치인 /home/git/gitlab-elasticsearch-indexer에 GitLab-Elasticsearch-Indexer를 설치합니다.

sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elasticsearch-indexer]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:indexer:install[/home/git/gitlab-elasticsearch-indexer,https://example.com/gitlab-elasticsearch-indexer.git]" RAILS_ENV=production

GitLab Pages 설치#

cd /home/git
sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git
cd gitlab-pages
sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION)
sudo -u git -H make

Gitaly 설치#

# Create and restrict access to the git repository data directory
sudo install -d -o git -m 0700 /home/git/repositories

# Fetch Gitaly source with Git and compile with Go
cd /home/git/gitlab
sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production

추가 매개변수로 다른 Git 리포지터리를 지정할 수 있습니다.

sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories,https://example.com/gitaly.git]" RAILS_ENV=production

다음으로 Gitaly가 설정되었는지 확인합니다.

# Restrict Gitaly socket access
sudo chmod 0700 /home/git/gitlab/tmp/sockets/private
sudo chown git /home/git/gitlab/tmp/sockets/private

# If you are using non-default settings, you need to update config.toml
cd /home/git/gitaly
sudo -u git -H editor config.toml

Gitaly 설정에 대한 자세한 내용은 Gitaly 문서를 참고합니다.

서비스 설치#

systemd 유닛 설치#

init로 systemd를 사용하는 경우 다음 단계를 따릅니다. 그 외에는 SysV init 스크립트 단계를 따릅니다.

서비스 파일을 복사하고 systemd가 인식하도록 systemctl daemon-reload를 실행합니다.

cd /home/git/gitlab
sudo mkdir -p /usr/local/lib/systemd/system
sudo cp lib/support/systemd/* /usr/local/lib/systemd/system/
sudo systemctl daemon-reload

GitLab 이 제공하는 유닛은 Redis와 PostgreSQL의 실행 위치에 대해 거의 가정하지 않습니다.

GitLab을 다른 디렉터리에 설치했거나 기본 사용자가 아닌 사용자로 설치했다면, 유닛의 해당 값도 함께 변경해야 합니다.

예를 들어 Redis와 PostgreSQL을 GitLab과 같은 머신에서 실행한다면 다음과 같이 합니다.

Puma 서비스를 편집합니다.

sudo systemctl edit gitlab-puma.service

열린 편집기에서 다음 내용을 추가하고 파일을 저장합니다.

[Unit]
Wants=redis-server.service postgresql.service
After=redis-server.service postgresql.service

Sidekiq 서비스를 편집합니다.

sudo systemctl edit gitlab-sidekiq.service

다음 내용을 추가하고 파일을 저장합니다.

[Unit]
Wants=redis-server.service postgresql.service
After=redis-server.service postgresql.service

systemctl edit를 쓰지 않고 유닛 파일을 직접 수정했거나 드롭인 설정 파일을 추가했다면, 변경 사항을 적용하기 위해 다음 명령을 실행합니다.

sudo systemctl daemon-reload

부팅 시 GitLab 이 시작되도록 설정합니다.

sudo systemctl enable gitlab.target

SysV init 스크립트 설치#

SysV init 스크립트를 사용하는 경우 다음 단계를 따릅니다. systemd를 사용한다면 systemd 유닛 단계를 따릅니다.

init 스크립트(/etc/init.d/gitlab)를 내려받습니다.

cd /home/git/gitlab
sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab

기본이 아닌 폴더나 사용자로 설치하는 경우에는 defaults 파일을 복사해 편집합니다.

sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab

부팅 시 GitLab 이 시작되도록 설정합니다.

sudo update-rc.d gitlab defaults 21
# or if running this on a machine running systemd
sudo systemctl daemon-reload
sudo systemctl enable gitlab.service

Logrotate 설정#

sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab

Gitaly 시작#

다음 섹션을 진행하려면 Gitaly가 실행 중이어야 합니다.

systemd로 Gitaly를 시작합니다.

sudo systemctl start gitlab-gitaly.service

SysV에서 Gitaly를 수동으로 시작합니다.

gitlab_path=/home/git/gitlab
gitaly_path=/home/git/gitaly

sudo -u git -H sh -c "$gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \
  $gitaly_path/_build/bin/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 &"

데이터베이스 초기화 및 고급 기능 활성화#

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production
# Type 'yes' to create the database tables.

# or you can skip the question by adding force=yes
sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes

# When done, you see 'Administrator account created:'

sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail GITLAB_ACTIVATION_CODE=yourcode

`secrets.yml` 보호#

애플리케이션 상태 확인#

GitLab과 그 환경이 올바르게 구성되었는지 확인합니다.

sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production

애셋 컴파일#

sudo -u git -H yarn install --production --pure-lockfile
sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production

rake가 JavaScript heap out of memory 오류로 실패하면 다음과 같이 NODE_OPTIONS를 지정해 실행합니다.

sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production NODE_OPTIONS="--max_old_space_size=4096"

GitLab 인스턴스 시작#

# For systems running systemd
sudo systemctl start gitlab.target

# For systems running SysV init
sudo service gitlab start

10. NGINX#

NGINX는 GitLab 이 공식적으로 지원하는 웹 서버입니다. NGINX를 웹 서버로 사용할 수 없거나 사용하지 않으려면 GitLab recipes를 참고합니다.

설치#

sudo apt-get install -y nginx

사이트 구성#

예제 사이트 설정 파일을 복사합니다.

sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab
sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab

설정 파일을 사용 환경에 맞게 수정합니다. 특히 git 이외의 사용자로 설치하는 경우에는 GitLab 경로가 일치하는지 확인합니다.

# Change YOUR_SERVER_FQDN to the fully-qualified
# domain name of your host serving GitLab.
#
# Remember to match your paths to GitLab, especially
# if installing for a user other than 'git'.
#
# If using Ubuntu default nginx install:
# either remove the default_server from the listen line
# or else sudo rm -f /etc/nginx/sites-enabled/default
sudo editor /etc/nginx/sites-available/gitlab

GitLab Pages를 활성화하려면 별도의 NGINX 설정을 사용해야 합니다. 필요한 설정은 GitLab Pages 관리 가이드에서 모두 확인합니다.

HTTPS를 사용하려면 gitlab NGINX 설정을 gitlab-ssl로 교체합니다. HTTPS 설정에 대한 자세한 내용은 HTTPS 사용을 참고합니다.

테스트 구성#

gitlab 또는 gitlab-ssl NGINX 구성 파일을 다음 명령으로 검증합니다:

sudo nginx -t

설치된 버전이 1.12.1보다 높은지 확인합니다:

nginx -v

버전이 더 낮으면 다음 오류가 발생할 수 있습니다:

nginx: [emerg] unknown "start$temp=[filtered]$rest" variable
nginx: configuration file /etc/nginx/nginx.conf test failed

재시작#

# For systems running systemd
sudo systemctl restart nginx.service

# For systems running SysV init
sudo service nginx restart

설치 후 작업#

애플리케이션 상태 재확인#

빠뜨린 항목이 없는지 다음 명령으로 더 철저히 점검합니다:

sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production

모든 항목이 녹색이면 GitLab 설치에 성공한 것입니다.

Note

gitlab:check에 SANITIZE=true 환경 변수를 지정하면 점검 명령 출력에서 프로젝트 이름을 제외합니다.

최초 로그인#

첫 GitLab 로그인을 위해 웹 브라우저에서 YOUR_SERVER에 접속합니다.

기본 계정의 사용자 이름은 root 입니다. 앞서 만든 비밀번호를 입력하여 로그인합니다. 로그인 후에는 원한다면 사용자 이름을 변경할 수 있습니다.

GitLab을 시작하고 중지하는 방법은 다음과 같습니다:

systemd 유닛: sudo systemctl start gitlab.target 또는 sudo systemctl stop gitlab.target을 사용합니다.
SysV init 스크립트: sudo service gitlab start 또는 sudo service gitlab stop을 사용합니다.

권장 다음 단계#

설치를 마친 후에는 인증 옵션과 신규 사용자 계정 제한을 포함한 권장 다음 단계를 검토하는 것이 좋습니다.

고급 설정 팁#

상대 URL 지원#

상대 URL로 GitLab을 구성하는 방법은 상대 URL 문서를 참고합니다.

HTTPS 사용#

HTTPS로 GitLab을 사용하려면 다음과 같이 합니다:

gitlab.yml에서 다음을 수행합니다:
1. 섹션 1의 port 옵션을 443으로 설정합니다.
2. 섹션 1의 https 옵션을 true로 설정합니다.
GitLab Shell의 config.yml에서 다음을 수행합니다:
1. gitlab_url 옵션을 GitLab의 HTTPS 엔드포인트(예: https://git.example.com)로 설정합니다.
2. ca_file 또는 ca_path 옵션으로 인증서를 설정합니다.
gitlab 구성 대신 gitlab-ssl NGINX 예제 구성을 사용합니다.
1. YOUR_SERVER_FQDN을 업데이트합니다.
2. ssl_certificate와 ssl_certificate_key를 업데이트합니다.
3. 구성 파일을 검토하고 다른 보안 및 성능 향상 기능의 적용을 검토합니다.

자체 서명 인증서 사용은 권장하지 않습니다. 반드시 사용해야 한다면 표준 절차에 따라 자체 서명 SSL 인증서를 생성합니다:

mkdir -p /etc/nginx/ssl/
cd /etc/nginx/ssl/
sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key
sudo chmod o-r gitlab.key

이메일 회신 활성화#

설정 방법은 "이메일 회신" 문서를 참고합니다.

LDAP 인증#

config/gitlab.yml에서 LDAP 인증을 구성할 수 있습니다. 이 파일을 편집한 후에는 GitLab을 재시작합니다.

커스텀 OmniAuth 공급자 사용#

OmniAuth 통합 문서를 참고합니다.

프로젝트 빌드#

GitLab은 프로젝트를 빌드할 수 있습니다. 이 기능을 사용하려면 빌드를 수행할 러너가 필요합니다. 설치 방법은 GitLab Runner 섹션을 참고합니다.

신뢰할 수 있는 프록시 추가#

URL에 잘못 인코딩된 문자 때문에 문제가 발생하면 오류: 리버스 프록시 사용 시 404 Not Found를 참고합니다.

커스텀 Redis 연결#

표준이 아닌 포트나 다른 호스트의 Redis 서버에 연결하려면 config/resque.yml 파일에서 연결 문자열을 구성할 수 있습니다.

# example
production:
  url: redis://redis.example.tld:6379

소켓으로 Redis 서버에 연결하려면 config/resque.yml 파일에서 unix: URL 스킴과 Redis 소켓 파일 경로를 사용합니다.

# example
production:
  url: unix:/path/to/redis/socket

또한 config/resque.yml 파일에서 환경 변수를 사용할 수 있습니다:

# example
production:
  url: <%= ENV.fetch('GITLAB_REDIS_URL') %>

커스텀 SSH 연결#

표준이 아닌 포트에서 SSH를 실행한다면 GitLab 사용자의 SSH 구성을 변경해야 합니다.

# Add to /home/git/.ssh/config
host localhost          # Give your setup a name (here: override localhost)
    user git            # Your remote git user
    port 2222           # Your port number
    hostname 127.0.0.1; # Your server name or IP

config/gitlab.yml 파일에서 대응하는 옵션(예: ssh_user, ssh_host, admin_uri)도 변경해야 합니다.

추가 마크업 스타일#

Prometheus 서버 설정#

config/gitlab.yml에서 Prometheus 서버를 구성할 수 있습니다:

# example
prometheus:
  enabled: true
  server_address: '10.1.2.3:9090'

문제 해결#

메시지: `You appear to have cloned an empty repository.`#

`google-protobuf` 오류: `LoadError: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.14' not found`#

일부 플랫폼에서 특정 버전의 google-protobuf gem을 사용할 때 발생할 수 있습니다. 해결 방법은 이 gem의 소스 전용 버전을 설치하는 것입니다.

먼저 설치된 GitLab 이 요구하는 google-protobuf의 정확한 버전을 확인해야 합니다:

cd /home/git/gitlab

# Only one of the following two commands will print something. It
# will look like: * google-protobuf (3.2.0)
bundle list | grep google-protobuf
bundle check | grep google-protobuf

다음 명령에서 3.2.0은 예시입니다. 앞서 확인한 버전 번호로 바꿉니다:

cd /home/git/gitlab
sudo -u git -H gem install google-protobuf --version 3.2.0 --platform ruby

마지막으로 google-protobuf 이 올바르게 로드되는지 테스트할 수 있습니다. 다음 명령은 OK를 출력해야 합니다.

sudo -u git -H bundle exec ruby -rgoogle/protobuf -e 'puts :OK'

gem install 명령이 실패하면 운영체제의 개발자 도구를 설치해야 할 수 있습니다.

Debian/Ubuntu에서는 다음과 같습니다:

sudo apt-get install build-essential libgmp-dev

RedHat/CentOS에서는 다음과 같습니다:

sudo yum groupinstall 'Development Tools'

GitLab 에셋 컴파일 오류#

에셋을 컴파일할 때 다음 오류 메시지가 표시될 수 있습니다:

Killed
error Command failed with exit code 137.

Yarn 이 메모리가 부족한 컨테이너를 종료할 때 발생할 수 있습니다. 해결 방법은 다음과 같습니다:

시스템 메모리를 최소 8GB로 늘립니다.

다음 명령으로 에셋을 정리합니다:

sudo -u git -H bundle exec rake gitlab:assets:clean RAILS_ENV=production NODE_ENV=production

yarn 명령을 다시 실행하여 충돌을 해결합니다:
```
sudo -u git -H yarn install --production --pure-lockfile
```

에셋을 다시 컴파일합니다:

sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production

소스 코드 직접 컴파일 설치

Linux 패키지 설치 검토#

설치할 버전 선택#

소프트웨어 요구 사항#

GitLab 디렉터리 구조#

설치 워크플로#

1. 패키지 및 의존성#

sudo#

빌드 의존성#

Git#

GraphicsMagick#

메일 서버#

ExifTool#

2. Ruby#

3. RubyGems#

4. Go#

5. Node#

6. 시스템 사용자#

7. 데이터베이스#

8. Redis#

systemd로 Redis 감시#

Redis를 감독 없이 두기#

9. GitLab#

소스 클론#

설정하기#

GitLab 데이터베이스(DB) 설정 구성#

Gem 설치#

GitLab Shell 설치#

GitLab Workhorse 설치#

Enterprise Edition에 GitLab-Elasticsearch-indexer 설치#

GitLab Pages 설치#

Gitaly 설치#

서비스 설치#

systemd 유닛 설치#

SysV init 스크립트 설치#

Logrotate 설정#

Gitaly 시작#

데이터베이스 초기화 및 고급 기능 활성화#

secrets.yml 보호#

애플리케이션 상태 확인#

애셋 컴파일#

GitLab 인스턴스 시작#

10. NGINX#

설치#

사이트 구성#

테스트 구성#

재시작#

설치 후 작업#

애플리케이션 상태 재확인#

최초 로그인#

권장 다음 단계#

고급 설정 팁#

상대 URL 지원#

HTTPS 사용#

이메일 회신 활성화#

LDAP 인증#

커스텀 OmniAuth 공급자 사용#

프로젝트 빌드#

신뢰할 수 있는 프록시 추가#

커스텀 Redis 연결#

커스텀 SSH 연결#

추가 마크업 스타일#

Prometheus 서버 설정#

문제 해결#

메시지: You appear to have cloned an empty repository.#

google-protobuf 오류: LoadError: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.14' not found#

GitLab 에셋 컴파일 오류#

소스 코드 직접 컴파일 설치

Linux 패키지 설치 검토#

설치할 버전 선택#

소프트웨어 요구 사항#

GitLab 디렉터리 구조#

설치 워크플로#

1. 패키지 및 의존성#

sudo#

빌드 의존성#

Git#

GraphicsMagick#

메일 서버#

ExifTool#

`secrets.yml` 보호#

메시지: `You appear to have cloned an empty repository.`#

`google-protobuf` 오류: `LoadError: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.14' not found`#

`secrets.yml` 보호#

메시지: `You appear to have cloned an empty repository.`#

`google-protobuf` 오류: `LoadError: /lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.14' not found`#