ソリューションのビルド

このガイドでは、DockerfileとDockerイメージのビルドプロセスと、それを使ってSitecoreソリューションをビルドする方法を紹介します。

注意: このページの原文は https://containers.doc.sitecore.com/docs/build-solution です

始める前に

このガイドでは、「はじめに」のドキュメントを読んだことを前提としています。具体的には、すぐに使える Sitecoreインスタンスを正常に実行 できることを前提としています。

Docker Examples リポジトリをクローンする

まだやっていない場合は、Docker Examples リポジトリ をマシン上のどこかにクローンしてください。例えば、C:\sitecore\docker-examples\ (この記事では、このフォルダが使用されていると仮定しています)。

このリポジトリには、Sitecore Containers DevEx ドキュメントのコンパニオンコードが含まれています。このガイドでは、custom-images フォルダを使用します。

Dockerfiles を理解する

Dockerfilesの簡単な紹介

Dockerfileを書くことは、アプリケーションをコンテナ化するための最初のステップです。Dockerfile には、Dockerイメージの組み立て方や実行方法の指示が含まれていることを覚えておいてください。Dockerfileのコマンドは、イメージの組み立て方のステップバイステップのレシピと考えることができます。

ここでは、シンプルな（Sitecoreではない）ASP.NET MVCアプリの例を示します。

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 AS build
WORKDIR /app

COPY *.sln .
COPY aspnetmvcapp/*.csproj ./aspnetmvcapp/
RUN nuget restore

COPY aspnetmvcapp/. ./aspnetmvcapp/
WORKDIR /app/aspnetmvcapp
RUN msbuild /p:Configuration=Release

FROM mcr.microsoft.com/dotnet/framework/aspnet:4.8 AS runtime
WORKDIR /inetpub/wwwroot
COPY --from=build /app/aspnetmvcapp/. ./

この例では マルチステージビルド を使用しています。最初に mcr.microsoft.com/dotnet/framework/sdk イメージを使ってコードをビルドし (ビルド段階)、出力を mcr.microsoft.com/dotnet/framework/aspnet イメージ (ランタイム段階) にコピーします。

Dockerfileは Docker buildコマンド に渡され、イメージをビルドして作成します。

オプションの .dockerignore を使用すると、ファイルやフォルダをビルドコンテキストから除外し、サイズを小さくしたり、COPYコマンドやADDコマンドで機密データをスキップしたりすることができます。

Dockerfiles の詳細については、Docker のドキュメントを参照してください。

コードのビルドはどこで行われるべきでしょうか？

上の例で見たように、コードのコンパイルとビルドはDockerfileの命令の一部です。.NETの場合、これにはNuGetのリストアとMSBuildの呼び出しが含まれているかもしれません。このようにDockerfileで直接アプリケーションをビルドすることは、より「伝統的な」ビルドに比べて以下のような利点があります。

  • 移植性 - ビルドプロセス全体が「コンテナ化」されています。ビルドエージェントとローカル環境は、Docker以外に何もインストールする必要がありません。
  • ビルド環境のコントロール - どのビルド依存関係（とどのバージョン）を使用するかはソリューションが所有します。
  • 効率性 - ビルドステップが非常に冗長であっても、Dockerのビルドキャッシュを使用することで、リビルドが最適化されます。
  • Dockerエコシステムの中でうまく実行する - ビルドはDockerコマンドを使ってトリガーすることができ、他のイメージで使用するためのビルド成果物の取得は、Dockerfile FROM命令で簡単に行えます。

このガイドでは、このアプローチに焦点を当てています。

Dockerfileでのビルドが望ましいとはいえ、ソリューションをビルドするためには従来の方法に頼らざるを得ない場合もあります（レガシーコードベースやビルドプロセスの制限などの理由で）。このシナリオの詳細については、次の記事を参照してください。

ソリューションのビルド Dockerfile とイメージ

ほとんどのDockerの例では、コードがコンパイルされ、ベースとなるWindowsイメージの上にビルドされ、結果として得られたイメージが直接実行されます（ランタイムイメージと呼ばれます）。

しかし、典型的なSitecoreの実装では、1つのVisual Studioソリューションで複数のロール（例：WebサイトやXConnectアセンブリ）用のビルド成果物を作成するのが一般的で、いくつかの成果物は複数のロール（例：CM/CD）にデプロイする必要があります。コンテナの場合、同じビルド出力を複数の Sitecore ランタイムイメージの上に重ねる必要があります。各Sitecoreイメージごとにビルド命令を複製することもできますが、これは非常に非効率的です。

そこで必要なのは、(1)ソリューションをビルドし、(2)ビルド結果のイメージ上に構造化されたビルド成果物として出力を保存することだけに特化したDockerfileです。

Dockerfile をビルド

これはまさにルートの Dockerfile の例にあるものです。

Dockerコミュニティでは、Dockerfile.buildという名前のビルド用Dockerfileをよく見かけます。

custom-images フォルダに移動して、ここにある Dockerfile を見てみてください (例: C:\sitecore\docker-examples\custom-images\Dockerfile )。

ここでは、簡単のために BASE_IMAGE と BUILD_IMAGE のARGを展開しています。

このファイルは、エスケープ文字 を (デフォルトのバックスラッシュではなく) バックスティックに設定するためのエスケープディレクティブで始まります。

# escape=`

次に、NuGetのリストアに必要なアーティファクトだけを集めるための prep 段階を行います。これは.NETビルドでよく行われる最適化です。Dockerfile のベストプラクティス - NuGet リストアの最適化 を参照してください。

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 AS prep

COPY *.sln nuget.config Directory.Build.targets Packages.props \nuget\
COPY src\ \temp\
RUN Invoke-Expression 'robocopy C:\temp C:\nuget\src /s /ndl /njh /njs *.csproj *.scproj packages.config'

新しいビルダーステージは、.NET Framework SDKイメージ に基づいてコードのコンパイルとビルドプロセスを開始し、BUILD_CONFIGURATION ARGが宣言されます（これは Docker Composeで設定 された "debug "か "release "のどちらかになります）。

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 AS builder
ARG BUILD_CONFIGURATION

SHELL命令は、それ以降のすべての命令でデフォルトのシェルをPowerShell（デフォルトのcmdから）に切り替えます。これはWindowsのDockerfilesでよく見かける命令です。

SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

次に、作業ディレクトリを作成し、先ほど収集したNuGetアーティファクトをコピーし、(最適化された)nugetリストアを行います。

WORKDIR C:\build
COPY --from=prep .\nuget .\
RUN nuget restore

復元後、残りのソースコードをコピーして、変換ファイルを C:\outtransforms に集めています。

COPY src\ .\src\
RUN Invoke-Expression 'robocopy C:\build\src C:\out\transforms /s /ndl /njh /njs *.xdt'

この例では、COPYコマンドのサイズを小さくし、binやobjフォルダのようなものを除外する.dockerignore(Dockerfileと並んでいる)が含まれています。 これはDockerfileをビルドする際のベストプラクティスです。

コンフィグ変換についての詳細は、 コンフィグ変換の適用 ガイドを参照してください。

次に、設定した BUILD_CONFIGURATION に対してmsbuildを使用してビルドを実行します。 この例では、Webサイト/プラットフォーム(DockerExamples.Website.csproj)とxConnect(DockerExamples.XConnect.csproj)の両方の環境をターゲットにしたプロジェクトが含まれています。単純なファイルシステムの公開で、出力先はそれぞれ C:\out\website と C:\out\xconnect になります。

RUN msbuild .\src\DockerExamples.Website\DockerExamples.Website.csproj /p:Configuration=$env:BUILD_CONFIGURATION /p:DeployOnBuild=True /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishUrl=C:\out\website
RUN msbuild .\src\DockerExamples.XConnect\DockerExamples.XConnect.csproj /p:Configuration=$env:BUILD_CONFIGURATION /p:DeployOnBuild=True /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishUrl=C:\out\xconnect

xConnect ビルドの詳細については、カスタム xConnect モデルを含む するガイドを参照してください。

ビルドが完了したら、最終イメージ用のビルド出力を収集します。このステージでは、Microsoft Nano Server イメージを使用します。このイメージはファイルを配信するだけで実行されることはないため、ベースイメージは最適化されたサイズで、他のランタイムイメージよりもはるかに小さいものが選択されます。

FROM mcr.microsoft.com/windows/nanoserver:1809

出力ファイルは、の段階から、builder 以下の構造で最終イメージにコピーされます。

  • \artifacts\website
  • \artifacts\transforms
  • \artifacts\xconnect
WORKDIR C:\artifacts
COPY --from=builder C:\out\website .\website\
COPY --from=builder C:\out\transforms .\transforms\
COPY --from=builder C:\out\xconnect .\xconnect\

この例では、Sitecore アイテムのシリアライズは考慮していません。シリアライズのフレームワークや戦略によっては、ソリューションのビルドDockerfileに追加の指示がある場合があります。詳細については、アイテムの展開 を参照してください。

ソリューションイメージ

ソリューションの Dockerfileのビルド は、ビルドの成果物だけで構成されるイメージを生成します。アセットイメージ」と呼ばれることもありますが、結果として得られるソリューションイメージは決してDockerコンテナで実行されることを意図したものではありません。

次回の記事では、このソリューションイメージが実際にどのようにしてカスタムSitecoreイメージを作成する ために使用されるかを見ていきます。

Docker Composeで設定する

イメージを生成するためには Dockerのビルドコマンド を使ってDockerfileを送る必要があることを覚えておいてください。ビルドコマンドを直接使うこともできますが、多くの場合はDocker Composeで設定します。

custom-imagesフォルダ（例：C:\sitecore\docker-examples\custom-images ）に移動して、以下のファイルを見てみましょう。

  • .env
  • docker-compose.yml
  • docker-compose.override.yml

これらは全てDocker Composeファイルの種類です。.env ファイルと docker-compose.yml ファイルは以前の記事で見ましたが、docker-compose.override.yml は新しいものです。

Composeファイルの形式については、Dockerのドキュメント を参照してください。

docker-compose.override.yml を理解する

Docker Composeコマンド(例: docker-compose up -d)では、特に指定がない限り、docker-compose.override.yml ファイルは自動的にメインの docker-compose.yml ファイルと一緒にインクルードされます。Docker Composeに2つ以上のComposeファイルが渡されると、それらをマージして、すべてのリソースと設定を1つのマージされた定義にまとめます。

複数のComposeファイルの使用方法の詳細については、Dockerのドキュメント を参照してください。

この例では、docker-compose.yml ファイルは Sitecore Experience Platform - Single (XP0) Docker Compose ファイルで、Sitecore から提供されています。docker-compose.override.yml は、メインファイルを拡張し、カスタムSitecoreイメージのビルドや開発に必要なオーバーライドや拡張機能を備えています。

ソリューションサービスの設定

docker-compose.override.yml ファイルでは、ソリューションイメージのビルドが定義されています。このファイルを開いて、ソリューションサービスがどのように設定されているかを見てみましょう。

solution:
  image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-solution:${VERSION:-latest}
  build:
    context: .
    args:
      BASE_IMAGE: ${SOLUTION_BASE_IMAGE}
      BUILD_IMAGE: ${SOLUTION_BUILD_IMAGE}
      BUILD_CONFIGURATION: ${BUILD_CONFIGURATION}
  scale: 0

いくつかの重要な注意点があります。

  • 変数の値（例：${SOLUTION_BASE_IMAGE}）は、この例では環境ファイル(.env )で定義されていますが、ローカルの開発マシン上のシステム環境変数やビルドサーバ上のシークレットから取得することもできます。
  • イメージ名には "-solution" という接尾辞を使用します。デフォルトの変数値では、タグ付けされたバージョンは docker-examples-solution:latest になります。
  • build context は . に設定されており、Docker Composeが同じ場所で Dockerfile をビルド を使用するように指示します。
  • build args はビルドDockerfileにあるものと相関しています。
  • scale は0に設定されており、docker-compose up に solution サービスのコンテナが起動しないようになっています。

ソリューションイメージをビルド

PowerShellプロンプトを開き、Composeファイルと同じフォルダ(例: C:\sitecore\docker-examples\custom-images )から以下を実行します。

docker-compose build solution
  • このガイドで使用されているコマンドやその他の一般的なコマンドの簡単なリファレンスについては、Sitecore Docker チートシート を参照してください。

これでソリューションイメージのビルドプロセスが開始され、順調にいけばイメージが作成されます。

Building solution
Step 1/21 : ARG BASE_IMAGE
Step 2/21 : ARG BUILD_IMAGE
Step 3/21 : FROM ${BUILD_IMAGE} AS prep
[...]
Successfully built 9bb20b2ab6db
Successfully tagged docker-examples-solution:latest

すべてのDockerイメージをリストアップすることで、イメージが作成されたことが確認できます。

docker images

REPOSITORY                TAG     IMAGE ID      CREATED        SIZE
docker-examples-solution  latest  9bb20b2ab6db  2 minutes ago  259MB

ソリューションイメージのビルドのトラブルシューティング

まずはトラブルシューティングガイド をご覧ください。

ソリューションイメージ (または他の「アセットイメージ」) に特有のよくあるトラブルシューティングの問題は、イメージがコンテナとして実行されることがないため、結果として得られるファイルシステムをどのように探索するかが明らかではないということです。これは、対話型シェルでイメージを実行 することで可能です。

例えば、上記のソリューションイメージの例に対して対話型コマンドプロンプトを開くには (Nano Server には PowerShell がありません)、以下のようにします。

docker run -it --rm docker-examples-solution:latest

exit と入力して一時的なコンテナを削除し、前の PowerShell セッションに戻ります。

次のステップ

ソリューションがどのように構築され、ビルドアーティファクトを持つイメージを手に入れたかを見てきましたが、Sitecore ランタイムイメージを作成するためにどのように使用されるかについては、リンクをたどってください。

関連情報

← 最初のSitecoreインスタンスの実行カスタムSitecoreイメージを構築する →