GitLab Pages를 활성화하기 전에, 먼저 GitLab을 성공적으로 설치했는지 확인하세요.

이 문서는 소스에서 컴파일된 GitLab 설치 환경에서 GitLab Pages를 구성하는 방법을 설명합니다.

Linux 패키지 설치(권장)에서 GitLab Pages를 구성하는 방법에 대한 자세한 내용은 Linux 패키지 문서를 참조하세요. Linux 패키지 설치에는 GitLab Pages의 최신 지원 버전이 포함되어 있습니다.

GitLab Pages 데몬#

GitLab Pages는 GitLab Pages 데몬을 사용합니다. 이는 외부 IP 주소에서 수신 대기하며 커스텀 도메인 및 인증서를 지원하는 경량 HTTP 서버입니다. SNI를 통한 동적 인증서를 지원하고, 기본적으로 HTTP2를 사용하여 페이지를 제공합니다. 자세한 내용은 README를 참조하세요.

커스텀 도메인의 경우, Pages 데몬은 포트 80 또는 443에서 수신 대기해야 합니다. 이는 와일드카드 도메인에는 적용되지 않습니다. Pages 데몬은 다음 방법 중 하나로 설정할 수 있습니다:

• GitLab과 동일한 서버에서, 보조 IP로 수신 대기.

• 별도의 서버에서. Pages 경로는 해당 서버에도 존재해야 하므로 네트워크를 통해 공유해야 합니다.

• GitLab과 동일한 서버에서, 동일한 IP이지만 다른 포트로 수신 대기. 이 경우, 로드 밸런서로 트래픽을 프록시해야 합니다. HTTPS의 경우 TCP 로드 밸런싱을 사용하세요. TLS 종료(HTTPS 로드 밸런싱)를 사용하면 사용자 제공 인증서로 페이지를 제공할 수 없습니다. HTTP의 경우 HTTP 또는 TCP 로드 밸런싱 모두 사용 가능합니다.

아래 섹션에서는 첫 번째 옵션을 기준으로 설명합니다. 커스텀 도메인을 지원하지 않는 경우 보조 IP는 필요하지 않습니다.

사전 요건#

Pages 구성을 진행하기 전에 다음 사항을 확인하세요:

• GitLab Pages를 제공할 별도의 도메인이 있어야 합니다. 이 문서에서 해당 도메인은 example.io입니다.

• 해당 도메인에 대한 와일드카드 DNS 레코드를 구성했어야 합니다.

• GitLab이 설치된 동일한 서버에 zip 및 unzip 패키지가 설치되어 있어야 합니다. 이 패키지들은 Pages 아티팩트를 압축하고 압축 해제하는 데 필요합니다.

• 선택 사항. HTTPS로 Pages를 제공하기로 결정한 경우, Pages 도메인(*.example.io)에 대한 와일드카드 인증서가 있어야 합니다.

• 선택 사항이지만 권장됨. 사용자가 자체적으로 러너를 설정하지 않아도 되도록 인스턴스 러너를 구성하고 활성화했어야 합니다.

DNS 구성#

GitLab Pages는 자체 가상 호스트에서 실행되어야 합니다. DNS 서버 또는 제공업체에서 GitLab이 실행 중인 호스트를 가리키는 와일드카드 DNS A 레코드를 추가하세요. 예:

*.example.io. 1800 IN A 192.0.2.1

여기서 example.io는 GitLab Pages가 제공되는 도메인이고, 192.0.2.1은 GitLab 인스턴스의 IP 주소입니다.

참고: 사용자 페이지를 제공하는 데 GitLab 도메인을 사용하지 마세요. 자세한 내용은 보안 섹션을 참조하세요.

구성#

GitLab Pages를 여러 방법으로 설정할 수 있습니다. 다음 옵션들은 가장 단순한 설정부터 가장 고급 설정 순으로 나열됩니다. 모든 구성에 대한 최소 요건은 와일드카드 DNS 레코드입니다.

와일드카드 도메인#

각 사이트는 자체 서브도메인을 가집니다(예: <namespace>.example.io/<project_slug>). 이 서브도메인은 와일드카드 DNS 레코드(*.example.io)가 필요하며, 대부분의 인스턴스에 권장되는 설정입니다.

사전 요건:

• 와일드카드 DNS 설정

이 설정은 Pages를 사용할 수 있는 최소 구성입니다. 아래에 설명된 다른 모든 설정의 기반이 됩니다. NGINX는 모든 요청을 데몬으로 프록시합니다. Pages 데몬은 외부와 직접 통신하지 않습니다.

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

GitLab 설치 디렉터리로 이동합니다:

cd /home/git/gitlab

gitlab.yml을 편집하고 pages 설정 아래에서 enabled를 true로 설정하고, host를 GitLab Pages를 제공할 FQDN으로 설정합니다:

## GitLab Pages
pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  # path: shared/pages

  host: example.io
  access_control: false
  port: 8090
  https: false
  artifacts_server: false
  external_http: ["127.0.0.1:8090"]
  secret_file: /home/git/gitlab/gitlab-pages-secret

/home/git/gitlab-pages/gitlab-pages.conf에 다음 구성 파일을 추가합니다. example.io를 GitLab Pages를 제공할 FQDN으로, gitlab.example.com을 GitLab 인스턴스의 URL로 바꾸세요:

listen-http=:8090
pages-root=/home/git/gitlab/shared/pages
api-secret-key=/home/git/gitlab/gitlab-pages-secret
pages-domain=example.io
internal-gitlab-server=https://gitlab.example.com

You can use an `http` address when running GitLab Pages and GitLab on the same host. If you use
`https` with a self-signed certificate, make your custom CA available to GitLab Pages, for
example by setting the `SSL_CERT_DIR` environment variable.

비밀 API 키를 추가합니다:

sudo -u git -H openssl rand -base64 32 > /home/git/gitlab/gitlab-pages-secret

Pages 데몬을 활성화하려면:

시스템이 systemd init을 사용하는 경우 다음을 실행합니다:

sudo systemctl edit gitlab.target

편집기에서 다음을 추가하고 파일을 저장합니다:

[Unit]
Wants=gitlab-pages.service

시스템이 SysV init을 사용하는 경우, /etc/default/gitlab을 편집하고 gitlab_pages_enabled를 true로 설정합니다:

gitlab_pages_enabled=true

gitlab-pages NGINX 구성 파일을 복사합니다:

sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf

NGINX를 재시작합니다.

GitLab을 재시작합니다.

TLS 지원이 있는 와일드카드 도메인#

사전 요건:

• 와일드카드 DNS 설정

• 와일드카드 TLS 인증서

URL 구성: https://<namespace>.example.io/<project_slug>

NGINX는 모든 요청을 데몬으로 프록시합니다. Pages 데몬은 공용 인터넷에서 직접 수신 대기하지 않습니다.

TLS 지원이 있는 와일드카드 도메인을 구성하려면:

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

gitlab.yml에서 port를 443으로, https를 true로 설정합니다:

## GitLab Pages
pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  # path: shared/pages

  host: example.io
  port: 443
  https: true

/etc/default/gitlab을 편집하고 gitlab_pages_enabled를 true로 설정합니다. gitlab_pages_options에서 -pages-domain은 host 값과 일치해야 합니다. -root-cert 및 -root-key 설정은 example.io 도메인의 와일드카드 TLS 인증서입니다:

gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key"

gitlab-pages-ssl NGINX 구성 파일을 복사합니다:

sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf

NGINX를 재시작합니다.

GitLab을 재시작합니다.

고급 구성#

와일드카드 도메인 외에도, TLS 인증서 유무에 관계없이 커스텀 도메인을 사용하도록 GitLab Pages를 구성할 수 있습니다.

커스텀 도메인#

사전 요건:

• 와일드카드 DNS 설정

• 보조 IP

URL 구성: http://<namespace>.example.io/<project_slug> 및 http://custom-domain.com

이 구성에서는 Pages 데몬이 실행되고 NGINX가 요청을 프록시하지만, 데몬은 공용 인터넷에서도 요청을 받을 수 있습니다. TLS 없이 커스텀 도메인이 지원됩니다.

커스텀 도메인을 구성하려면:

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

gitlab.yml을 편집합니다. host를 GitLab Pages를 제공할 FQDN으로 설정하고, external_http를 Pages 데몬이 수신 대기하는 보조 IP로 설정합니다:

pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  # path: shared/pages

  host: example.io
  port: 80
  https: false

  external_http: 192.0.2.2:80

/etc/default/gitlab을 편집하고 gitlab_pages_enabled를 true로 설정합니다. gitlab_pages_options에서:

-pages-domain은 host와 일치해야 합니다.

• -listen-http는 external_http와 일치해야 합니다.

• -listen-https는 external_https와 일치해야 합니다.

gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80"

gitlab-pages NGINX 구성 파일을 복사합니다:

sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf

/etc/nginx/site-available/에서 모든 GitLab 관련 구성을 편집하고 0.0.0.0을 192.0.2.1로 바꿉니다. 여기서 192.0.2.1은 GitLab이 수신 대기하는 기본 IP입니다.

NGINX를 재시작합니다.

GitLab을 재시작합니다.

TLS 지원이 있는 커스텀 도메인#

사전 요건:

• 와일드카드 DNS 설정

• 와일드카드 TLS 인증서

• 보조 IP

URL 구성: https://<namespace>.example.io/<project_slug> 및 https://custom-domain.com

이 구성에서는 Pages 데몬이 실행되고 NGINX가 요청을 프록시하지만, 데몬은 공용 인터넷에서도 요청을 받을 수 있습니다. 커스텀 도메인과 TLS가 지원됩니다.

TLS 지원이 있는 커스텀 도메인을 구성하려면:

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

gitlab.yml을 편집합니다. host를 GitLab Pages를 제공할 FQDN으로 설정하고, external_http와 external_https를 Pages 데몬이 수신 대기하는 보조 IP로 설정합니다:

## GitLab Pages
pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  # path: shared/pages

  host: example.io
  port: 443
  https: true

  external_http: 192.0.2.2:80
  external_https: 192.0.2.2:443

/etc/default/gitlab을 편집하고 gitlab_pages_enabled를 true로 설정합니다. gitlab_pages_options에서:

-pages-domain은 host와 일치해야 합니다.

• -listen-http는 external_http와 일치해야 합니다.

• -listen-https는 external_https와 일치해야 합니다.

-root-cert 및 -root-key 설정은 example.io 도메인의 와일드카드 TLS 인증서입니다:

gitlab_pages_enabled=true
gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -listen-http 192.0.2.2:80 -listen-https 192.0.2.2:443 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key"

gitlab-pages-ssl NGINX 구성 파일을 복사합니다:

sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf
sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf

/etc/nginx/site-available/에서 모든 GitLab 관련 구성을 편집하고 0.0.0.0을 192.0.2.1로 바꿉니다. 여기서 192.0.2.1은 GitLab이 수신 대기하는 기본 IP입니다.

NGINX를 재시작합니다.

GitLab을 재시작합니다.

NGINX 주의 사항#

참고: 다음 정보는 소스 설치 환경에만 적용됩니다.

NGINX 구성에서 도메인 이름을 설정할 때 주의하세요. 백슬래시를 제거하면 안 됩니다.

GitLab Pages 도메인이 example.io인 경우, 다음을 바꾸세요:

server_name ~^.*\.YOUR_GITLAB_PAGES\.DOMAIN$;

다음으로:

server_name ~^.*\.example\.io$;

서브도메인을 사용하는 경우, 첫 번째를 제외한 모든 점(.)을 백슬래시(\)로 이스케이프하세요. 예를 들어, pages.example.io는 다음과 같습니다:

server_name ~^.*\.pages\.example\.io$;

접근 제어#

GitLab Pages 접근 제어는 프로젝트별로 구성할 수 있습니다. Pages 사이트에 대한 접근은 사용자의 해당 프로젝트 멤버십을 기반으로 제어할 수 있습니다.

접근 제어는 Pages 데몬을 GitLab에 OAuth 애플리케이션으로 등록하는 방식으로 작동합니다. 인증되지 않은 사용자가 비공개 Pages 사이트에 접근을 요청하면, Pages 데몬은 사용자를 GitLab으로 리디렉션합니다. 인증이 성공하면, 사용자는 토큰과 함께 Pages로 다시 리디렉션되며, 이 토큰은 쿠키에 저장됩니다. 쿠키는 비밀 키로 서명되므로 조작 여부를 감지할 수 있습니다.

비공개 사이트의 리소스를 볼 때 각 요청은 해당 토큰을 사용하여 Pages가 인증합니다. Pages가 받는 각 요청에 대해 GitLab API에 요청하여 사용자가 해당 사이트를 읽을 권한이 있는지 확인합니다.

Pages의 접근 제어 파라미터는:

• gitlab-pages-config라는 이름 규칙으로 구성 파일에 설정됩니다.

• -config 플래그 또는 CONFIG 환경 변수를 사용하여 Pages에 전달됩니다.

Pages 접근 제어는 기본적으로 비활성화되어 있습니다. 활성화하려면:

config/gitlab.yml을 수정합니다:

pages:
  access_control: true

GitLab을 재시작합니다.

새로운 시스템 OAuth 애플리케이션을 만듭니다. 이름을 GitLab Pages로 지정하고 리디렉션 URL을 https://projects.example.io/auth로 설정합니다. 신뢰할 수 있는 애플리케이션일 필요는 없지만, api 범위가 필요합니다.

다음 인수와 함께 구성 파일을 전달하여 Pages 데몬을 시작합니다:

  auth-client-id=
  auth-client-secret=
  auth-redirect-uri='http://projects.example.io/auth'
  auth-secret=<40 random hex characters>
  auth-server=

이제 사용자는 프로젝트 설정에서 이를 구성할 수 있습니다.

스토리지 경로 변경#

GitLab Pages 콘텐츠가 저장되는 기본 경로를 변경하려면:

Pages는 기본적으로 /home/git/gitlab/shared/pages에 저장됩니다. 다른 위치를 사용하려면, pages 섹션 아래의 gitlab.yml을 편집합니다:

pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  path: /mnt/storage/pages

GitLab을 재시작합니다.

Pages 최대 크기 설정#

프로젝트당 압축 해제 아카이브의 기본 최대 크기는 100 MB입니다.

사전 요건:

• 관리자 접근 권한.

이 값을 변경하려면:

• 오른쪽 상단 모서리에서 Admin을 선택합니다.

• 왼쪽 사이드바에서 Settings > Preferences를 선택합니다.

• Pages를 확장합니다.

• Maximum size of pages (MB) 값을 업데이트합니다.

백업#

Pages는 정기 백업의 일부이므로 별도로 구성할 필요가 없습니다.

보안#

XSS 공격을 방지하기 위해 GitLab과 다른 호스트 이름에서 GitLab Pages를 실행하는 것을 강력히 권장합니다.