GitLab Pagesのセルフコンパイルインストール管理

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

GitLab Pagesを有効にする前に、GitLabを正常にインストールしたことを確認してください。

このドキュメントでは、セルフコンパイルインストールのGitLab Pagesを設定する方法を説明します。

Linuxパッケージインストール (推奨) のGitLab Pages設定に関する詳細については、Linuxパッケージのドキュメントを参照してください。Linuxパッケージインストールには、サポートされている最新のGitLab Pagesのバージョンが含まれています。

GitLab Pagesの仕組み

GitLab Pagesは、外部IPアドレスをリッスンし、カスタムドメインと証明書をサポートする軽量HTTPサーバーであるGitLab Pagesデーモンを使用します。SNIを介した動的証明書をサポートし、デフォルトでHTTP2を使用してページを公開します。詳細については、Readmeを参照してください。

カスタムドメインの場合、Pagesデーモンは80または443ポートをリッスンする必要があります。これはワイルドカードドメインには適用されません。次のいずれかの方法で設定できます:

GitLabと同じサーバー上のセカンダリIPでリッスンします。
別のサーバー上。Pagesパスもそのサーバーに存在する必要があるため、ネットワーク経由で共有する必要があります。
GitLabと同じサーバーで、同じIPでも異なるポートでリッスンします。この場合、ロードバランサーによるトラフィックのプロキシ処理が必要になります。HTTPSの場合は、TCP負荷分散を使用します。TLS終端 (HTTPSロードバランシング) を使用する場合、ユーザーが提供する証明書でページを提供することはできません。HTTPの場合、HTTPまたはTCP負荷分散のいずれも許容されます。

以下のセクションでは、最初のオプションを前提としています。カスタムドメインをサポートしていない場合、セカンダリIPは必要ありません。

前提条件

Pagesの設定に進む前に、以下を確認してください:

GitLab Pagesを提供する別のドメインを持っていること。このドキュメントでは、このドメインはexample.ioです。
そのドメイン用にwildcard DNS recordを設定していること。
GitLabがインストールされているのと同じサーバーにzipとunzipパッケージをインストールしていること。パッケージは、Pagesアーティファクトを圧縮および解凍するために必要です。
オプション。HTTPSでPagesを提供する場合、Pagesドメイン (*.example.io) 用のwildcard certificateがあること。(オプション)
オプション（推奨）: オプションですが推奨。インスタンスRunnerを設定して有効にしているため、ユーザーは自分で用意する必要がありません。

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はいくつかの方法で設定できます。以下のオプションは、最もシンプルな設定から最も高度な設定まで順に示されています。すべての設定における最小要件は、ワイルドカードDNSレコードです。

ワイルドカードドメイン

各サイトは独自のサブドメインを取得します (例: <namespace>.example.io/<project_slug>)。このサブドメインにはワイルドカードDNSレコード (*.example.io) が必要であり、ほとんどのインスタンスに推奨される設定です。

前提条件:

ワイルドカードDNSの設定

この設定は、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
  # The location where 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に追加します。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

You can use an `http` address when running GitLab Pages and GitLab on the same host. If you use
`https` with a self-signed certificate, make your custom CA available to GitLab Pages, for
example by setting the `SSL_CERT_DIR` environment variable.

シークレット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はすべてのリクエストをデーモンにプロキシします。Pagesデーモンはパブリックインターネットをリッスンしません。

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で、portを443に、httpsをtrueに設定します:

## GitLab Pages
pages:
  enabled: true
  # The location where pages are stored (default: 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

この設定では、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
  # The location where pages are stored (default: 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と一致する必要があります。
- -listen-httpsはexternal_httpsと一致する必要があります。
```
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を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

この設定では、Pagesデーモンが実行され、NGINXがこれにリクエストをプロキシしますが、デーモンはパブリックインターネットからのリクエストも受信できます。カスタムドメインとTLSをサポートしています。

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とexternal_httpsをPagesデーモンがリッスンするセカンダリIPに設定します:

## GitLab Pages
pages:
  enabled: true
  # The location where pages are stored (default: 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にリダイレクトされ、そのトークンはCookieに保持されます。Cookieはシークレットキーで署名されているため、改ざんを検出できます。

プライベートサイトのリソースを表示する各リクエストは、そのトークンを使用してPagesによって認証されます。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=<OAuth Application ID generated by GitLab>
  auth-client-secret=<OAuth code generated by GitLab>
  auth-redirect-uri='http://projects.example.io/auth'
  auth-secret=<40 random hex characters>
  auth-server=<URL of the GitLab instance>

ユーザーは、プロジェクト設定でこれを設定できるようになりました。

ストレージパスを変更する

GitLab Pagesのコンテンツが保存されるデフォルトパスを変更するには:

ページはデフォルトで/home/git/gitlab/shared/pagesに保存されます。別の場所を使用するには、pagesセクションの下にあるgitlab.ymlを編集します:
```
pages:
  enabled: true
  # The location where pages are stored (default: shared/pages).
  path: /mnt/storage/pages
```
GitLabを再起動します。

最大Pagesサイズを設定

プロジェクトごとの解凍されたアーカイブのデフォルトの最大サイズは100 MBです。

前提条件:

管理者アクセス権が必要です。

この値を変更するには:

右上隅で、管理者を選択します。
設定 > 設定を選択します。
Pagesを展開します。
**Maximum size of pages (MB)**の値を更新します。

バックアップ

Pagesは通常のバックアップの一部であるため、設定することはありません。

セキュリティ

クロスサイトスクリプティング攻撃を防ぐために、GitLab PagesをGitLabとは異なるホスト名で実行することを強くおすすめします。