Build Tools Quick Start Guide

The following steps provide a quick introduction to the Self-Managed Commerce build tools.

What You Will Do

In this quick start guide, you will do the following:

• Configure a Linux host so it is suitable and ready to run the Self-Managed Commerce build tools.
• Clone the Self-Managed Commerce code repository to the Linux host.
• Configure a Maven ~/.m2/settings.xml file on the Linux host.
• Build the Self-Managed Commerce source code.
• Build the Self-Managed Commerce container layout.
• Build the Self-Managed Commerce base and third-party container images.
• Build the Self-Managed Commerce application container images.
• Start the Self-Managed Commerce application services.
• Observe the results.
• Stop the Self-Managed Commerce application services.

Prerequisite: Linux Host

Set up a Linux host with the below characteristics.

1. Using the Amazon Linux 2023 operating system.
2. With a minimum of 4 CPUs, 16GB RAM, 50GB disk space, and access to the Internet.
3. With a user that has the ability to run commands using sudo.
4. With packages git and openssh installed. On Amazon Linux 2023, run the command sudo dnf install openssh git.

note

Only Amazon Linux 2023 can be automatically configured by the provided tools.

tip

When you complete this quick start guide, the Self-Managed Commerce application services will be running on the Linux host. If you want to access the application URLs, ensure that the Linux host is on a network that you can reach from your web browser.

Prerequisite: Self-Managed Commerce Code

1. Verify that you have access to your Self-Managed Commerce code repository, which is typically named ep-commerce. For information, see Hosting the Self-Managed Commerce Source Code.
2. Using the Git command, clone the Self-Managed Commerce code repository to the Linux host.
3. Confirm that you are using a branch that includes the Self-Managed Commerce build tools folder <ep-commerce>/devops/build_tools.

note

This document uses the placeholder <ep-commerce> to represent the path to the Self-Managed Commerce code repository.

Configure the host

The configure_build_host.sh command will install the necessary packages and perform the necessary configuration so the host is ready to run the Self-Managed Commerce build tools. The configure_build_host.sh command is intended for use with Amazon Linux 2023.

1. Get a Bash prompt on the Linux host as a user with sudo powers.
2. Change directory to <ep-commerce>/devops/build_tools_extras.
3. Run the command: sudo ./configure_build_host.sh.

For more information, see Configure a Build Host.

Refresh user permissions

Log out and log back in to refresh your user's permissions. This is required for using Docker in later steps.

Configure the Maven settings.xml

The below steps provide an automated way to create the Maven ~/.m2/settings.xml file on the Linux host. You can also configure it manually.

tip

If you already have a suitable settings.xml file then you can copy that to the host at ~/.m2/settings.xml instead of following the below steps.

Steps:

1. Obtain your username and password for repository.elasticpath.com. If you do not have access, contact your project lead or contact Elastic Path at access@elasticpath.com.
2. Get a Bash prompt on the Linux host.
3. Change directory to <ep-commerce>/devops/build_tools_extras.
4. Run the command: ansible-playbook -e maven_deployer_user_name='<username>' -e maven_deployer_password='<password>' configure_maven_settings.yml.
   • Replace <username> and <password> with your username and password for repository.elasticpath.com.

For more information about this playbook, see Configure Maven Settings.xml.

Build the Source Code

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/build_tools.
3. Run command: ./build_source_tree.sh.

For more detail about the command, see Build the Source Tree.

Build the Container Image Layout

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/build_tools.
3. Run command: ./build_container_layout.sh.

For more detail about the command, see Build the Container Image Layout.

Build the Base and Third-Party Images

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/build_tools.
3. Run the command: ansible-playbook build_base_images.yml.

For more information, see Build Base and Third-Party Images.

Build the Self-Managed Commerce Application Images

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/build_tools.
3. Run the command: ansible-playbook build_commerce_images.yml.

For more information, see Build Application Images.

Start a Containerized Commerce Environment

Complete the below steps to start the containerized services.

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/docker_compose.
3. Run the following commands:

# Set necessary environment variables
# Note that the image_facts.env file was created by earlier steps.
source /opt/env/image_facts.env

# Start the ActiveMQ service
docker-compose -p ep-commerce -f activemq/docker-compose.yml up -d

# Start the MySQL database service
docker-compose -p ep-commerce -f mysql/docker-compose.yml up -d

# Create and populate the Self-Managed Commerce database
docker-compose -p ep-commerce -f data-pop-tool/docker-compose.yml up

# Start the Self-Managed Commerce services
docker-compose -p ep-commerce -f commerce/docker-compose.yml up -d

For more information, see Running Applications with Docker Compose.

Observe the Results

Inspect the results by running the below Docker commands.

1. Run docker image ls to vew the container images.
2. Run docker ps to view the running containers.

Browse to the Applications

You can navigate to and access the Self-Managed Commerce applications running on your Linux host.

1. Identify your Linux host’s IP address.
2. Use your web browser to open Cortex Studio. The URL will be like http://<your_hosts_ip>:8080/studio/. For information about Cortex Studio, see Learning to use Cortex Studio.
3. Use your web browser to open Commerce Manager. The URL will be like http://<your_hosts_ip>:8081/cm/ and the default login credentials are documented in Starting Commerce Manager. For information about Commerce Manager, see Introduction to Self-Managed Commerce Administration.

Stop the Services

Complete the below steps to stop the services.

1. Get a Bash prompt on the Linux host.
2. Change directory to <ep-commerce>/devops/docker_compose.
3. Run the following commands:

docker-compose -p ep-commerce -f commerce/docker-compose.yml stop
docker-compose -p ep-commerce -f activemq/docker-compose.yml stop
docker-compose -p ep-commerce -f mysql/docker-compose.yml stop

Quick Start Completed

After completing the above steps you have achieved the following:

1. You built the Self-Managed Commerce code.
2. You built the Self-Managed Commerce container images.
3. You created a Self-Managed Commerce database in a MySQL container image.
4. You started the Self-Managed Commerce application services on your Linux host.
5. You accessed the Self-Managed Commerce application services via your web browser.
6. You stopped the Self-Managed Commerce application and related services.