GitLab 페이지 관리 방법 (Self-compiled 설치용)

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

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

이 문서에서는 Self-compiled GitLab 설치용 GitLab Pages를 구성하는 방법을 설명합니다.

Linux 패키지 설치를 사용하면 지원되는 GitLab Pages의 최신 버전이 포함되어 있기 때문에 Linux Package 설치에 대한 자세한 내용은 Linux package documentation를 참조하십시오.

GitLab Pages 동작 방식

GitLab Pages는 GitLab Pages 데몬을 사용하여 칼퇴 브랜치의 변경 사항을 대상 브랜치에 통합하기 위한 제안입니다.외부 IP 주소에서 수신되는 경량 HTTP 서버이며 사용자 정의 도메인 및 인증서를 지원합니다. SNI를 통해 동적 인증서를 지원하며 기본적으로 HTTP2를 사용하여 페이지를 노출합니다. 이 작동 방식을 완전히 이해하려면 README를 참고하는 것이 좋습니다.

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

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

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

사전 요구 사항

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

GitLab Pages를 제공할 별도 도메인이 있어야 합니다. 본 문서에서는 example.io로 가정합니다.
해당 도메인에 대한 와일드카드 DNS 레코드를 구성해야 합니다.
GitLab이 설치된 서버에 zip 및 unzip 패키지가 설치되어 있어야 합니다. 이것은 Pages 아티팩트를 압축 및 해제하는 데 필요합니다.
선택 사항입니다. 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 도메인을 사용하여 사용자 페이지를 제공하면 안됩니다. 자세한 내용은 보안 섹션을 참조하십시오.

구성

귀하의 요구에 따라 4가지 다양한 방법으로 GitLab Pages를 설정할 수 있습니다. 다음 옵션은 가장 간단한 설정에서 가장 고급 설정까지 나열되어 있습니다. 모든 구성에 필요한 최소 요구 사항은 와일드카드 DNS 설정입니다.

와일드카드 도메인

사전 요구 사항:

와일드카드 DNS 설치

URL scheme: 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 인스턴스의 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

페이지 데몬 활성화:
- 시스템이 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 scheme: 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
  # pages가 저장되는 위치 (기본값: 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를 변경해야 합니다. 연결을 위해 페이지 데몬이 수신 대기하는 보조 IP에 external_http를 설정해야 합니다:

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를 변경해야 합니다. 연결을 위해 페이지 데몬이 수신 대기하는 보조 IP에 external_http 및 external_https를 설정해야 합니다:

## 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

gitlab_pages_enabled를 true로 설정하여 페이지 데몬을 활성화하도록 /etc/default/gitlab을 수정합니다. 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-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입니다.

이 값을 변경하려면:

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

백업

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

보안

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

On this page

GitLab 페이지 관리 방법 (Self-compiled 설치용)

GitLab Pages 동작 방식

사전 요구 사항

DNS 구성

구성

와일드카드 도메인

TLS 지원이 포함된 와일드카드 도메인

고급 구성

사용자 정의 도메인

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

NGINX 주의사항

액세스 제어

리포지터리 경로 변경

최대 페이지 크기 설정

백업

보안

도움말

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

도움받기

On this page