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 패키지 설명서를 참조하세요.

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

GitLab Pages 작동 방식

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

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

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

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

사전 요구 사항

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

GitLab Pages를 제공하기 위한 별도의 도메인이 있는지 확인하세요. 이 문서에서는 example.io로 가정합니다.
해당 도메인을 위해 와일드카드 DNS 레코드를 구성했는지 확인하세요.
GitLab이 설치된 동일한 서버에 zip 및 unzip 패키지를 설치했는지 확인하세요. Pages 아티팩트를 압축하고 해제하는 데 필요합니다.
선택 사항. Pages (*.example.io)를 HTTPS로 제공하기로 결정하는 경우, 페이지 도메인에 대한 와일드카드 인증서를 보유하고 구성했는지 확인하세요.
선택 사항이지만 권장됩니다. 인스턴스 러너를 구성하고 활성화했는지 확인하세요. 이렇게 하면 사용자가 직접 가져올 필요가 없습니다.

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로 설정하고 GitLab Pages를 제공할 FQDN을 나타내도록 host를 설정하세요:

## 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 Pages를 실행할 서버의 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를 사용하고 자체 서명된 인증서를 사용하는 경우 GitLab Pages에서 사용자 정의 CA를 사용할 수 있도록 환경 변수를 설정하세요.

비밀 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 인증서가없는 사용자 정의 도메인을 지원하는 것이 가장 쉬운 설정입니다.

사용자 정의 도메인

요구 사항:

와일드카드 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-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 스키마: 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을 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 접근 제어는 프로젝트별로 구성할 수 있습니다. 페이지 사이트에 대한 액세스는 해당 프로젝트의 멤버십에 기반하여 제어할 수 있습니다.

액세스 제어는 페이지 데몬을 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여야 합니다. 이는 “trusted” 애플리케이션일 필요는 없지만 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에 저장됩니다. 다른 위치에 저장하려면 pages 섹션 아래에 gitlab.yml에서 설정해야 합니다.
```
pages:
  enabled: true
  # 페이지가 저장되는 위치 (기본값: shared/pages).
  path: /mnt/storage/pages
```
GitLab을 다시 시작합니다.

페이지 최대 크기 설정

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

이 값을 변경하려면 다음을 수행하십시오:

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

백업

페이지는 정기 백업의 일부이므로 구성할 것이 없습니다.

보안

XSS 공격을 방지하기 위해 GitLab Pages를 GitLab과는 다른 호스트 이름으로 실행하는 것을 강력히 고려해야 합니다.

자체 컴파일 설치를 위한 GitLab Pages 관리

GitLab Pages 작동 방식

사전 요구 사항

DNS 구성

구성

와일드카드 도메인

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

고급 구성

사용자 정의 도메인

TLS 지원과 함께 사용자 정의 도메인

NGINX 주의 사항

접근 제어

저장 경로 변경

페이지 최대 크기 설정

백업

보안

도움말

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

도움받기