皆様こんにちは。SEの小池と申します。
GitLabには静的WebサイトをGitLabのリポジトリから直接公開する GitLab Pages という機能があります。
この機能はSaaS版とオンプレ版の両方で利用でき、且つ、全てのティアで (無償版でも) 利用可能という、結構大盤振る舞いな機能です。
今回はDocker Composeで起動したGitLabでGitLab Pagesを簡単に試す方法をご紹介いたします。
- 本記事の対象の方
- 今回のブログのゴール
- このブログをお読みいただくにあたっての事前ご連絡事項
- 筆者の検証環境
- GitLab公式の説明動画
- グループタイプのGitLab PagesのURL
- 事前準備
- Step1. Docker Composeのymlファイルを編集
- Step2. GitLab Pagesの有効化確認
- Step3. Pages用のグループ (Top-level) を作成
- Step4. テンプレートを使ってプロジェクトを作成
- Step5. CI/CDパイプラインを実行
- Step.6 公開された静的Webページの確認
- 最後に
本記事の対象の方
- Docker Composeを使ってコンテナで起動したGitLabで、GitLab Pagesを試したい方。
今回のブログのゴール
このブログのゴールはこちらです。
- Docker Composeで起動したGitLabで、GitLab Pagesを使って静的Webサイトをデプロイする。
このブログをお読みいただくにあたっての事前ご連絡事項
- 本記事は後述する筆者のローカル検証用GitLab (15.3.1-ee) にてGitLab Pagesを使って静的Webサイトを公開するまでの経緯を記載しております。当方の検証環境とは異なる環境構成、エディション 及び バージョンではこの記事に記載の通りではない可能性がございます。
- 本記事ではSaaS版のGitLab (GitLab.com) におけるGitLab Pagesの試し方については言及しておりません。SaaS版のGitLabでGitLab Pagesをお試しになりたい方は、GitLab社のこちらのブログをご参照ください。
- 本記事ではGitLab Pagesの機能説明は記載しておりません。GitLab Pagesの機能説明はGitLab Docs (こちら) をご参照ください。
- 本記事のGitLabのGUIは日本語にローカライズした状態で掲載しております。それ以外の言語をご利用の方は適宜読み替えてください。
- 本記事では、GitLabに内包されているGitLab Pagesのプロジェクトテンプレートを利用します。テンプレートはGitLabのバージョンによって内容が異なる可能性があります。
筆者の検証環境
本記事を書くにあたり、当方がGitLab Pagesを試行した環境は以下の通りです。
- DockerホストはUbuntu 20.04.4 LTS。
- Docker Compose v2.6.0を使ってGitLab 15.3.1-eeを起動している。
- GitLabで使用しているドメインは
gitlabmain.example.com。 - 以下のディレクトリをハードマウントしている。
- Dockerホスト側 :
/srv/gitlab/config-> GitLabコンテナ :/etc/gitlab - Dockerホスト側 :
/srv/gitlab/logs-> GitLabコンテナ :/var/log/gitlab - Dockerホスト側 :
/srv/gitlab/data-> GitLabコンテナ :/var/opt/gitlab
- Dockerホスト側 :
- Runnerは2つ。
- 1つ目：共用Runner。コンテナ。エクゼキューターが
docker。 - 1つ目：共用Runner。コンテナ。エクゼキューターが
shell。
- 1つ目：共用Runner。コンテナ。エクゼキューターが
- プライベートCA利用。
GitLab公式の説明動画
Docker ComposeでGitLabを起動している環境におけるGitLab Pagesの使い方に関する動画が、GitLab社から公開されています。
筆者はこの動画のおかげでGitLab Pagesを試すことができたと言っても過言ではありません・・・。
Docker Composeのymlファイルと、GitLabの設定ファイルであるgitlab.rbの中身を見せてくれます。
もし、Docker Composeを用いてGitLabを起動している環境において、GitLab Pagesで静的Webページをうまく公開できない場合は、この動画を見ながら各種設定ファイルの内容を見直してみると良いと存じます。
なお、この動画はアクセスコントロールを有効にしていますが、本記事の後続の手順ではアクセスコントロールは無効のままとしております。
グループタイプのGitLab PagesのURL
実はGitLab Pagesはグループページやユーザーページ等、いくつかのタイプが存在します。
今回のブログではこのうちグループページのタイプのGitLab Pagesを試してみます。
参考 : GitLab Pages domain names, URLs, and base URLs | GitLab
GitLab Pagesをグループページタイプで公開した場合、WebページのURLは以下の通りとなります。
http(s)://＜グループ名＞.＜GitLab Pagesドメイン＞/＜プロジェクト名＞
後に記載する事前準備にて必要な、ワイルドカードDNSレコードの登録 or hostsの編集でこのURLが重要になってまいります。
事前準備
まず、作業前に以下の準備をします。
- 必須 : GitLab Pagesのためのドメインを決める。
- 必須 : ワイルドカード DNS レコードの作成 or hostsの編集。
- 必須 : Runnerを用意する。
- オプション : HTTPSを使いたい場合は、ワイルドカード証明書を用意する。
上記の項目は、前述した筆者の環境において最低限の作業で、且つ、個人的にGitLab Pagesを試すために必要な事項となります。
一般的なGitLab Pages利用に際する事前準備事項についてはGitLab Docsの以下のURLをご参照ください。
参考 : GitLab Pages administration - Prerequisites| GitLab
必須 : GitLab Pagesのためのドメインを決める
GitLab Pagesのためのドメインは、GitLabのドメインとは異なるドメインを使用する必要があります。
GitLabのサブドメインも不可となります。
GitLab Docsにわかりやすい例がいくつか載っているので、そちらをご参照いただきながらGitLab Pagesで使うドメインをご検討ください。
参考 : GitLab Pages administration - Prerequisites| GitLab
筆者の場合、GitLabでgitlabmain.example.comというドメインを使用しているため、GitLab Pagesではpages.example.comというドメインを使うことに致します。
| GitLabのドメイン | GitLab Pagesのドメイン |
|---|---|
| gitlabmain.example.com | pages.example.com |
必須 : ワイルドカード DNS レコードの作成 or hostsの編集
グループタイプのGitLab PagesのURLで紹介いたしました通り、今回の場合GitLab Pagesでデプロイした静的WebページのURLはhttp(s)://＜グループ名＞.＜GitLab Pagesドメイン＞/＜プロジェクト名＞となります。
そのため、任意のクライアントがこのページを閲覧するにあたり、クライアントが利用するDNSにワイルドカードレコードを登録するか、クライアントのローカルのhostsファイルを編集する必要があります。
今回のブログでは筆者のローカル検証環境でGitLab Pagesを使ってみることを目的としているため、クライアントのローカルhostsファイルを編集することで対応致します。
この対応方法はStep3. Pages用のグループ (Top-level) を作成で記載していますので、そのタイミングで実施致します。
もし、DNSサーバーにワイルドカードレコードを作成する場合は、以下のGitLab Docsをご参照ください。
参考 : GitLab Pages administration - DNS configuration | GitLab
必須 : Runnerを用意する
今回のブログでは、GitLabインスタンスに含まれるGitLab Pages用のテンプレートを使います。
このプロジェクトでGitLab Pagesの静的Webページをデプロイするには、CI/CDパイプラインを実行する必要があるため、Runnerが必須となります。
GitLab Docsでは共用 Runner (Shared runner) の用意が推奨されています。
参考 : GitLab Pages administration - Prerequisites | GitLab
なお、当ブログでは以下2つのRnnnerで動作検証し、どちらでも静的Webページをデプロイできることを確認済です。
- 共用 Runner (コンテナで起動。エクゼキューターは
docker) - 共用 Runner (コンテナで起動。エクゼキューターは
shell)
オプション : HTTPSを使いたい場合はサーバー証明書を用意する
オプションとして、GitLab Pagesでhttpsを利用したい場合は、事前準備で決めたGitLab Pagesのドメインのワイルドカード証明書を用意します。
グループタイプのGitLab PagesのURLでご紹介いたしました通り、グループタイプのGitLab PagesのURLは<http(s)://＜グループ名＞.＜GitLab Pagesドメイン＞/＜プロジェクト名＞となります。
このため、GitLab Pagesでhttpsを利用したい場合は、GitLab Pagesで使うドメインのワイルドカード証明書が必要となります。
筆者はGitLabにもhttpsを利用していたので、それにあわせてGitLab Pagesでもワイルドカード証明書を使ってhttpsを実装致しました。
今回のブログではGitLab Pagesのドメインをpages.example.comにするので、発行すべきワイルドカード証明書のCNは*.pages.example.comとなります。
この際発行した証明書が以下の通りです。
この証明書とキーを、GitLabのコンテナから見える場所に置きます。
このブログでは証明書とキーはDockerホスト側の/srv/gitlab/config/ssl/の下に置きました。
筆者の検証環境で述べた通り、Dockerホスト側の/srv/gitlab/config/を、GitLabコンテナの/etc/gitlabにマウントしていますので、証明書とキーのパスは以下の通りとなります。
| ワイルドカード証明書 | キー |
|---|---|
Dockerホスト側のパス：/srv/gitlab/config/ssl/pages.example.com.crtGitLabコンテナから見たパス： /etc/gitlab/ssl/pages.example.com.crt |
Dockerホスト側のパス：/srv/gitlab/config/ssl/pages.example.com.keyGitLabコンテナから見たパス： /etc/gitlab/ssl/pages.example.com.key |
Step1. Docker Composeのymlファイルを編集
GitLabの環境設定を編集して、GitLab Pagesを使える状態にします。
筆者の検証環境はGitLabをDocker Comcposeで起動しているので、Docker Composeのymlファイルを編集していきます。
まず編集前のdocker-compose.ymlがこちらです。
version: '3.6' services: gitlab: image: 'gitlab/gitlab-ee:14.10.4-ee.0' restart: always hostname: 'gitlabmain.example.com' environment: GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlabmain.example.com' gitlab_rails['gitlab_shell_ssh_port'] = 2224 ports: - '80:80' - '443:443' - '2224:22' volumes: - '/srv/gitlab/config:/etc/gitlab' - '/srv/gitlab/logs:/var/log/gitlab' - '/srv/gitlab/data:/var/opt/gitlab' shm_size: '256m' networks: app_net: ipv4_address: 192.168.100.10 networks: app_net: driver: bridge ipam: driver: default config: - subnet: 192.168.100.0/24
まず、事前準備で検討したGitLab Pagesで使うドメインを指定します。
指定するには設定値pages_external_urlを用います。
当方環境のdocker-compose.ymlの場合は、11行目に追記致しました。
version: '3.6' services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlabmain.example.com' environment: GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlabmain.example.com' gitlab_rails['gitlab_shell_ssh_port'] = 2224 pages_external_url 'https://pages.testdom.local' ports: - '80:80' - '443:443' - '2224:22' volumes: - '/srv/gitlab/config:/etc/gitlab' - '/srv/gitlab/logs:/var/log/gitlab' - '/srv/gitlab/data:/var/opt/gitlab' shm_size: '256m' networks: app_net: ipv4_address: 192.168.100.10 networks: app_net: driver: bridge ipam: driver: default config: - subnet: 192.168.100.0/24
次に、GitLab Pagesを利用するに際し最低限の設定値を指定します。
今回の場合、gitlab_pages['enable']、gitlab_pages['listen_proxy']、gitlab_pages['internal_gitlab_server']の3つを指定します。
当方環境のdocker-compose.ymlの場合は、12～14行目に追記致しました。
| 設定値 | 概要 | 今回の設定値 |
|---|---|---|
| gitlab_pages['enable'] | GitLab ページを有効または無効にする。 | true |
| gitlab_pages['listen_proxy'] | リバース プロキシ リクエストをリッスンするアドレス。 (デフォルト値が設定されているにもかかわらず、明示的に指定しないとうまく動かないようなので、明示的にしています。) |
'localhost:8090' |
| gitlab_pages['internal_gitlab_server'] | API リクエスト専用の内部 GitLab サーバー アドレス。 | 'http://localhost:8080' |
version: '3.6' services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlabmain.example.com' environment: GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlabmain.example.com' gitlab_rails['gitlab_shell_ssh_port'] = 2224 pages_external_url 'https://pages.example.com' gitlab_pages['enable'] = true gitlab_pages['listen_proxy'] = 'localhost:8090' gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080' ports: - '80:80' - '443:443' - '2224:22' volumes: - '/srv/gitlab/config:/etc/gitlab' - '/srv/gitlab/logs:/var/log/gitlab' - '/srv/gitlab/data:/var/opt/gitlab' shm_size: '256m' networks: app_net: ipv4_address: 192.168.100.10 networks: app_net: driver: bridge ipam: driver: default config: - subnet: 192.168.100.0/24
最後に、今回はGitLab Pagesでhttpsを使いたいので、事前準備で作成したワイルドカード証明書のパスとキーのパスを明示的に指定します。
ワイルドカード証明書のパスの設定値はpages_nginx['ssl_certificate']、キーのパスの設定値はpages_nginx['ssl_certificate_key']です。
この時設定する証明書とキーのパスは、コンテナから見た証明書とキーのパスを記載します。
当方環境のdocker-compose.ymlの場合は、15,16行目に追記致しました。
(筆者の検証環境で述べた通り、Dockerホストの/srv/gitlab/conigをGitLabコンテナの/etc/gitlabにハードマウントしています。)
version: '3.6' services: gitlab: image: 'gitlab/gitlab-ee:latest' restart: always hostname: 'gitlabmain.example.com' environment: GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlabmain.example.com' gitlab_rails['gitlab_shell_ssh_port'] = 2224 pages_external_url 'https://pages.example.com' gitlab_pages['enable'] = true gitlab_pages['listen_proxy'] = 'localhost:8090' gitlab_pages['internal_gitlab_server'] = 'http://localhost:8080' pages_nginx['ssl_certificate'] = '/etc/gitlab/ssl/pages.example.com.crt' pages_nginx['ssl_certificate_key'] = '/etc/gitlab/ssl/pages.example.com.key' ports: - '80:80' - '443:443' - '2224:22' volumes: - '/srv/gitlab/config:/etc/gitlab' - '/srv/gitlab/logs:/var/log/gitlab' - '/srv/gitlab/data:/var/opt/gitlab' shm_size: '256m' networks: app_net: ipv4_address: 192.168.100.10 networks: app_net: driver: bridge ipam: driver: default config: - subnet: 192.168.100.0/24
他にもたくさんの設定値があるのですが、この5つの項目の設定でGitLab Pagesを動かせるはずなので、今回はこれで次に進みます。
他の設定項目については以下のGitLab Docsをご参照ください。
参考 : GitLab Pages administration - Global settings | GitLab
編集したdocker-compose.yml保存し、GitLabを起動します。
Step2. GitLab Pagesの有効化確認
前のステップで起動したGitLabでGitLab Pagesが有効になっているかを確認します。
GitLabで管理者権限を持つユーザーでサインインし、[メニュー] > [管理者] をクリックします。
[概要] > [ダッシュボード] を開き、[機能] 欄を確認します。
GitLab Pagesが有効になっている場合は、 [GitLab Pages] 項目に緑のチェックマーク ( ) が表示されています。
Step3. Pages用のグループ (Top-level) を作成
GitLab Pagesを試すためのグループを作成します。
グループを作成できる権限を持つユーザーでGitLabにサインインし、[メニュー] > [グループ] > [グループを作成] をクリックします。
(グループの作成は、GitLabインスタンスに管理者権限を持つユーザーの他、通常ユーザーでも権限が付与されていれば可能です。)
[グループを作成] をクリックします。
[グループ名] に任意の文字列を指定し、可視性レベルを任意に設定します。
またこの際、もし事前準備の必須 : ワイルドカード DNS レコードの作成 or hostsの編集でDNSのレコード編集ではなくクライアント側のhostsファイルを編集する方を選択した場合は、Group URLのテキストボックスに表示された文字列を参考に、以下の図の要領でクライアント側のhostsファイルを編集してください。
設定後、[グループを作成] をクリックします。
Step4. テンプレートを使ってプロジェクトを作成
GitLabにはいくつかプロジェクトのテンプレートが存在します。
その中にGitLab Pages用のテンプレートもあるので、今回はそれを用います。
前のステップで作成したグループに移動してから、[新規プロジェクト] をクリックします。
[テンプレートから作成] をクリックします。
[Pages/Plain HTML] というテンプレートを探し、[テンプレートを使用] をクリックします。
[プロジェクト名] に任意の文字列を入力し、可視性レベルを任意に設定します。
設定後、[プロジェクトを作成] をクリックします。
しばらくすると、テンプレートを使ったプロジェクトが自動で作成されます。
Step5. CI/CDパイプラインを実行
先ほどテンプレートから作成したプロジェクトは、変更せずそのままCI/CDパイプラインを実行するだけで、リポジトリのpublicフォルダーの中にあるhtmlが静的Webサイトとして公開されるようになっています。
今回は手動でCI/CDパイプラインを実行します。
まず、このプロジェクトがRunnerを使用可能な状態になっているかを確認します。
このプロジェクトに対してMaintainer以上のロールを持つユーザーでサインインします。
対象プロジェクトの [設定] > [CI/CD] を開き、[Runner] を展開します。
このプロジェクトで使用可能なRunnerが1つ以上あることを確認してください。
下図の場合、共用Runner (Shared runner) が2つ利用可能な状態です。
利用可能なRunnerが1つもない場合は、GitLab Docsや弊社の過去のブログなどをご参照の上、このプロジェクトで利用可能なRunnerを1つ以上ご用意ください。
参考 : Install GitLab Runner | GitLab
, GitとCI/CDに関する知識ゼロのSEが、GitLabでRunner (Docker) を登録するだけの話
1つ以上利用可能なRunnerがあることが確認出来たら、あとはそのままCI/CDパイプラインを実行します。
このプロジェクトの [CI/CD] > [パイプラン] を開き、画面右上の [Run pipeline] をクリックします。
[Run pipeline] をクリックします。
パイプラインの詳細画面に自動遷移しますので、パイプラインが完了するまで待機します。
パイプラインが完了したら、下図のようにジョブ [pages] と [pages:deploy] が存在し、両方とも正常終了していることを確認します。
Step.6 公開された静的Webページの確認
デプロイされたWebページを確認します。
このプロジェクトに対してMaintainer以上のロールを持つユーザーでサインインします。
プロジェクトのページから、[設定] > [Pages] をクリックします。
あなたのページは以下で提供されます：の下にURLがあるのでそれをクリックします。
警告が出た場合は、そのまま表示をしてください。
正常にGitLab Pagesで静的Webページをデプロイできた場合は、最終的に下のようなサンプル画面が表示されます！
Docker Composeで起動したGitLabでGitLab Pagesを簡単に試す方法は以上となります。
今回表示した.htmlファイルはリポジトリのpublicフォルダ内にあるので、このファイルを変更すると独自のWebページを表示することができます。
最後に
この度はGitもCI/CDもよくわかっていないど素人SEによるGitLab検証ブログをお読みいただき、誠にありがとうございます。
このブログの目標は以下のとおりでしたが、皆さまはいかがでしたでしょうか。
- Docker Composeで起動したGitLabで、GitLab Pagesを使って静的Webサイトをデプロイする。
ずっと前から「早く書かなきゃ・・・」と思っていたGitLab Pagesの検証ブログを、今回ついに書くことができました。
当方の環境はコンテナでGitLabを起動、プライベートCA利用、Runnerもコンテナ…とトラブルが起きやすい環境だったのですが、GitLab社の公式の動画に助けられ簡単に試すことができました。
この記事がGitLabを触り始めた方の一助となれば幸いにございます。
GitLabに関するお問い合わせは、以下のフォームからお願い致します。
GitLab製品 お問い合わせ
今までのGitLabの検証ブログはこちらです。
GitLab操作デモ動画 (基本編) を作ってみました。(音声の録音は自宅でiPhoneのボイスメモ使うという超低クオリティですが…。)
つたない内容ではありますが、ご興味がおありでしたら是非ご視聴いただければと存じます。
