GitLab 페이지 관리자 가이드

개요

GitLab Pages는 Go로 작성된 간단한 HTTP 서버인 GitLab Pages 데몬을 사용하여 외부 IP 주소를 수신하고 사용자 지정 도메인 및 사용자 지정 인증서를 지원할 수 있습니다.

• 와일드 카드 도메인이 아닌 사용자 정의 도메인 의 경우 Pages 데몬은 포트 80 /443에서 수신.

• 보조 IP 에서 수신 대기하는 GitLab과 동일한 서버에서 Pages 데몬을 실행.

• 별도의 서버에서 Pages 데몬을 실행. 
  (Pages 데몬이 설치된 서버에 Pages 경로도 있어야하므로 네트워크를 통해 공유해야함)

• 동일한 IP에서 다른 포트에서 수신 대기하면서 GitLab과 동일한 서버에서 Pages 데몬을 실행(로드 밸런서로 트래픽을 프록시 해야함) 해당 경로를 선택하면 HTTPS에 TCP로드 밸런싱을 사용해야하며, TLS 종료 (HTTPS-로드 밸런싱)를 사용하면 사용자가 제공 한 인증서로 페이지를 제공 할 수 없습니다. 
  (HTTP의 경우 HTTP 또는 TCP로드 밸런싱을 사용하는 것을 권장)

전제 조건

페이지 구성을 진행하기 전에 다음을 수행해야합니다.

1. GitLab Pages를 제공하기위한 전용 루트 도메인이 있어야하며,  GitLab 인스턴스 도메인의 하위 도메인은 사용할 수 없습니다.

2. 와일드 카드 DNS 레코드를 구성.

3. (선택 사항) HTTPS에서 페이지를 제공하기로 결정한 경우 해당 도메인에 대한 와일드 카드 인증서가 있어야함.

4. (선택적이지만 권장 됨) 사용자가 자신의 것을 가져올 필요가 없도록 공유 러너를 활성화.

5. (사용자 정의 도메인에만 해당) 보조 IP가 있음.

Public Suffix List에 도메인 추가

Public Suffix List 하위 도메인을 처리하는 방법을 결정하는 브라우저에서 사용되며 GitLab 인스턴스를 통해 일반 구성원이 GitLab Pages 사이트를 만들 수 있으면 해당 사용자가 페이지 도메인 ( example.io) 에 하위 도메인을 만들 수도 있습니다. 도메인을 공개 접미사 목록에 추가하면 브라우저가 다른 무엇보다도 슈퍼 쿠키를 허용하지 않습니다 .

지침에 따라 GitLab 페이지 하위 도메인을 제출합니다. 예를 들어 도메인이 example.io인 경우 Public Suffix List에 추가하도록 요청해야 합니다.

DNS 구성

DNS 서버 / 제공자 에서 GitLab이 실행하는 호스트를 가리키는 wildcard DNS A record를 추가해야 합니다. 
예를 들어, 항목은 다음과 같습니다.

*.example.io. 1800 IN A    192.0.2.1
*.example.io. 1800 IN AAAA 2001::1

여기서 example.io GitLab Pages가 제공되는 도메인 192.0.2.1은 GitLab 인스턴스의 IPv4 주소이며 2001::1IPv6 주소입니다. IPv6이없는 경우 AAAA 레코드를 생략 할 수 있습니다.

구성

필요에 따라 4 가지 방식으로 GitLab Pages를 설정할 수 있습니다.

다음 예제는 가장 쉬운 설정에서 가장 고급 설정에 이르기까지 나열되어 있습니다. 최소 요구 사항은 모든 구성에 필요하므로 와일드 카드 DNS를 설정하는 것입니다.

와일드 카드 도메인

요구 사항 :

• 와일드카드 DNS 설정

URL 체계 : http://page.example.io

• 페이지를 사용할 수 있는 최소 설정이며 아래에 설명 된대로 다른 모든 설정의 기반입니다. 

• NGINX는 모든 요청을 데몬에 프록시합니다.

1. GitLab 페이지의 외부 URL을 다음 위치에 설정하십시오 /etc/gitlab/gitlab.rb.

   pages_external_url 'http://example.io'
   

2. GitLab을 재구성.

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

요구 사항 :

• 와일드 카드 DNS 설정

• 와일드 카드 TLS 인증서

URL 체계 : https://page.example.io

NGINX는 모든 요청을 데몬에 프록시합니다.

1. /etc/gitlab/ssl에 인증서와 키를 안에 넣습니다

2.  /etc/gitlab/gitlab.rb에서 다음과 같은 구성을 지정합니다 :

   pages_external_url 'https://example.io'
   
   pages_nginx['redirect_http_to_https'] = true
   pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages-nginx.crt"
   pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages-nginx.key"
   

   pages-nginx.crt와 pages-nginx.key은 각각의 SSL 인증서 및 키입니다.

3. GitLab을 재구성.

Docker 컨테이너에 대한 추가 구성

GitLab Pages 데몬은 Docker 컨테이너에서 실행될 때 마운트를 바인딩 할 권한이 없습니다. 

1. 편집 /etc/gitlab/gitlab.rb.

2. GitLab 페이지 의 inplace_chroot로 설정하십시오 true:

   gitlab_pages['inplace_chroot'] = true
   

3. GitLab을 재구성.

글로벌 설정

아래는 Omnibus GitLab의 Pages에 알려진 모든 구성 설정과 그 기능에 대한 표입니다. 이 옵션은에서 조정할 수 있으며 /etc/gitlab/gitlab.rb Gitlab을 재구성한 후에 적용됩니다 . Pages 데몬이 환경에서 컨텐츠를 실행하고 제공하는 방법을보다 세밀하게 제어해야하는 경우가 아니면 이러한 설정 대부분을 수동으로 구성 할 필요가 없습니다.

고급 구성

• 와일드 카드 도메인 외에도 사용자 정의 도메인과 함께 작동하도록 GitLab Pages를 구성하는 옵션이 있습니다. 여기서도 TLS 인증서가 있거나없는 사용자 정의 도메인 지원이라는 두 가지 옵션이 있습니다. 가장 쉬운 설정은 TLS 인증서가없는 것입니다. 두 경우 모두 보조 IP 가 필요합니다 . IPv4 주소뿐만 아니라 IPv6가있는 경우 둘 다 사용할 수 있습니다.

맞춤 도메인

요구 사항 :

• 와일드 카드 DNS 설정

• 보조 IP

URL 체계 : http://page.example.io 및 http://domain.com

이 경우 Pages 데몬이 실행 중이고 NGINX는 여전히 데몬에 대한 요청을 프록시하지만 데몬은 외부 세계로부터 요청을 수신 할 수도 있습니다. 사용자 정의 도메인은 지원되지만 TLS는 지원되지 않습니다.

1. 편집 /etc/gitlab/gitlab.rb:

   pages_external_url "http://example.io"
   nginx['listen_addresses'] = ['192.0.2.1']
   pages_nginx['enable'] = false
   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']

2. GitLab을 재구성

TLS를 지원하는 사용자 정의 도메인

요구 사항 :

• 와일드 카드 DNS 설정

• 와일드 카드 TLS 인증서

• 보조 IP

URL 체계 : https://page.example.io및https://domain.com

이 경우 Pages 데몬이 실행 중이고 NGINX는 여전히 데몬에 대한 요청을 프록시하지만 데몬은 외부 세계로부터 요청을 수신 할 수도 있습니다. 사용자 정의 도메인 및 TLS가 지원됩니다.

1. 편집 /etc/gitlab/gitlab.rb:

   pages_external_url "https://example.io"
   nginx['listen_addresses'] = ['192.0.2.1']
   pages_nginx['enable'] = false
   gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt"
   gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key"
   gitlab_pages['external_http'] = ['192.0.2.2:80', '[2001::2]:80']
   gitlab_pages['external_https'] = ['192.0.2.2:443', '[2001::2]:443']
   

2. GitLab을 재구성

맞춤 도메인 확인

악의적인 사용자가 자신이 아닌 도메인을 가로 채지 못하게하기 위해 GitLab은 사용자 지정 도메인 확인을 지원합니다. 사용자 정의 도메인을 추가 할 때 사용자는 해당 도메인의 DNS 레코드에 GitLab 제어 인증 코드를 추가하여 자신이 소유하고 있음을 증명해야합니다.

사용자 기반이 개인 정보이거나 신뢰할 수없는 경우 확인 요구 사항을 비활성화할 수 있습니다. Pages 섹션 에서  Admin Area > Settings > Preferences 이동하여 Require users to prove ownership of custom domains 을 취소 하면 됩니다. 이 설정은 기본적으로 활성화되어 있습니다.

Let’s Encrypt integration

GitLab 12.1에 도입 되었습니다.

GitLab Pages의 Let 's Encrypt 통합 기능을 사용하면 사용자 지정 도메인에서 제공되는 GitLab Pages 사이트에 대해 SSL 인증서를 Let 's Encrypt SSL 인증서에 추가 할 수 있습니다.

이를 활성화하려면 다음이 필요합니다.

1. 도메인 만료에 대한 알림을받을 이메일을 선택

2. 인스턴스의 Admin Area > Settings > Preferences 으로 이동하여 Pages 설정에서 알림을 받을 이메일을 입력하고 아래와 같이 Let 's Encrypt의 서비스 약관에 동의.

3. Save changes을 클릭.

액세스 제어

GitLab 11.5에 도입 되었습니다.

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

액세스 제어는 GitLab에 Pages 데몬을 OAuth 응용 프로그램으로 등록하여 작동합니다. 인증되지 않은 사용자가 개인 페이지 사이트에 대한 액세스 요청을 할 때마다 Pages 데몬은 사용자를 GitLab으로 리디렉션합니다. 인증이 성공하면 사용자는 쿠키로 유지되는 토큰을 사용하여 페이지로 다시 리디렉션 됩니다. 쿠키는 비밀 키로 서명되므로 변조가 감지 될 수 있습니다.

개인 사이트에서 리소스를 보는 각 요청은 해당 토큰을 사용하여 Pages에 의해 인증됩니다. 수신 된 각 요청에 대해 GitLab API에 사용자가 해당 사이트를 읽을 수있는 권한이 있는지 확인하도록 요청합니다.

페이지 액세스 제어는 기본적으로 비활성화되어 있습니다. 사용하려면 다음을 수행.

1. /etc/gitlab/gitlab.rb에서 활성화

   gitlab_pages['access_control'] = true
   

2. GitLab을 재구성.

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

모든 Pages 웹 사이트에 대한 공개 액세스 비활성화

GitLab 12.7에 도입 되었습니다.

GitLab 인스턴스에서 호스팅되는 모든 GitLab Pages 웹 사이트에 대해 액세스 제어 를 시행 할 수 있습니다. 
이렇게하면 로그인 한 사용자 만 액세스 할 수 있습니다. 이 설정은 개별 프로젝트에서 사용자가 설정 한 액세스 제어를 대체합니다.

이는 Pages 웹 사이트와 함께 게시 된 정보를 인스턴스 사용자에게만 보존하는 데 유용 할 수 있습니다. 하기 위해서:

1. 인스턴스의 Admin Area > Settings > Preferences으로 이동하여 Pages 설정에서 Disable public access to Pages sites 체크.

2. Save changes을 클릭.

프록시 뒤에서 실행

다른 GitLab과 마찬가지로 Pages는 외부 인터넷 연결이 프록시에 의해 제어되는 환경에서 사용될 수 있습니다. GitLab 페이지에 프록시를 사용하려면 :

1.  /etc/gitlab/gitlab.rb 구성 

   gitlab_pages['http_proxy'] = 'http://example:8080'

2. GitLab을 재구성.

사용자 지정 인증 기관 (CA) 사용

사용자 정의 CA에서 발행 한 인증서를 사용할 때 사용자 정의 CA가 인식되지 않으면 Access Control 및 HTML 작업 아티팩트의 Online View가 작동하지 않습니다.

소스에서 설치하는 경우 시스템 인증 저장소에 사용자 정의 인증 기관 (CA)을 설치하여이 문제를 해결할 수 있습니다.

Omnibus의 경우 일반적으로 Omnibus GitLab에 사용자 지정 CA를 설치하면 이 문제가 해결 되지만 버그 로 인해 해당 방법이 작동하지 않습니다. 다음 해결 방법을 사용하십시오.

1. GitLab 서버 TLS / SSL 인증서/opt/gitlab/embedded/ssl/certs/cacert.pem에 GitLab 애플리케이션 URLgitlab-domain-example.com 추가.

   printf "\ngitlab-domain-example.com\n===========================\n" | sudo tee --append /opt/gitlab/embedded/ssl/certs/cacert.pem
   echo -n | openssl s_client -connect gitlab-domain-example.com:443  | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee --append /opt/gitlab/embedded/ssl/certs/cacert.pem
   

2. GitLab Pages 데몬을 다시 시작. Omnibus GitLab 인스턴스의 경우 :

   sudo gitlab-ctl restart gitlab-pages

데몬에 대한 자세한 로깅 활성화

자세한 로깅은 Omnibus GitLab 11.1에서 도입 되었습니다.

아래 단계에 따라 GitLab Pages 데몬의 자세한 로깅을 구성하십시오.

1. 기본적으로 디먼은 INFO레벨 로만 로그 합니다. 레벨로 이벤트를 로그하게 DEBUG하려면/etc/gitlab/gitlab.rb에 다음을 구성해야합니다.

   gitlab_pages['log_verbose'] = true
   

2. GitLab을 재구성.

저장 경로 변경

아래 단계에 따라 GitLab Pages의 내용이 저장되는 기본 경로를 변경하십시오.

1. 페이지는 기본적으로 /var/opt/gitlab/gitlab-rails/shared/pages에 저장되며 다른 위치에 저장하려면 /etc/gitlab/gitlab.rb에 설정해야합니다.

   gitlab_rails['pages_path'] = "/mnt/storage/pages"
   

2. GitLab을 재구성.

리버스 프록시 요청에 대한 리스너 구성

Omnibus GitLab 11.1에 도입 되었습니다.

아래 단계에 따라 GitLab Pages의 프록시 리스너를 구성합니다.

1. 기본적으로 리스너는 localhost:8090의 요청을 청취하도록 구성되어 있습니다.

   비활성화하려면 다음을 구성해야합니다 /etc/gitlab/gitlab.rb.

   gitlab_pages['listen_proxy'] = nil
   

   다른 포트에서 수신 대기하려면 다음에서 구성해야합니다 /etc/gitlab/gitlab.rb.

   gitlab_pages['listen_proxy'] = "localhost:10080"
   

2. GitLab을 재구성.

최대 페이지 크기 설정

Admin Area > Settings > Preferences > Pages의 Maximum size of pages (MB)에서 프로젝트 당 압축 해제 된 아카이브의 최대 크기를 구성 할 수 있습니다. (기본값은 100MB)

별도의 서버에서 GitLab 페이지 실행

주 응용 프로그램 서버의 부하를 줄이기 위해 별도의 서버에서 GitLab Pages 데몬을 실행할 수 있습니다.

별도의 서버에서 GitLab 페이지를 구성하려면 :

1. 페이지 활성화하려면  /etc/gitlab/gitlab.rb에 다음을 추가.

   gitlab_pages['enable'] = true
   

2. 선택적으로 액세스 제어 를 사용 하려면 /etc/gitlab/gitlab.rb에 다음을 추가.

   gitlab_pages['access_control'] = true
   

3. 변경 사항을 적용 하려면 GitLab 서버를 재구성하고 gitlab-secrets.json파일은 이제 새로운 구성으로 업데이트됩니다.

4. GitLab 서버 에서 비밀 파일의 백업을 만듭니다.

   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak
   

5. 새 서버를 설정합니다. 이 서버는 Pages 서버가 됩니다.

6. 만들기 NFS 공유 새 서버 및 메인에서 액세스 할 수 있도록이 공유를 구성 GitLab 서버를 . 이 예에서는 기본 GitLab Pages 폴더 /var/opt/gitlab/gitlab-rails/shared/pages 를 새 서버의 공유 폴더로 /mnt/pages 사용하고 GitLab 서버 에 마운트 합니다 .

7. 옴니버스 GitLab를 설치하고 /etc/gitlab/gitlab.rb을 수정

   external_url 'http://<ip-address-of-the-server>'
   pages_external_url "http://<your-pages-server-URL>"
   postgresql['enable'] = false
   redis['enable'] = false
   prometheus['enable'] = false
   puma['enable'] = false
   sidekiq['enable'] = false
   gitlab_workhorse['enable'] = false
   gitaly['enable'] = false
   alertmanager['enable'] = false
   node_exporter['enable'] = false
   gitlab_rails['auto_migrate'] = false
   

8. Pages 서버에서 비밀 파일의 백업을 작성

   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak
   

9. /etc/gitlab/gitlab-secrets.json파일을 GitLab 서버 에서 Pages 서버로 복사.

10. 변경 사항이 적용되도록 GitLab 을 재구성.

11.  /etc/gitlab/gitlab.rb을 수정

    gitlab_pages['enable'] = false
    pages_external_url "http://<your-pages-server-URL>"
    gitlab_rails['pages_path'] = "/mnt/pages"
    

12. 변경 사항이 적용되도록 GitLab 을 재구성.