이 문서는 소스 컴파일 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 서버 또는 DNS 공급업체에서 GitLab 이 실행되는 호스트를 가리키는 와일드카드 DNS A 레코드를 추가합니다. 예:

*.example.io. 1800 IN A 192.0.2.1

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

구성#

GitLab Pages는 여러 방식으로 설정할 수 있습니다. 다음 옵션은 가장 단순한 설정부터 가장 고급 설정까지 순서대로 나열되어 있습니다. 모든 구성의 최소 요건은 와일드카드 DNS 레코드입니다.

와일드카드 도메인#

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

사전 요구 사항:

• 와일드카드 DNS 설정

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

1. 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
   

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

   cd /home/git/gitlab
   

3. 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
   

4. 다음 구성 파일을 /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
   
   GitLab Pages 와 GitLab 을 같은 호스트에서 실행하는 경우에는 `http` 주소를 사용할 수 있습니다.
   자체 서명 인증서로 `https` 를 사용한다면, 예를 들어 `SSL_CERT_DIR` 환경 변수를 설정해
   커스텀 CA 를 GitLab Pages 에서 사용할 수 있게 합니다.
   
   

5. 시크릿 API 키를 추가합니다.

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

6. 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
     

7. 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
   

8. NGINX 를 재시작합니다.

9. GitLab 을 재시작합니다.

TLS 를 지원하는 와일드카드 도메인#

사전 요구 사항:

• 와일드카드 DNS 설정
• 와일드카드 TLS 인증서

URL 스킴: https://<namespace>.example.io/<project_slug>

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

TLS 를 지원하는 와일드카드 도메인을 구성하는 방법은 다음과 같습니다.

1. 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
   

2. 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
   

3. /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"
   

4. 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
   

5. NGINX 를 재시작합니다.

6. GitLab 을 재시작합니다.

고급 구성#

와일드카드 도메인 외에도, TLS 인증서를 사용하거나 사용하지 않는 커스텀 도메인에서 GitLab Pages 가 동작하도록 구성할 수 있습니다.

커스텀 도메인#

사전 요구 사항:

• 와일드카드 DNS 설정
• 보조 IP

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

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

커스텀 도메인을 구성하는 방법은 다음과 같습니다.

1. 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
   

2. 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
   

3. /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"
   

4. 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
   

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

6. NGINX 를 재시작합니다.

7. GitLab 을 재시작합니다.

TLS 를 지원하는 커스텀 도메인#

사전 요구 사항:

• 와일드카드 DNS 설정
• 와일드카드 TLS 인증서
• 보조 IP

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

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

TLS 를 지원하는 커스텀 도메인을 구성하는 방법은 다음과 같습니다.

1. 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
   

2. 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
   

3. /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"
   

4. 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
   

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

6. NGINX 를 재시작합니다.

7. 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 액세스 제어는 기본적으로 비활성화되어 있습니다. 활성화하는 방법은 다음과 같습니다.

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

   pages:
     access_control: true
   

2. GitLab 을 재시작합니다.

3. 새 시스템 OAuth 애플리케이션을 생성합니다. 이름을 GitLab Pages 로 지정하고 Redirect URL 을 https://projects.example.io/auth 로 설정합니다. 신뢰할 수 있는 애플리케이션일 필요는 없지만 api 스코프는 필요합니다.

4. 다음 인자를 담은 구성 파일을 전달해 Pages 데몬을 시작합니다.

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

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

스토리지 경로 변경#

GitLab Pages 콘텐츠가 저장되는 기본 경로를 변경하는 방법은 다음과 같습니다.

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

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

2. GitLab을 재시작합니다.

Pages 최대 크기 설정#

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

사전 요구 사항:

• 관리자 액세스 권한이 있습니다.

이 값을 변경하는 방법은 다음과 같습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > Preferences를 선택합니다.
3. Pages를 확장합니다.
4. Maximum size of pages (MB) 값을 업데이트합니다.

백업#

Pages는 정기 백업에 포함되므로 구성할 것이 없습니다.

보안#

XSS 공격을 방지하기 위해 GitLab Pages를 GitLab과 다른 호스트 이름으로 실행하는 방안을 적극적으로 검토해야 합니다.