これは「関連記事表示 by Vector Search 2.0」のデモサイトです。記事コンテンツはソリューションブログから引用しています。
Craft Cross CMSのコンテンツを使ってAstroでWebサイトを構築する

Craft Cross CMSのコンテンツを使ってAstroでWebサイトを構築する

こんにちは、Customer Engineerのgamiです！最近は『Slay the Spire』というドミニオンみたいなゲームにハマっています。

さて、先日リリースされた「Craft Cross CMS」は、いわゆるヘッドレスCMSとしての特徴を持っています。

Craft Cross CMS徹底解説：活用シーンからワークフローまで一挙公開！

CMS（Contents Management System）の中でも、一般に「ヘッドフル」なCMSであれば、Webサイト構築までをCMS側の機能で持っています。一方で「ヘッドレス」なCMSはその拡張性と引き換えに、Webサイト構築については開発者自身で面倒を見ないといけません。

そこで今回は、Webサイト構築を簡単にするフレームワークである「Astro」を使ってCraft Cross CMSのコンテンツを使ったWebサイトを構築する手順をご紹介します。

ヘッドレスCMSとは？

CMSに詳しくない方に向けて、まずはヘッドレスCMSとは何かについて簡単に補足します。

ヘッドレスCMSとは、フロントエンド（表示部分）とバックエンド（コンテンツ管理部分）が分離されたCMSのことです。従来のCMS（ヘッドフルCMS）は、コンテンツ管理とWebサイトの表示機能が一体化していましたが、ヘッドレスCMSでは以下のような特徴があります。

ヘッドレスCMSの特徴:

  • API駆動：コンテンツはAPI経由で配信され、外部から柔軟に利用できる
  • フロントエンドの自由度：任意のフレームワークで表示部分を構築可能
  • マルチチャネル対応：Webサイト、モバイルアプリ、IoTデバイスなど複数のプラットフォームに同一コンテンツを配信可能

Craft Cross CMSもこのヘッドレスCMSの特徴を持ち、Webサイトを含むあらゆるチャネルから自由にコンテンツを利用できます。

Astroとは？

今回使うAstroについても、簡単に補足します。

Astroは、コンテンツ重視のWebサイト構築に特化した、現代的な静的サイトジェネレーター（SSG）です。オープンソースソフトウェアとして公開されており、無料で使うことができます。

サービスサイトのロゴを見ると、名だたるグローバル企業のWebサイトで採用されているようです。

Astroは他のWebフレームワークと比べても、ブログやドキュメントサイトなどコンテンツが中心となるWebサイトの構築に強みがあります。そのため、ヘッドレスCMSと組み合わせてWebサイト構築に使われることも多くあります。実際、サービスサイトを見ても様々なCMSとの連携実績があるようです。

AstroでCMSを利用する

今回ホスティングで利用するCraft Sitesではサーバーサイドでの動的なHTML生成には対応していないため、Webサイトを構築するには静的なファイルをビルドして設置する必要があります。その点で、静的サイト生成に強みがあるAstroは、Craft Sitesとも相性のよいWebフレームワークと言えます。

アウトプットイメージ

今回は、サンプルコードを使って「Craft Cross CMSで入稿したブログ記事を掲載するWebサイト」を構築してみましょう。

最終的なアウトプットイメージは次の通りです。

ブログ記事コンテンツをCraft Cross CMSで入稿します。

すると、そのコンテンツを使って次のようなブログサイトができあがります。

構成図は次の通りです。

今回は、Craft Cross CMS側でコンテンツを公開したときに自動でWebサイトをビルド & デプロイするような自動化の仕組みを構築します。ここでは例として、GitHub Actionsを使ってワークフローを実行し、Craft Sitesに対してWebサイトをデプロイします。

Astroを使うことで、Craft Cross CMSのコンテンツを埋め込む形でWebサイトのHTML/CSS/JavaScript等をビルドすることができます。

なお、開発時はローカル開発環境でコード修正やWebサイトの表示確認をします。また、Craft Sitesへのデプロイについても、まずは手動アップロードでの表示確認手順を紹介し、前述の自動デプロイの仕組み構築については後から補足します。

ちなみに、今回は例としてAstroとGitHub Actionsを使った構成を紹介していますが、AstroではなくNext.jsなど静的サイト生成に対応した他のWebフレームワークを使うこともできます。またGitHub Actionsについても、CircleCIなどその他のCI/CDプラットフォームに置き換えることも可能です。

注意点

前提として、次の点に注意をしてください。

  • 今回紹介する手順を試すには、 Web開発のための最低限のエンジニアリング知識が必要となります
    • 必要な前提知識の例: シェルスクリプト, Node.js, npm, Git
  • Craft Functions、Craft Sites、Craft Cross CMS、API v2が利用できるKARTEプロジェクトが必要です

設定手順

設定の手順は次の通りです。

  1. Craft Cross CMSでモデルおよびコンテンツを作成する
  2. CDNタイプのAPI v2アプリを作成する
  3. Astroを使ったローカル開発環境を構築する
  4. Craft Sitesのサイトを作成する
  5. Craft Sitesにビルド結果を手動アップロードする

順番に見てみましょう。

1. Craft Cross CMSでモデルおよびコンテンツを作成する

まず、Astroで表示するブログコンテンツを管理するためのモデルをCraft Cross CMSで作成し、サンプルコンテンツを入稿します。

  • [Craft > コンテンツ一覧 > コンテンツ設定] の [モデルを追加]から、モデル作成画面を開きます
  • 以下のフィールドを持つモデルを作成してください：
フィールド名タイプ表示名
titleテキストタイトル
image画像サムネイル画像
contentリッチテキスト本文
pubDate日付リリース日
descriptionテキスト詳細文
author選択著者
tags選択（複数）タグ
  • モデルを作成後、いくつかのサンプルコンテンツを入稿し、公開しておいてください

2. CDNタイプのAPI v2アプリを作成する

AstroからCraft Cross CMSのコンテンツを取得するために、CDNタイプのAPI v2アプリを作成し、必要なスコープを設定します。

  • Astroからコンテンツを取得するために、CDNタイプのAPI v2アプリを作成します

  • 以下のスコープを持つ cdn タイプのアプリを作成してください：

    • beta.cdn.cms.content.get
    • beta.cdn.cms.content.list

作成後、アクセストークンを控えておいてください。このトークンは後ほど使用します。

3. Astroを使ったローカル開発環境を構築する

今回の記事のために用意した次のサンプルコードを使用して、Astroのローカル開発環境を構築し、CMSとの連携設定をします。

craft-codes/astro/cross-cms-astro-sample at main · plaidev/craft-codes

  • 上記サンプルコードを、ローカルにgit cloneします
  • ターミナル上でダウンロードしたAstroプロジェクトのディレクトリに移動し、依存モジュールをインストールします
$ cd craft-codes/astro/cross-cms-astro-sample
$ npm install
  • プロジェクトルートに .env ファイルを作成し、以下の形式で実際の環境変数の値を記載して保存します
# cdnタイプAPI v2アプリのアクセストークン
CMS_CDN_API_ACCESS_TOKEN=atf0.xxxxxx

# [Craft > CMS設定 > APIエンドポイント] から確認できる、CDN APIのホスト名
CMS_CDN_API_HOST=a1b2c3d4.cdn-api.karte.io

# 作成したCMSモデルのID
CMS_BLOG_MODEL_ID=a1234567890b2345678901c3
  • 開発サーバーを起動します
$ npm run dev
  • ブラウザで http://localhost:4321 にアクセスし、Webサイトが表示されることを確認します

ここまでで、ローカル開発環境におけるCraft Cross CMSのコンテンツを使ったWebサイトの静的ビルドについては体験できました。

4. Craft Sitesのサイトを作成する

ここからは、Craft SitesにWebサイトをデプロイするための方法を紹介します。

まずは、ビルドしたAstroサイトをホスティングするためのCraft Sitesサイトを作成します。

  • [Craft > サイト]の[新規作成]から、適当な設定でサイトを作成します
    • 検証目的であれば、ドメインは [自動でドメインを払い出す] を使って問題ありません
    • [キャッシュTTL] を0にしておくとサイト更新時にすぐに変更を確認できるので、検証時はおすすめです

5. Craft Sitesにビルド結果を手動アップロードする

次に、Astroプロジェクトを本番用にビルドし、生成された静的ファイルをCraft Sitesに手動アップロードして、Webサイトを公開します。

  • ターミナル上でAstroプロジェクトのディレクトリに移動し、本番用のビルドを実行します
$ cd craft-codes/astro/cross-cms-astro-sample
$ npm run build

  • ビルドが完了し、dist フォルダに静的ファイルが生成されたことを確認します

  • Craft Sitesの管理画面から先ほど作成したサイトを開き、この dist フォルダの中身をルートディレクトリに展開する形でアップロードし、全ファイルを公開します

    • 手順（例）
      • [フォルダのアップロード] で dist フォルダをアップロード
      • dist フォルダ配下の全ファイルを [公開する]
      • dist フォルダを指定してルートディレクトリに [移動]

  • アップロード完了後、Craft SitesのURLにアクセスして、正常にWebサイトが表示されることを確認します

これで、ビルドしたWebサイトをCraft Sitesに手動デプロイすることができました。

補足：GitHub Actionsを使った自動デプロイの設定

前述のように、実運用を考えると、「Craft Cross CMSでコンテンツを更新したときにはWebサイト側にも自動でその更新内容が反映されるような自動化」ができた方が便利です。

一般的には、次のようなワークフローを構築し、Webサイトのビルドやデプロイを自動化します。

  • Craft Cross CMSのHook設定によって、コンテンツの作成や変更の公開/非公開をhookしてCraft Functionsを実行するようにする
  • Craft FunctionsからGitHub ActionsなどのCI/CDツールのジョブを実行する
  • CI/CDツールのジョブ上で、Astroを使ったビルドとCraft Sitesへのデプロイを実行する

今回は、GitHub Actionsを使った次のような自動化フローを実現するための設定例を簡単に紹介します。

GitHub側での設定

ソースコードの管理およびワークフロー実行のためのGitHubリポジトリを作成して、自動デプロイ用のワークフローを定義します。

  • GitHub上で、repository_dispatchイベントを起こすのに必要な権限を持ったPersonal access tokensを作成します

  • GitHubリポジトリを作成します

  • Astroアプリケーションのソースコードをリポジトリにpushします

  • 次のサンプルコードを参考に、.github/workflows配下にGitHub Actionsワークフローの設定ファイルを作成します

  • 以下のシークレットと変数をGitHubリポジトリに追加します

    • Repository secrets:
      • SITES_API_TOKEN: Craft Sitesを操作するためのAPI v2アプリのアクセストークン（後述）
    • Repository variables:
      • CMS_CDN_API_ACCESS_TOKEN: .envファイルの設定値と同様
      • CMS_CDN_API_HOST: .envファイルの設定値と同様
      • CMS_BLOG_MODEL_ID: .envファイルの設定値と同様
      • SITE_NAME: デプロイ対象のCraft Sitesサイト名

KARTE側での設定

KARTE側では、Craft Cross CMSの変更を検知してCraft Functionsを実行しGitHub Actions側に通知するための設定が必要になります。

  • 次の権限を持ったtokenタイプのAPI v2アプリを作成します
    • beta.craft.sites.content.upload
    • beta.craft.sites.content.invalidate
    • beta.craft.sites.content.updateVisibility
    • beta.cms.content.get
  • （作成したAPI v2アプリのアクセストークンを、前述したGitHub Repository secretsに設定します）
  • 作成したGitHub側のPersonal access tokensを、Craft Secret Managerに登録します
  • 次のサンプルコードを使って、イベント駆動タイプのCraft Functionsを作成します
  • 作成したAPI v2アプリの [Hook設定] に次のような設定を追加します
    • [トリガー設定]
      • KARTE CMS: コンテンツの公開時
      • KARTE CMS: コンテンツの非公開時
    • [チャンネル設定 > craft]
      • 先程作成したファンクションを設定し、有効化する

この設定により、CMSのコンテンツ公開/非公開時のHookの仕組みでCraft Functionsが自動実行されるようになります。そこからGitHub側にrepository_dispatchイベントが発生して、それをトリガーにしてGitHub Actions上でAstroを使ったWebサイトのビルドやCraft Sitesへのアップロードが走るようになります。

おわりに

今回はCraft Cross CMSのコンテンツを使ってAstroでWebサイトを構築する方法について紹介しました。

この構成により、効率的なコンテンツ管理と高速なWebサイトの両立が可能になります。特にGitHub ActionsなどのCI/CDツールとの連携により、CMSでの更新が即座にWebサイトに反映される自動化された運用を実現できます。

ぜひ皆さんも試してみてください！

Tags: