Build Base and Third-Party Images

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

note

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

Prerequisites

Before you begin, ensure you meet the following prerequisites.

Build Environment Requirements

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

Ansible Playbook build_base_images.yml

Use the included devops/build_tools/build_base_images.yml playbook to build the base images and third-party 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.
4. Change directory to devops/build_tools.
5. Invoke the playbook to build the base and third-party images.

ansible-playbook build_base_images.yml

Output

The playbook will output container images and a file with details about the container images.

Container images

The playbook outputs the four container images described below.

Image Name	Description	Default Image Tag
ep/amazonlinux_java	Java base-image, built on an Amazon Linux 2023 base image. The build tools use the Java version specified in the (ops-spec.json file).	<java_version>
ep/tomcat	Tomcat base image. The build tools use the Tomcat version specified in the (ops-spec.json file).	<tomcat_version>-<java_version>
ep/activemq	ActiveMQ application image. The build tools use the ActiveMQ version specified in the (ops-spec.json file).	<activemq_version>
ep/mysql	MySQL application image. The build tools use the containerized MySQL version specified in the (ops-spec.json file).	<mysql_version>

tip

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

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_ACTIVEMQ_FQN	ep/activemq:<activemq_version>
IMAGE_AMAZONLINUX_JAVA_FQN	ep/amazonlinux-java:<java_version>
IMAGE_MYSQL_FQN	ep/mysql:<mysql_version>
IMAGE_TOMCAT_FQN	ep/tomcat:<tomcat_version>-<java_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_ACTIVEMQ_FQN}" # or img push "${IMAGE_ACTIVEMQ_FQN}"
docker push "${IMAGE_AMAZONLINUX_JAVA_FQN}" # or img push "${IMAGE_AMAZONLINUX_JAVA_FQN}"
docker push "${IMAGE_MYSQL_FQN}" # or img push "${IMAGE_MYSQL_FQN}"
docker push "${IMAGE_TOMCAT_FQN}" # or img push "${IMAGE_TOMCAT_FQN}"

Playbook options

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

Choosing a MySQL Version

The build_base_images.yml playbook builds MySQL container images for use with Self-Managed Commerce. Both MySQL 8.0 and MySQL 8.4 are supported.

Default MySQL Version

By default, the playbook uses the database_id value defined in devops/build_tools/group_vars/all/main.yml, which currently points to mysql-8.4 in the operations specification (ops-spec.json). This means MySQL 8.4 images are built by default.

Explicitly Specifying a MySQL Version

You can explicitly choose which MySQL major version to build by overriding the database_id variable when you invoke the playbook:

Specify MySQL version 8.0:

ansible-playbook -e database_id='mysql-8.0' build_base_images.yml

Specify MySQL version 8.4:

ansible-playbook -e database_id='mysql-8.4' build_base_images.yml

Discovering supported MySQL versions

To discover the supported MySQL container versions, inspect the databases section of devops/ops-spec/src/main/resources/ops-spec.json in your ep-commerce branch. Find the MySQL entries where "deployment": "container". For more information on the format and contents of the ops-spec.json file, see Operations Specification (ops-spec.json).

For example, you can filter for containerized MySQL options with the following command:

jq -r '.databases[] | select(.deployment=="container" and .type=="mysql") | "\(.id) -> MySQL \(.version) (\(.versionChoice))"' devops/ops-spec/src/main/resources/ops-spec.json

The id value is what you supply via database_id when running ansible-playbook -e database_id='<id_value>' build_base_images.yml.

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_base_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 base and third-party images individually.

note

The tomcat and activemq images require that the amazonlinux_java image has already been built.

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.
4. Change directory to devops/build_tools.
5. Invoke ansible-playbook build_base_images.yml -t amazonlinux-java to build the Amazon Linux Java image.
6. Invoke ansible-playbook build_base_images.yml -t tomcat to build the Tomcat image, based on the Amazon Linux Java image.
7. Invoke ansible-playbook build_base_images.yml -t activemq to build the ActiveMQ image, based on the Amazon Linux Java image.
8. Invoke ansible-playbook build_base_images.yml -t mysql to build the MySQL image.

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.

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_base_images.yml

Image Tag

The image tags can be customized using variables at playbook runtime.

note

By default, the image tags are determined by version strings defined in the Operations Specification (ops-spec.json) file. For more information on the format and contents of this file, see Operations Specification (ops-spec.json).

Variable Name	Default Value
image_tag_java	Java version defined in ops-spec.json
image_tag_tomcat	Application server version defined in ops-spec.json
image_tag_activemq	ActiveMQ version defined in ops-spec.json
image_tag_mysql	MySQL container version defined in ops-spec.json

Example:

ansible-playbook -e image_tag_activemq='dev' build_base_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_base_images.yml