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

GitLab Pages self-compiled 설치 관리

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

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

본 문서에서는 자체 컴파일한 GitLab 설치에 대한 GitLab Pages 구성 방법을 설명합니다.

이 정보를 참고하여 Linux 패키지 설치에 대한 GitLab Pages 구성 방법에 대해 자세히 알아보세요(권장됨), Linux package documentation.

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

GitLab Pages 작동 방식

GitLab Pages는 외부 IP 주소에서 수신 대기하는 가벼운 HTTP 서버인 GitLab Pages daemon을 활용하여 사용자 정의 도메인 및 인증서를 지원합니다. SNI을 통해 동적 인증서를 지원하며 기본적으로 HTTP2를 사용하여 페이지를 노출합니다. GitLab Pages가 작동하는 방식을 완전히 이해하려면 해당 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 artifact를 압축하고 해제하는 데 필요합니다.
선택 사항입니다. HTTPS로 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를 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로 설정하고 Pages를 제공할 FQDN을 host로 설정하세요:

## GitLab Pages
pages:
  enabled: true
  # 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에 추가하고, 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

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는 모든 요청을 데몬으로 프록시합니다. 페이지 데몬은 외부 세계에서 수신하지 않습니다.

페이지 데몬 설치:

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 인증서 없는 사용자 정의 도메인 지원. 가장 간단한 설정은 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을 편집합니다. GitLab Pages를 제공할 FQDN에 맞게 host를 변경해야 합니다. 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 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을 GitLab이 수신하는 기본 IP인 192.0.2.1로 바꿉니다.
NGINX 재시작.
GitLab 재시작.

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

사전 작업:

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

URL 구성: 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을 편집합니다. GitLab Pages를 제공할 FQDN에 맞게 host를 변경해야 합니다. 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 Pages 도메인이 example.io이라면 다음과 같이 바꿔주세요:

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

다음으로 대체하세요:

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

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

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

액세스 제어

GitLab Pages 액세스 제어는 프로젝트별로 구성할 수 있습니다. 페이지 사이트에 대한 액세스는 사용자가 해당 프로젝트의 멤버십에 기반하여 제어될 수 있습니다.

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

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

Pages 액세스 제어 매개변수는 gitlab-pages-config라는 규칙에 따라 지정된 구성 파일에 설정됩니다. 구성 파일은 -config 플래그 또는 CONFIG 환경 변수를 사용하여 Pages로 전달됩니다.

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

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

다음과 같은 인수를 사용하여 Pages 데몬을 시작하세요.

 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 self-compiled 설치 관리

GitLab Pages 작동 방식

전제 조건

DNS 구성

구성

와일드카드 도메인

와일드카드 도메인 및 TLS 지원

고급 구성

사용자 정의 도메인

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

NGINX 주의 사항

액세스 제어

저장 경로 변경

최대 페이지 크기 설정

백업

보안

도움말

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

도움받기