Setting up Continuous Integration Server

Continuous Integration (CI) in the context of Elastic Path Commerce is the process of building and testing changes to the Elastic Path Commerce application code.

Typical Continuous Integration Flow

A typical Elastic Path Commerce continuous integration flow is described below:

Input:

• A branch of the ep-commerce source code repository.

Steps:

• Checkout the ep-commerce source code branch from your Git hosting service.
• Run one or more Maven build processes to:
  • Compile the specified branch of the ep-commerce source code.
  • Run software tests defined in the ep-commerce source code.
  • Create the Elastic Path Commerce deployment package.
• Run one or more container image build processes to create the set of Elastic Path Commerce container images.
• Deploy an Elastic Path Commerce test or integration environment, which includes:
  • A supported relational database service
  • A supported Apache ActiveMQ Java Messaging Service (JMS)
  • A database-population process ensures that the database table structure exists as defined in the Elastic Path Commerce cource code, and that the specified operational and test data is loaded
  • The Elastic Path Commerce application services deployed and running.
• Run tests that interact with and validate the deployed Elastic Path Commerce applications, such as:
  • The Elastic Path Commerce Cortex system tests. Cortex is the application service that provides the Elastic Path Commerce APIs. These tests are run as a Maven process.
  • The Commerce Manager System Tests. Commerce Manager is the web application used to manage Elastic Path Commerce stores. These tests are run as a Maven process.

After successfully completing the above steps, you will have:

• A branch of the ep-commerce source code repository that has passed the software tests.
• A set of Elastic Path Commerce container images built from that branch.
• A test environment that your team may leave up and use for further testing.

note

For more information about the artifacts mentioned in the continuous integration flow described above, see Elastic Path Commerce Deployment Artifacts.

Continuous Integration Server Requirements

You can choose any continuous integration tool that allows you to run an Elastic Path Commerce continuous integration flow. The high level requirements are:

• Access and clone your ep-commerce Git source code repository.
• Run Maven-based jobs in an environment that meets the Development Environment requirements.
• Build container images. Bash scripts are provided to facilitate building the various base images, third-party images, and Elastic Path Commerce images. The provided Bash scripts can only be run in a Linux environment. For more information about those scripts, see Containerization.
• Push the container images to your container image registries.
• Run a deployment process to your Elastic Path Commerce test environments. Depending on your requirements, these environment can be long-lived environments, ephemeral fully-containerized environments, or a mix of both. Examples of how to run Elastic Path Commerce services as containers are provided as Docker Compose files. For more information about those examples, see Containerization.

tip

CloudOps for Kubernetes includes Jenkins-based continuous integration (CI) tooling for building and testing Elastic Path Commerce. Elastic Path Commerce container images built using the CloudOps for Kubernetes CI tooling can be run on any infrastructure that supports Docker-style containers. Even if you do not use CloudOps for Kubernetes for your production infrastructure, it may still be a suitable way to quickly provide CI tooling for your Elastic Path Commerce implementation team. To learn more about CloudOps for Kubernetes, see Infrastructure Options.

Build Environment Setup

Follow the instructions at Setting up your Developer Environment to build Elastic Path Commerce in a command line environment.

important

Increase the maximum number of open file descriptors allowed to 132000 to avoid potential build failures. Consult your operating system documentation for more information.

Compute Requirements

The Maven build processes can run for a long time and require considerable compute power and memory. Below are recommended resources for the hosts that will run Maven build processes.

Minimum:

• CPU: 2 cores
• Memory: 6 GB
• Disk: 75 GB

Preferred:

• CPU: 6 cores
• Memory: 12 GB
• Disk: 150 GB

Updating the Maven settings.xml File

Your Maven build environment requires a suitably-configured Maven settings.xml file. Obtain or create a suitable file. See Update Maven Settings for more information.

Common Maven Commands

The following documentation describes the purpose and syntax of common Maven commands used in Elastic Path Commerce continuous integration. Setup continuous integration jobs only on the primary development branch.

Elastic Path Commerce

Builds the ep-commerce module and all modules within the ep-commerce module. This job builds:

• Bill of Materials
• Commerce Engine
• Health Monitoring
• Commerce Manager
• Cortex Resources
• Extensions
• Commerce Data
• Deployment Package

Root POM is ep-commerce/pom.xml.

mvn -B -U -e clean deploy -Pwith-deployment-package

Commerce Manager System Tests

Runs Commerce Manager Selenium tests and Cucumber tests using a deployed server as the test target.

Root POM is extensions/cm/ext-cm-modules/system-tests/selenium/pom.xml.

mvn clean verify -Premote -Dcucumber.options="--tags @smoketest" -Dfailsafe.fork.count="1" -Dremote.web.driver.url="http://<targetHost>:4444/wd/hub"

tip

Enable Test-ids on the target server using JVM (Java Virtual Machine) parameter -Dorg.eclipse.rap.rwt.enableUITests=true.

The deployment server and the test server might not be the same. To test against a remote Commerce Manager server, run the following command:

mvn clean install -Dcucumber.options="--tags @smoketest" -Dselenium.session.baseurl=${cmUrl} -Dep.cortex.url=${cortexUrl}  -f extensions/cm/ext-cm-modules/system-tests/selenium/pom.xml

Cortex System tests

Runs Cortex Cucumber testing using a deployed server as the test target.

Root POM is ep-commerce/extensions/cortex/system-tests/cucumber/pom.xml.

mvn -B -U -e clean verify -P!setup-local-integration-test -Dep.rest.baseurl=http://<cortex_host>/cortex -Dep.jms.url=tcp://${activemq_host}:61616 -Dit.test=CucumberRunnerIT

Notes

• Build modules with a valid settings.xml file

  The recommended practice is to use the maven/ci-settings.xml file in the ep-commerce/devops module and check this out from SCM (Source Code Management) at the beginning of each job.

• You can choose to add the following profiles to each of the Maven commands:

  • pass-build-even-if-tests-fail

    Using Jenkins, if a test fails then the build does not fail. This is useful because the build continues running and it will find all test failures. The build will turn unstable instead of passing or failing.

  • pass-build-even-if-code-compliance-fails

    Uses the same logic as pass-build-even-if-tests-fail but with regards to code compliance and code checking rules.