Build Application Images

This page describes how to build the Self-Managed Commerce application images using the build tools included in the Self-Managed Commerce ep-commerce Git project.

note

For more information about containerized Self-Managed Commerce, see Containerized Environments.

Prerequisites

Before you begin, ensure you meet the following prerequisites.

Build Environment Requirements

The scripts are designed to be run in a suitably configured environment. For more information, see Configure the Build Environment.

Container Layout

The Self-Managed Commerce container layout, which is a zip file that contains Self-Managed Commerce artifacts, Dockerfiles and entrypoint scripts, must be available on or copied to the build host. For instructions to create the container layout zip file, see Build the Container Image Layout. If the container layout was created on a different host, copy it so it is available locally before proceeding.

note

The Dockerfiles and container entrypoint scripts that are packaged in the container layout package are located in the ep-commerce project source, under path extensions/packager/ext-container-layout/src/main/files.

Base Images

The Self-Managed Commerce base images must be available to the build host. For instructions to create the base images, see Build Base and Third-Party Images.

tip

For more information about the relationship between the Self-Managed Commerce application images, the base images, and the deployment package, see Self-Managed Commerce Deployment Artifacts.

Ansible Playbook build_commerce_images.yml

Use the included devops/build_tools/build_commerce_images.yml playbook to build the Self-Managed Commerce application images.

Basic Usage

1. Establish a shell session on the build host.
2. Clone the Self-Managed Commerce source code project ep-commerce from your organization Git repository.
3. Checkout the ep-commerce branch that you want to build. It should be the same branch used to build the prerequisites.
4. Change directory to devops/build_tools.
5. Invoke the playbook to build the application images.

ansible-playbook build_commerce_images.yml

Output

The playbook outputs Self-Managed Commerce container images and a file with details about the container images.

Commerce container images

The playbook outputs the container images described below, which are used to deploy Self-Managed Commerce environments.

Image name	Description	Default Image Tag
ep/cortex	Commerce API and Cortex Studio	<ep_release_version>
ep/search	Search Server	<ep_release_version>
ep/cm	Commerce Manager	<ep_release_version>
ep/batch	Batch Server	<ep_release_version>
ep/integration	Integration Server	<ep_release_version>
ep/data-sync	Data Sync WebApp	<ep_release_version>
ep/data-pop-tool	Commerce Data Population Tool	<ep_release_version>
ep/mock	Wiremock Service	<ep_release_version>

Image Facts File

The playbook outputs a text file that lists the names and tags of created images. The default location of the file is /opt/env/image_facts.env. Read or source this file to determine the fully-qualified name and tag of each image that has been built. The values in this file can be used to perform additional operations, such as pushing the images to a remote image repository.

The following key-value pairs can be found in the image facts file in the format of shell variables.

Key name	Default Value
IMAGE_CORTEX_FQN	ep/activemq:<ep_release_version>
IMAGE_SEARCH_FQN	ep/search:<ep_release_version>
IMAGE_CM_FQN	ep/cm:<ep_release_version>
IMAGE_BATCH_FQN	ep/batch:<ep_release_version>
IMAGE_INTEGRATION_FQN	ep/integration:<ep_release_version>
IMAGE_DATA_SYNC_FQN	ep/data-sync:<ep_release_version>
IMAGE_DATA_POP_TOOL_FQN	ep/data-pop-tool:<ep_release_version>
IMAGE_MOCK_FQN	ep/mock:<ep_release_version>

Using the Image Facts File

Use the image facts file by loading it in your current shell using the source command, then use the values to perform additional operations such as pushing the images.

Example:

source /opt/env/image_facts.env
docker push "${IMAGE_CORTEX_FQN}" # or img push "${IMAGE_CORTEX_FQN}"
docker push "${IMAGE_SEARCH_FQN}" # or img push "${IMAGE_SEARCH_FQN}"
docker push "${IMAGE_CM_FQN}" # or img push "${IMAGE_CM_FQN}"
docker push "${IMAGE_BATCH_FQN}" # or img push "${IMAGE_BATCH_FQN}"
docker push "${IMAGE_INTEGRATION_FQN}" # or img push "${IMAGE_INTEGRATION_FQN}"
docker push "${IMAGE_DATA_SYNC_FQN}" # or img push "${IMAGE_DATA_SYNC_FQN}"
docker push "${IMAGE_DATA_POP_TOOL_FQN}" # or img push "${IMAGE_DATA_POP_TOOL_FQN}"
docker push "${IMAGE_MOCK_FQN}" # or img push "${IMAGE_MOCK_FQN}"

Playbook options

Additional options are available that allow you to control the behaviour and output of the playbook.

Building without a Docker daemon

The Ansible playbook and roles support building container images in a daemonless environment by using the img tool instead of docker. The img tool is installed when you configure your environment with the steps described in Configure a Build Host or Configure a Build Image.

note

The img command requires that the USER environment variable be set. We have observed that the USER variable is not set when accessing Linux host using AWS Session Manager. You may need to set the USER environment variable manually before building images with the img command. An example of how to do that is:

• export USER=$(id -un)

To use img for daemonless container image builds, set the Ansible variable use_img to true. You can set this on the command line with the -e use_img='true' syntax when you run the playbook, as shown in the below example:

ansible-playbook -e use_img='true' build_commerce_images.yml

To learn more about the img tool, see the img repository on GitHub.

Building the images separately

Under some circumstances you might want to build the Self-Managed Commerce application images individually. This can be done by specifying a comma-separated list of tags at runtime.

note

Tags can be any combination of: cortex,search,batch,integration,cm,data-sync,mock,data-pop.

Example:

• To exclude the Wiremock image, invoke ansible-playbook build_commerce_images.yml -t cortex,search,batch,integration,cm,data-sync,data-pop.
• To build only the Data Population Tool image, invoke ansible-playbook build_commerce_images.yml -t data-pop.
• To build only the Cortex application image, invoke ansible-playbook build_commerce_images.yml -t cortex.

tip

You can run the Self-Managed Commerce image build process in parallel by executing the build_commerce_images.yml playbook for each image individually, on different build hosts.

Specifying an image name prefix

All image names include a prefix value, which can be customized at playbook runtime. If you will be pushing images to a remote repository, this variable can be customized to include the repository URL.

note

The full image name will be a combination of image_name_prefix + / + image_name. The forward-slash (/) between the image_name_prefix and image_name will be added automatically.

Variable Name	Default Value
image_name_prefix	ep

Example:

ansible-playbook -e image_name_prefix='1234567.dkr.ecr.us-west-2.amazonaws.com/ep' build_commerce_images.yml

Image Tag

The image tag can be customized using a variable at playbook runtime.

note

By default, the image tag is determined by the Self-Managed Commerce release version defined in pom.xml.

Variable Name	Default Value
image_tag_commerce	<ep_release_version>

Example:

ansible-playbook -e image_tag_commerce='dev' build_commerce_images.yml

Change the path of the image facts file

The path to the image facts file can be changed by setting the image_facts_file variable when running ansible-playbook.

Example:

ansible-playbook -e image_facts_file='/tmp/image_facts.env' build_commerce_images.yml