Configure the Build Environment

The Self-Managed Commerce build tools are a set of components that perform common Self-Managed Commerce Maven build tasks, invoke Maven tests, and build container images. These tools are designed so you can use them on your local Linux environment, on a Linux server, or integrate them in your continuous integration (CI) system of choice.

This page describes how to automatically configure and prepare a Linux environment, running a supported operating system, so that it meets the prerequisites for running the Self-Managed Commerce build tools.

Access to the Self-Managed Commerce source code is required. For information, see Hosting the Self-Managed Commerce Source Code.

Options

If you want to run the build tools on a Linux build host running a supported operating system, you can configure the host by running the configure_build_host.sh script. See Configure a Build Host section.

If you want to run the build tools inside of a build container, you can create a Linux build image by running the configure_build_image.yml Ansible playbook. See Configure a Build Image section.

If you want to use the Self-Managed Commerce build tools locally but you are not running a supported operating system, then you can configure a local Linux container by following the steps in section Running the Tools in a Local Container below.

Configure a Build Host

You can run the configure_build_host.sh script to prepare a Linux host to run the build tools. The shell script will install Ansible and then invoke Ansible playbook configure_build_host.yml to complete the configuration.

Prerequisites

The Linux host requires a minimum of 4 CPUs, 16GB RAM 50GB disk space and access to the Internet. It also requires an installed Git client, and must be running a supported operating system.

note

You will need shell access on the build host, and must have the permission to run commands using sudo.

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's Git repository.
3. Change directory to devops/build_tools_extras.
4. Invoke sudo ./configure_build_host.sh to install the necessary software components and configurations.

sudo ./configure_build_host.sh

Output

The Ansible playbook will

• Install required operating system packages and tools

• Install Maven and the Java Development Kit (JDK). It installs the versions that are specified in the ops-spec.json file.

• Install the img tool. This is an image building tool that can be used to build container images in environments that do not have access to the Docker daemon. To learn more about the img tool, see the img repository on GitHub.

• Create an environment file that you can use to set the PATH, JAVA_HOME, and MAVEN_HOME environment variables. The default location of this file is /opt/env/environment_facts.env. You can source the file to set the environment variables and then, for example, run Maven commands from the command line.

  source /opt/env/environment_facts.env
  mvn --version

Options - Build Host Variables

Use the below environment variables to modify the behaviour of the configure_build_host.sh script.

Variable	Purpose	Default Value
extra_packages	Optionally specify additional packages to install by setting the extra_packages variable to a space-separated list. Only packages supported by the operating system can be installed. For packages available for Amazon Linux 2023, see Amazon Linux 2023 packages	n/a
environment_facts_file	Optionally change the location of the environment file	n/a

Example Usage

# Specify to install additional packages on the host
sudo ./configure_build_host.sh -e extra_packages='package1,package2'

# Specify to install additional package and to write the facts file to a different path
sudo ./configure_build_host.sh -e extra_packages='package1,package2' -e environment_facts_file='/tmp/environment_facts.env'

Next steps

Configure the Maven settings.xml file before running builds in the container. For more information, see Configure Maven Settings.xml.

Configure a Build Image

You can run the configure_build_image.yml Ansible playbook to prepare a container image that will have the tools and configuration required to run the Self-Managed Commerce build tools.

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_extras.
5. Invoke the playbook to create the build image.

ansible-playbook configure_build_image.yml

Output

The Ansible playbook will output a container image with the necessary tools and configuration required to run the build tools. That image will include the following:

• Required operating system packages and tools
• The Maven and the Java Development Kit (JDK) versions that are specified in the ops-spec.json file.
• The img tool to support building container images in environments that do not have access to the Docker daemon. To learn more about the img tool, see the img repository on GitHub.
• Other required environment configuration.

tip

When you run the image to perform builds, we recommend allocating it a minimum of 4 CPUs, 16GB RAM and 50GB disk space.

Options - Build Image Variables

Use the following variables to modify the image build process.

Variable	Purpose	Default Value
image_name	Name used for the built image	ep/builder
image_tag	Tag used for the built image	Self-Managed Commerce release version
use_img	Perform a daemonless image build (this does not require a running Docker daemon)	false
extra_packages	Optionally, specify a list of additional operating system packages to install on the image. Provide the package names in a space-separated list of packages that are valid for Amazon Linux 2023. For available packages, see Amazon Linux 2023 packages	n/a

For information about setting variables, see Defining Ansible Variables.

Example Usage

# Specify to install additional packages on the host
ansible-playbook -e extra_packages='package1,package2' configure_build_image.yml

# Specify to use the `img` tool and tag the resulting container image with `dev`
ansible-playbook -e use_img='true' -e image_tag='dev' configure_build_image.yml

Next steps

Configure the Maven settings.xml file before running builds in the container. For more information, see Configure Maven Settings.xml.

Running the Tools in a Local Container

If you want to use the Self-Managed Commerce build tools locally but you are not running a supported operating system, then you can use an Amazon Linux 2023 container to run the tools.

Prerequisites

The examples in this document require Docker and that the Self-Managed Commerce ep-commerce Git project be present on the host machine.

1. Install Docker Desktop on your machine so you can run containers. Refer to the Docker Desktop documentation for more details. A license may be required.

2. Clone the Self-Managed Commerce ep-commerce Git project to a path your machine. For this example let's assume that the path to the project is /Users/myuser/Documents/code/ep-commerce. Confirm that you are using a branch that includes the Self-Managed Commerce build tools. These tools are in the ep-commerce Git project, under folder devops/build_tools.

Approaches

Two approaches to creating a suitable container image are described below. One option is to configure an Amazon Linux 2023 container locally. Another option is to use a Self-Managed Commerce build image provided by your team.

Locally configure a container

Follow the steps below to configure a local Amazon Linux 2023 container that is suitable for running the Self-Managed Commerce build tools.

1. Pull the Amazon Linux 2023 container image. The below command should be sufficient. If you require more information, see the Amazon Linux documentation.

   docker pull amazonlinux:2023

2. Start an Amazon Linux 2023 container with the Self-Managed Commerce ep-commerce Git project mounted as a volume. The below command should be sufficient. If you require more information, see The Docker documentation.

   docker run --privileged --platform linux/amd64 -v /Users/myuser/Documents/code/ep-commerce:/root/ep-commerce -it --entrypoint bash amazonlinux:2023

   important

   In the above command, replace /Users/myuser/Documents/code/ep-commerce with the path to the ep-commerce project on your host.

This should start the container on your machine and bring you to a Bash prompt within the container, as the root user.

1. In the container, run the below commands to install the required software

   # change to the ep-commerce project folder that contains the host configuration tools
   cd /root/ep-commerce/devops/build_tools_extras/
   
   # Install and configure the necessary tools
   ./configure_build_host.sh

2. Optional: Export the running container to an image, to save your changes for later re-use.

   Identify the running container. You can run the below command to list all running containers.

   docker ps

   Export the running container to an image.

   # Example with placeholders for the container ID, the image name you want to use
   # and the tag name that you want to use.
   docker commit <container_id> <image_name>:<tag_name>
   
   # Example with specific values
   docker commit interesting_cerf smc_build_image:mytag

Using your team's build image

If your team has built and made the Self-Managed Commerce build image available to you, then you can use it locally to run the build tools.

1. Obtain the build image from your team's container repository using the appropriate docker pull command. Consult the team members who created the build image for more information.

2. Start a container using the build image, with the Self-Managed Commerce ep-commerce Git project mounted as a volume. The below command should be sufficient. If you require more information, see The Docker documentation.

   docker run -v /Users/myuser/Documents/code/ep-commerce:/root/ep-commerce -it --entrypoint bash ep/builder:<yourtag>

   important

   In the above command, replace /Users/myuser/Documents/code/ep-commerce with the path to the ep-commerce project on your host, and replace <yourtag> with the container image tag that you wish to use. Consult the team members who created the build image if you are unsure of the proper image tag to use.

This should start the container on your machine and bring you to a Bash prompt within the container, as the root user.

Next steps

Configure the Maven settings.xml file before running builds in the container. For more information, see Configure Maven Settings.xml.

Access and run the Self-Managed Commerce build tools from within the container. In the examples above, they will be available in the container at path /root/ep-commerce/devops/build_tools.

tip

When building Self-Managed Commerce Base and Third-Party Images or Application Images from within a container, you may need to set use_img='true'. See the linked documentation pages for more information.