今回の記事では Sitecore JSS React SDKで提供される React のサンプルアプリを Sitecore JSS Next.js SDK 用に提供されるSitecoreファーストで開発するためのコンテナテンプレートを使用して作成した環境のCMサーバーにデプロイして統合モード(Integrated mode)で動作させる方法を記載します。
まず、Sitecoreのコンテナテンプレートを使用してJSS Next.js SDK用の開発環境をセットアップする手順は、公式サイトの次のページを参照してください。
Walkthrough: Setting up a development environment with the Sitecore Containers template for Next.js
または、本サイトの次のページを参照いただくこともできます。
コンテナ環境で開発するためのスターターテンプレートは Next.js 用のみが提供されています。今回は、その環境でJSS React SDKで提供されるアプリも開発できるようにしようというのが本記事を記載する内容になります。
今回使用した環境は次の通り
- ホスト: Windows 10 20H2 (Azure上にインスタンスを動作させています)
- Sitecore バージョン10.2
- Sitecore開発用テンプレート(Sitecore.DevEx.Templates)のバージョン : 1.6.1
前提として、JSS Next.js SDKのSitecoreコンテナテンプレートを使用した開発環境がセットアップ済みであることとします。また、プロジェクトフォルダーは、以下のパスに配置されている前提とします。
C:\projects\MyApp
1. コンテナのカスタマイズ
JSS React(Vue, Angular含む)アプリをコンテンツ管理サーバー上で動作させる場合、デフォルトの設定ではコンテンツ管理サーバー上にNode.jsをNode.jsレンダリングエンジン用にインストールする必要があります。
Next.jsの場合は、Next.js自身が独立したレンダリングホスト(HTTPレンダリングエンジン)として動作するためこの設定は不要です。ReactもNode.jsレンダリングエンジンの代わりにNext.jsと同じくHTTPレンダリングエンジンを使用するように設定をすることもできますがその場合はさらに追完お設定が必要になりますので今回はその方法は記載しません。
Next.js用のSitecoreコンテナ開発用テンプレートでは、CMサーバーにNode.jsがインストールされていないので、CMサーバーのイメージを作成する際に、Node.jsをインストールする設定を追加する必要があります。
VSコードなどのエディターを使用して、Next.js用のサンプルアプリをセットアップしたフォルダー直下にある、docker-compose.override.yml を開きます。(今回の場合はC:\projects\myapp)
cm用イメージのbuildセクションのargsに、 次の引数を追加します。
BUILD_IMAGE: mcr.microsoft.com/dotnet/framework/sdk:4.8-windowsservercore-ltsc2019
PowerShellを使用してnode.jsをダウンロードするために使用するイメージなので、PowerShellが使えるイメージであれば任意のDockerイメージをMicrosoftが管理するコンテナリポジトリからダウンロードして使用できます。今回はプロジェクトをビルドするためのsolutionイメージで使用されているイメージをそのまま再利用することにしました。変更を保存します。
次に、cmサーバー用のDockerfile(本例の場合 myapp\docker\build\cm\Dockerfile)を開きます。
下図などを参考に、上記で追加した BUILD_IMAGE を引数にとるコードを追加します。
ARG BUILD_IMAGE
BUILD_IMAGEをベースイメージとして、 node.js をダウンロードするコードを下記コードを呼び図を参考に追加します。
FROM ${BUILD_IMAGE} AS nodejs_files SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"] RUN Invoke-WebRequest -OutFile nodejs.zip -UseBasicParsing "https://nodejs.org/dist/v16.13.0/node-v16.13.0-win-x64.zip"; ` Expand-Archive nodejs.zip -DestinationPath C:\; ` Rename-Item "C:\\node-v16.13.0-win-x64" "C:\\nodejs"
DockerFileの最後に、ダウンロードして展開したnodejsのフォルダーをCMサーバー用のイメージにコピーし、環境変数PATHを追加するコードを追加して保存します。下記コード及び図を参考にしてください。
WORKDIR C:\nodejs COPY --from=nodejs_files C:\nodejs\ . RUN setx /M PATH $($Env:PATH + ';C:\nodejs')
コマンドプロンプトを起動し、プロジェクトフォルダー(本例の場合C:\projects\myapp)に移動して、イメージをビルドします。
docker-compose build
エラーが発生すれば適宜修正します。修正後、コンテナを起動して引き続きSitecore環境下コンテナ上で動作することを確認してください。
docker-compose up
2. APIキーの準備
Reactサンプルアプリ用のAPIキーを準備します。
コンテンツマネージメントサーバー(今回の環境の例の場合https://cm.myapp.localhost)にログインし、これから作成するReactアプリ用のAPIキーアイテムを作成します。
コンテンツエディターを起動して、/sitecore/system/settings/services/api keys アイテム配下に API Keyアイテムを作成します。CORS Origins と Allowed Controllersに * を入力して保存します。作成したAPIキーアイテムのIDをメモ帳などにコピーしておきます。
3. JSS React サンプルアプリのセットアップ
React(Vue, Anguler含む)用のサンプルアプリはコードファースト用のスターターアプリのみが用意されています。そのため、jss cli を使用してコードファースト用のサンプルアプリをまずはセットアップします。
jss cli自身はNext.js 用の開発環境を準備した段階でホストOS側にインストールされています。
コマンドプロンプトを起動して次のコマンドを実行します。今回は、C:\projects フォルダーは以下で次のコマンドを実行したと想定します。
jss create myreact react
これで、reactアプリは myreact フォルダーに作成されました。
早速コンテナ内で動作するSitecoreインスタンス(今回はCMサーバー)と接続するためのセットアップを行います。
cd myreact jss setup
jss setup コマンドを実行するとCUIベースのウィザードが起動するので、下図を参考に値を入力してウィザードを完了します。
この時いくつか注意点を記載します。 ファイルをデプロイするSitecoreフォルダーは、プロジェクトフォルダーのdocker\deploy\platform フォルダーを指定します。今回の環境の場合は C:\projects\myapp\docker\deploy\platform を指定しています。
開発のテンプレートをもとに作成したSitecoreのCMサーバーは、本フォルダーを監視して、ファイルやフォルダーが本フォルダーに配置されるとそのフォルダーやファイルをCMサーバーのコンテナのSitecoreのWebアプリケーションフォルダーにコピーします。
SitecoreのhostnameはJSS Next.js SDK用のテンプレートを使用してセットアップしたCMサーバーの名前を指定します。importサービスるのURLはデフォルトで問題ありません。API キーは作成したAPI KeyアイテムのIDを指定してください。
これでほぼ完了です。あとは設定ファイルやSitecoreアイテムおよびプログラムをデプロイするだけです。
4.プログラムのデプロイ
まずは、JSS Reactアプリ用の設定ファイルをデプロイします。jss deploy config を実行するとjss setup で指定したフォルダーにconfigファイルがコピーされます。
jss deploy config
platformフォルダーに追加したファイルやフォルダーはCMサーバーのコンテナにコピーして取り込まれます。コピーが完了したらCMサーバーが再起動されるので、コピー完了後platformフォルダーのファイルは削除できます。
最後に、 Sitecoreのコンテンツアイテム、辞書アイテムおよびテンプレートなどの開発者用のアイテムをCMサーバーにインポートします。
jss deploy app -c -d
デプロイが成功したら、CMサーバーにログインしコンテンツエディターを起動します。ツリーを展開 JSS React用のアイテムが作成されていることを確認してください。
また、エクスペリエンスエディターを起動してみたまま編集することができます。
5.おまけ Headless モードで動かす
作成したJSS ReactアプリはHeadlessモードで動作させることができます。手順は、下記headlessのサンプルページを参考にセットアップします。
その際、レイアウトサービスを提供するCMサーバー(開発テンプレートはXP0環境なのでCM,CDは兼任)はDockerコンテナとして動作しているため、ホストOS側にセットアップされたheadless用のnodejsアプリは、上記の設定だけだとうまく動かない場合があります。
そのため、私が動作確認時に行った追加の設定事項を記載します。
今回は、node-headless-ssr-proxyサンプルアプリをC:\projects\node-headless-ssr-proxyフォルダーにセットアップした前提で記載します。
5.1 qaParamsの追加
フォルダー直下にある、 config.js ファイルを開き 明示的にサイトを指定するqaParamsパラメーターを追加します。
qsParams: 'sc_site=myreact',
これは、CMサーバーはconfig.js の apiHost で指定したサーバー名を使用してサイトを解決します。そのため、Next.js用のアプリがデプロイされていると、cm.myapp.localhost のようなデフォルトの名前でレイアウトサービスを呼び出すように設定するとNext.jsアプリのサイトとしてリクエストが解決されます。そのためアプリごとにCM/CDサーバーにアクセスするサーバー名を分けていない場合は、qsParamsパラメーターを指定してサイト(JSSアプリ)を明確に指定するようにします。
5.2 ポート番号の変更
index.jsファイルを開きheadless ssr proxyように使用するポート番号をデフォルトの3000から80に変更します。
const port = process.env.PORT || 80;
これは、Sitecore 10.2の問題で、リクエストプロキシした場合にCMサーバーに送信される X-FORWARD-HOSTにポート番号が含まれていた場合(例えばlocalhost:3000)、Sitecoreがリクエストを処理する際にエラーを起こす問題を回避するためです。このため、80,443ポートを使用する必要があるのですが、今回は証明書の設定はしていないので、80ポートを使用するように指定しています。
駆け足になりましたが、今回の説明は以上です。
さんのコメント: さんのコメント: