GitLab Pages 작동 방식
사전 요구 사항
- DNS 구성
구성
- 와일드카드 도메인
- TLS 지원하는 와일드카드 도메인
고급 구성
- 사용자 정의 도메인
- TLS 지원을 포함한 사용자 정의 도메인
NGINX 주의 사항
액세스 제어
저장소 경로 변경
최대 페이지 크기 설정
백업
보안

GitLab Pages 자체 컴파일 설치 관리

Tier: Free, Premium, Ultimate Offering: Self-Managed

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

이 문서는 자체 컴파일된 GitLab 설치를 위한 GitLab Pages 구성 방법에 대해 설명합니다.

Linux 패키지 설치를 위한 GitLab Pages 구성에 대한 자세한 내용은 Linux package 문서를 참조하십시오.

Linux 패키지 설치를 사용하는 장점은 GitLab Pages의 최신 지원 버전이 포함되어 있다는 것입니다.

GitLab Pages 작동 방식

GitLab Pages는 외부 IP 주소에서 수신 대기하는 가벼운 HTTP 서버 인 GitLab Pages 데몬을 활용하여 사용자 정의 도메인 및 인증서를 지원합니다. SNI를 통해 동적 인증서를 지원하며 기본적으로 HTTP2를 사용하여 페이지를 노출합니다. 작동 방식을 완전히 이해하려면 README를 참조하는 것이 좋습니다.

사용자 정의 도메인의 경우(하지만 와일드카드 도메인은 해당하지 않음), Pages 데몬은 80 및/또는 443 포트에서 수신 대기해야 합니다. 이러한 이유로 설정 방법에는 몇 가지 유연성이 있습니다.

Pages 데몬을 GitLab과 동일한 서버에서 실행하여 보조 IP에서 수신 대기
Pages 데몬을 별도의 서버에서 실행합니다. 이 경우 Pages 데몬이 설치된 서버에 Pages 경로도 있어야 하므로 네트워크를 통해 공유해야 합니다.
Pages 데몬을 GitLab과 동일한 서버에서 동일한 IP에서 실행하되 다른 포트에서 수신 대기합니다. 이 경우 트래픽을 로드 밸런서로 프록시해야 합니다. 이 경로를 선택한 경우 HTTPS에 대해 TCP 로드 밸런싱을 사용해야 합니다. TLS 종료(HTTPS 로드 밸런싱)를 사용하면 사용자가 제공한 인증서로 페이지를 제공할 수 없습니다. HTTP의 경우 HTTP 또는 TCP 로드 밸런싱을 사용할 수 있습니다.

이 문서에서는 첫 번째 옵션을 가정하고 진행합니다. 사용자 정의 도메인을 지원하지 않는 경우 보조 IP가 필요하지 않습니다.

사전 요구 사항

Pages 구성을 진행하기 전에 다음 사항을 확인하십시오.

GitLab Pages를 제공할 별도의 도메인이 있는지 확인합니다. 이 문서에서는 example.io로 가정합니다.
해당 도메인을 위해 와일드카드 DNS 레코드를 구성했는지 확인합니다.
GitLab이 설치된 서버에 zip 및 unzip 패키지가 설치되어 있는지 확인합니다. 이 패키지들은 Pages artifacts를 압축하고 압축 해제하는 데 필요합니다.
선택 사항입니다. HTTPS로 Pages(*.example.io)를 제공하기로 결정한 경우 Pages 도메인에 대한 와일드카드 인증서가 있는지 확인합니다.
선택 사항이지만 권장됩니다. 사용자가 자체 인스턴스를 가져오지 않아도 되도록 인스턴스 러너를 구성하고 활성화했는지 확인합니다.

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를 4가지 다른 방법으로 설정할 수 있습니다. 다음 옵션은 가장 쉬운 설정부터 가장 고급 설정까지 순서대로 나열되어 있습니다. 모든 구성에서 필요한 최소한의 요구 사항은 와일드카드 DNS 설정입니다.

와일드카드 도메인

요구 사항:

와일드카드 DNS 설정

URL 구조: http://<namespace>.example.io/<project_slug>

이 설정은 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
  # pages가 저장되는 위치 (기본: 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에 추가하고, GitLab Pages를 제공할 FQDN으로 example.io를 변경하고 GitLab 인스턴스의 URL을 gitlab.example.com로 바꿔주십시오.
```
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를 사용하고 자체 서명된 인증서를 사용하는 경우에는 사용자 지정 CA를 GitLab Pages에서 사용할 수 있도록 해야 합니다. 예를 들어, SSL_CERT_DIR 환경 변수를 설정하여 이를 수행할 수 있습니다.

비밀 API 키를 추가합니다.

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

페이지 데몬을 활성화합니다.
- 시스템이 init으로 systemd를 사용하는 경우 다음을 실행합니다.
```
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는 모든 요청을 데몬으로 프록시합니다. 페이지 데몬은 외부 세계에서 수신 대기하지 않습니다.

페이지 데몬 설치:

 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에서 포트를 443으로, https를 true로 설정:

 ## GitLab Pages
 pages:
   enabled: true
   # 페이지가 저장되는 위치(기본값: 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 재시작.

고급 구성

와일드카드 도메인 외에도 GitLab Pages를 사용자 정의 도메인과 함께 구성할 수 있습니다. 다시 말하지만, 여기에는 두 가지 옵션이 있습니다: TLS 인증서 있는 사용자 정의 도메인과 없는 사용자 정의 도메인을 지원합니다. 가장 쉬운 설정은 TLS 인증서가 없는 설정입니다.

사용자 정의 도메인

요구 사항:

와일드카드 DNS 설정
보조 IP

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

이 경우 페이지 데몬이 실행 중입니다. NGINX는 여전히 데몬으로 요청을 프록시하지만, 데몬은 외부에서도 요청을 수신할 수 있습니다. 사용자 정의 도메인은 지원되지만 TLS는 지원되지 않습니다.

페이지 데몬 설치:

 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는 데몬이 연결을 수신하는 보조 IP로 설정해야 합니다:

 pages:
   enabled: true
   # 페이지가 저장되는 위치(기본값: 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와 일치해야 합니다:
```
 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-ssl 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 scheme: https://<namespace>.example.io/<project_slug> 및 https://custom-domain.com

이 경우, 페이지 데몬이 실행 중입니다. NGINX는 여전히 요청을 데몬에 프록시하지만, 데몬도 외부에서 요청을 수신할 수 있습니다. 사용자 정의 도메인 및 TLS가 지원됩니다.

페이지 데몬 설치:

 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 페이지를 제공할 FQDN으로 변경해야 합니다. external_http와 external_https를 데몬이 연결을 수신하는 보조 IP로 설정해야 합니다:

 ## GitLab Pages
 pages:
   enabled: true
   # 페이지가 저장되는 위치 (기본값: 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을 GitLab이 수신 대기하는 주 IP인 192.0.2.1로 변경하세요.
NGINX를 다시 시작하세요.
GitLab을 다시 시작하세요.

NGINX 주의 사항

참고: 다음 정보는 자체 컴파일된 설치에만 적용됩니다.

NGINX 구성에서 도메인 이름을 설정할 때 특히 주의해야 합니다. 백슬래시를 제거해서는 안 됩니다.

GitLab 페이지 도메인이 example.io인 경우 다음을 대체하세요:

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

다음과 같이 대체하세요:

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

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

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

액세스 제어

GitLab 페이지 액세스 제어는 프로젝트별로 구성할 수 있습니다. 페이지 사이트에 대한 액세스는 사용자의 프로젝트 멤버십에 따라 제어될 수 있습니다.

액세스 제어는 페이지 데몬을 GitLab의 OAuth 애플리케이션으로 등록함으로써 작동합니다. 인증되지 않은 사용자가 비공개 페이지 사이트에 액세스하는 요청을 보내면 페이지 데몬이 사용자를 GitLab으로 리디렉션합니다. 인증이 성공하면 사용자는 토큰이 포함된 쿠키로 페이지로 리디렉션됩니다. 쿠키는 비밀 키로 서명되므로 변조를 감지할 수 있습니다.

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

GitLab 12.8부터 페이지의 액세스 제어 매개변수는 gitlab-pages-config라는 이름으로 약속되는 구성 파일에 설정됩니다. 구성 파일은 -config 플래그 또는 CONFIG 환경 변수를 사용하여 페이지에 전달됩니다.

페이지 액세스 제어는 기본적으로 비활성화되어 있습니다. 활성화하려면:

config/gitlab.yml 파일을 수정하세요:
```
 pages:
   access_control: true
```
GitLab을 다시 시작하세요.
새로운 시스템 OAuth 애플리케이션을 생성하세요. 이 애플리케이션은 GitLab Pages로 지정되어야 하며 Redirect URL은 https://projects.example.io/auth여야 합니다. “신뢰할 수 있는” 애플리케이션이 필요하지는 않지만 api 스코프가 필요합니다.

다음과 같은 구성 파일을 전달하여 페이지 데몬을 시작하세요:

   auth-client-id=<GitLab에서 생성한 OAuth 애플리케이션 ID>
   auth-client-secret=<GitLab에서 생성한 OAuth 코드>
   auth-redirect-uri='http://projects.example.io/auth'
   auth-secret=<40자의 랜덤 16진수 문자>
   auth-server=<GitLab 인스턴스의 URL>

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

저장소 경로 변경

기본적으로 GitLab Pages 콘텐츠는 다음 경로에 저장됩니다.

페이지는 기본적으로 /home/git/gitlab/shared/pages에 저장됩니다. 다른 위치에 저장하려면 gitlab.yml의 pages 섹션에서 설정해야 합니다.
```
pages:
  enabled: true
  # 페이지가 저장되는 위치 (기본값: shared/pages).
  path: /mnt/storage/pages
```
GitLab 재시작.

최대 페이지 크기 설정

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

이 값을 변경하려면:

왼쪽 사이드바에서 맨 아래 관리 영역을 선택합니다.
설정 > 기본 설정을 선택합니다.
Pages를 확장합니다.
페이지의 최대 크기 (MB) 값을 업데이트합니다.

백업

Pages는 정기 백업의 일부이므로 별도의 구성이 필요하지 않습니다.

보안

XSS 공격을 방지하기 위해 GitLab Pages를 GitLab과 다른 호스트 이름으로 실행하는 것이 좋습니다.

GitLab Pages 자체 컴파일 설치 관리

GitLab Pages 작동 방식

사전 요구 사항

DNS 구성

구성

와일드카드 도메인

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

고급 구성

사용자 정의 도메인

TLS 지원을 포함한 사용자 정의 도메인

NGINX 주의 사항

액세스 제어

저장소 경로 변경

최대 페이지 크기 설정

백업

보안

도움말

기능 사용 가능성과 제품 평가판

도움받기