GitLab Pages 작동 방식
사전 요구 사항
- DNS 구성
구성
- 와일드카드 도메인
- TLS 지원을 갖춘 와일드카드 도메인
고급 구성
- 사용자 정의 도메인
- TLS 지원 사용자 정의 도메인
NGINX 주의 사항
접근 제어
저장 경로 변경
최대 Pages 크기 설정
백업
보안

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

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

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

이 문서는 자기 컴파일된 GitLab 설치를 위해 GitLab Pages를 구성하는 방법을 설명합니다.

Linux Package 설치에 대한 GitLab Pages 구성 정보는 Linux 패키지 문서를 참조하세요.

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

GitLab Pages 작동 방식

GitLab Pages는 GitLab Pages daemon을 사용합니다. 이는 외부 IP 주소에서 수신 대기하며, 사용자 정의 도메인 및 인증서 지원을 제공하는 가벼운 HTTP 서버입니다. 이는 SNI를 통한 동적 인증서를 지원하며 기본적으로 HTTP2를 사용하여 페이지를 노출합니다.
그 작동 방식을 완전히 이해하기 위해 README를 읽는 것이 좋습니다.

사용자 정의 도메인(그러나 와일드카드 도메인은 제외)인 경우, Pages daemon은 포트 80 및/또는 443에서 수신 대기해야 합니다. 이러한 이유로 설정하는 방법에 약간의 유연성이 있습니다:

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

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

사전 요구 사항

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

GitLab Pages를 제공할 별도의 도메인이 있습니다. 이 문서에서는 이를 example.io로 가정합니다.
해당 도메인에 대해 와일드카드 DNS 레코드가 구성되었습니다.
Pages 아티팩트를 압축 해제하는 데 필요한 zip 및 unzip 패키지가 GitLab이 설치된 동일한 서버에 설치되어 있습니다.
선택 사항. Pages 도메인에 대해 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로 설정하고 GitLab Pages를 제공할 FQDN으로 host를 설정합니다:

## GitLab Pages
pages:
  enabled: true
  # 페이지가 저장되는 위치 (기본값: 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에 추가하고, 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를 사용하고 자체 서명 인증서를 사용하는 경우, GitLab Pages에 사용자 정의 CA를 사용할 수 있도록 해야 합니다. 예를 들어, SSL_CERT_DIR 환경 변수를 설정하여 이를 수행할 수 있습니다.

비밀 API 키 추가:

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

Pages 데몬을 활성화하려면:
- 시스템에서 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는 모든 요청을 데몬으로 프록시합니다. 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.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

이 경우, pages 데몬이 실행 중입니다. NGINX는 여전히 요청을 데몬으로 프록시하지만, 데몬은 외부 세계로부터 요청을 받을 수 있습니다. 사용자 정의 도메인은 지원되지만 TLS는 없습니다.

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.yml을 편집하여 아래 예와 같게 설정합니다. host를 GitLab Pages를 제공할 FQDN으로 변경해야 합니다. external_http를 pages 데몬이 연결을 수신하는 세컨더리 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가 지원됩니다.

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.yml을 아래의 예시처럼 수정하세요. GitLab Pages를 제공할 FQDN으로 host를 변경해야 합니다. external_http 및 external_https는 Pages 데몬이 연결을 수신하는 보조 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 접근 제어는 프로젝트별로 구성할 수 있습니다. Pages 사이트에 대한 접근은 사용자의 프로젝트 멤버십에 따라 제어될 수 있습니다.

접근 제어는 Pages 데몬을 GitLab에 OAuth 애플리케이션으로 등록하여 작동합니다. 인증되지 않은 사용자가 개인 Pages 사이트에 접근할 요청을 할 때마다, Pages 데몬은 사용자를 GitLab로 리디렉션합니다. 인증이 성공하면 사용자는 토큰과 함께 Pages로 다시 리디렉션되며, 이 토큰은 쿠키에 유지됩니다. 쿠키는 비밀 키로 서명되므로 변조가 감지될 수 있습니다.

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

Pages에 대한 접근 제어 매개변수는 기본적으로 gitlab-pages-config라는 이름의 구성 파일에 설정됩니다. 구성 파일은 -config flag 또는 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의 콘텐츠가 저장되는 기본 경로를 변경하려면 아래 단계를 따르세요.

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

최대 Pages 크기 설정

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

이 값을 변경하려면:

왼쪽 사이드바에서 하단에 있는 Admin을 선택합니다.
Settings > Preferences를 선택합니다.
Pages를 확장합니다.
페이지의 최대 크기 (MB)에 대한 값을 업데이트합니다.

백업

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

보안

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

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

GitLab Pages 작동 방식

사전 요구 사항

DNS 구성

구성

와일드카드 도메인

TLS 지원을 갖춘 와일드카드 도메인

고급 구성

사용자 정의 도메인

TLS 지원 사용자 정의 도메인

NGINX 주의 사항

접근 제어

저장 경로 변경

최대 Pages 크기 설정

백업

보안

도움말

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

도움받기