セルフコンパイルインストールのGitLab Pages管理
このドキュメントでは、セルフコンパイルしたGitLabインストール用のGitLab Pagesの設定方法を説明します。
Linuxパッケージインストール用のGitLab Pagesの設定（推奨）については、Linuxパッケージのドキュメントを参照してください。
Linuxパッケージインストールを使う利点は、サポートされている最新バージョンのGitLab Pagesが含まれていることです。
GitLab Pagesの仕組み
GitLab PagesはGitLab Pagesデーモンを利用します。GitLab Pagesデーモンは外部IPアドレスでリッスンし、カスタムドメインと証明書をサポートする軽量なHTTPサーバです。SNI を通して動的な証明書をサポートし、デフォルトでは HTTP2 を使ってページを公開します。どのように動作するかを完全に理解するために、READMEを読むことをお勧めします。
カスタムドメイン(ワイルドカードドメインではない)の場合、Pagesデーモンはポート80 および/または443 をリッスンする必要があります。そのため、設定方法には柔軟性があります：
- GitLabと同じサーバーでPagesデーモンを実行し、セカンダリIPで待ち受けます。
- Pagesデーモンを別のサーバーで実行します。その場合、PagesデーモンがインストールされているサーバーにもPagesパスが存在しなければならないので、ネットワークを通して共有する必要があります。
- GitLabと同じサーバーでPagesデーモンを実行し、同じIPでリッスンしますが、ポートは異なります。この場合、ロードバランサーを使ってトラフィックをプロキシする必要があります。そのルートを選択する場合は、HTTPS用にTCPロードバランシングを使うべきです。TLS終端(HTTPSロードバランシング)を使うと、ユーザー提供の証明書ではPagesを提供できません。HTTPの場合は、HTTPまたはTCPロードバランシングを使うことができます。
この文書では、最初のオプションを想定して話を進めます。カスタムドメインをサポートしていない場合、セカンダリIPは必要ありません。
前提条件
Pagesの設定を進める前に、以下を確認してください：
- GitLab Pages を提供する別のドメインがあること。このドキュメントでは、
example.ioを想定しています。 - そのドメインに対してワイルドカード DNS レコードを設定します。
- GitLabがインストールされている同じサーバーに、
zipとunzipパッケージをインストールしました。これは、Pagesアーティファクトの圧縮と解凍に必要だからです。 - オプションです。Pages (
*.example.io) を HTTPS で提供する場合は、Pages ドメイン用のワイルドカード証明書を用意してください。 - オプションですが、推奨します。共有ランナーを設定し、有効にしているため、ユーザーは自分のランナーを持参する必要がありません。
DNS設定
GitLab Pagesは独自のバーチャルホストで動作することを想定しています。DNSサーバー/プロバイダーで、ワイルドカードDNSA レコード をGitLabが実行されるホストを指すように追加する必要があります。例えば、エントリーは次のようになります：
*.example.io. 1800 IN A 192.0.2.1
example.io はGitLab Pagesを提供するドメインで、192.0.2.1 はGitLabインスタンスのIPアドレスです。
設定
必要に応じて、GitLab Pagesを4つの異なる方法で設定することができます。最も簡単な設定から最も高度な設定まで、以下のオプションを示します。ワイルドカード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に、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.comGitLab 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デーモンを有効にします：
-
システムが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-pagesNGINX設定ファイルをコピーします：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 # 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-sslNGINX設定ファイルをコピーします：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をカスタムドメインで使えるように設定するオプションもあります。ここでも2つのオプションがあります: TLS証明書ありのカスタムドメインと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 # 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と一致する必要があります：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-sslNGINX設定ファイルをコピーします：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.1GitLabがリッスンするプライマリIPに置き換えます。 - NGINXを再起動します。
- GitLab を再起動します。
TLSをサポートするカスタムドメイン
要件
- ワイルドカードDNSの設定
- ワイルドカードTLS証明書
- セカンダリIP
URLスキーム：https://<namespace>.example.io/<project_slug> およびhttps://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と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を編集し、pages デーモンを有効にするために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-sslNGINX設定ファイルをコピーします：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.1GitLabがリッスンするプライマリ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デーモンをOAuthアプリケーションとしてGitLabに登録することで機能します。認証されていないユーザーから非公開 Pages サイトへのアクセス要求があると、Pages デーモンはそのユーザーを GitLab にリダイレクトします。認証に成功すると、ユーザーはトークンを受け取ってPagesにリダイレクトされ、トークンはクッキーに保存されます。クッキーは秘密鍵で署名されているので、改ざんを検知することができます。
非公開サイトのリソースを閲覧する各リクエストは、トークンを使ってPagesによって認証されます。受け取ったリクエストごとに GitLab API にリクエストを行い、ユーザーがそのサイトを読む権限があるかどうかを確認します。
GitLab 12.8以降では、Pagesのアクセスコントロールパラメータは設定ファイルに設定されます。設定ファイルの名前はgitlab-pages-config です。設定ファイルは-config flag またはCONFIG 環境変数を使って Pages に渡されます。
Pagesのアクセスコントロールはデフォルトでは無効になっています。有効にするには
-
config/gitlab.ymlファイルを修正してください：pages: access_control: true - GitLab を再起動します。
- 新しいOAuth アプリケーションを作成します。これは
GitLab Pagesという名前で、https://projects.example.io/authというRedirect URLを持ちます。”trusted” アプリケーションである必要はありませんが、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のコンテンツが保存されるデフォルトパスを変更するには、以下の手順に従ってください。
-
Pagesはデフォルトで
/home/git/gitlab/shared/pagesに保存されます。もし別の場所に保存したい場合は、gitlab.ymlのpagesセクションで設定してください：pages: enabled: true # The location where pages are stored (default: shared/pages). path: /mnt/storage/pages -
GitLab を再起動します。
最大Pagesサイズの設定
プロジェクトごとに解凍されるアーカイブの最大サイズのデフォルトは 100 MB です。
この値を変更するには
- 左のサイドバーで、Search を選択するか、次のページに進んでください。
- Admin Areaを選択します。
- 左側のサイドバーで、[設定] > [環境設定]を選択します。
- ページを展開します。
- ページの最大サイズ(MB) の値を更新します。
バックアップ
Pagesは通常のバックアップの一部なので、設定する必要はありません。
セキュリティ
XSS攻撃を防ぐために、GitLab PagesをGitLabとは異なるホスト名で実行することを強く考慮する必要があります。