Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Setup CI Server

Setup CI Server

Note: Role: DevOps
Dependent on By Documentation
CI server provisioning IT Operations Prepare Infrastructure
Maven repository setup DevOps Setup Maven Repository
Source code preparation Tech Lead Prepare Source Code

Overview

A Continuous Integration (CI) server is a core requirement for team-based development. There are a number of excellent CI servers that are available. Elastic Path uses Jenkins for internal projects.

The objectives of this step are to:

  • Automatically build all modules that were committed to source control in Prepare Source Code .
  • Deploy the resulting artifacts to the Maven repository manager so they can be shared with the construction team.

Build Sequence

The build sequence for Elastic Path modules is shown in the diagram below:

Build Sequence

CI Jobs

At this time, we only need to setup CI jobs on the primary development branch. Prior to release it will also be necessary to setup CI on the release branch.

The jobs and associated commands to be automated are:

Job Name Description Maven command
Commerce Engine Build
  • Triggered by commits to commerce-engine module
  • Builds module and deploys generated artifacts to Maven repository
  • On completion triggers
    • Commerce Engine Tests
    • Cortex EP Integration Build
    • Commerce Manager Build

Root POM: commerce-engine/pom.xml 

mvn -B -U -e clean deploy -DskipAllTests
Commerce Engine Integration Tests
  • Triggered by Commerce Engine Build job
  • Runs integration tests for the commerce-engine module.

Root POM: commerce-engine/pom.xml 

mvn -B -U -e clean install
Commerce Data Build
  • Triggered by commits to commerce-data module
  • Builds module and deploys generated artifacts to Maven repository
  • On completion triggers
    • Extensions Build

Root POM: commerce-data/pom.xml 

mvn -B -U -e clean deploy
Cortex Resources Build
  • Triggered by commits to cortex-resources module, or by Commerce Engine Build job
  • Builds module and deploys generated artifacts to Maven repository.
  • On completion triggers
    • Extensions Build (when Commerce Manager is also complete)

Root POM: cortex-resources/pom.xml 

mvn -B -U -e clean deploy
Commerce Manager Build
  • Triggered by commits to commerce-manager-client module or by Commerce Engine Build job.
  • Builds module and deploys generated artifacts to Maven repository
  • On completion triggers
    • Extensions Build (when Cortex EP Integration Build is also complete)

Root POM: commerce-manager-client/pom.xml 

mvn -B -U -e clean deploy
Warning: Multi-threaded builds are not supported by this module.
Extensions Build
  • Triggered by commits to extensions module, or when Commerce Data build is complete, or when Commerce Manager and Cortex Resources Build are complete. You must set up this job to trigger when both Commerce Manager and Cortex EP Integration are complete, since extensions depends on both.
  • Builds module and deploys generated artifacts to Maven repository.
  • On completion triggers
    • Deployment Package

Root POM: extensions/pom.xml 

mvn -B -U -e clean deploy
Warning: Multi-threaded builds are not supported by this module.
Deployment Package
  • Packages up artifacts created by Commerce Engine, CM and Extensions builds for deployment to an application server.
  • Can be configured to run as a nightly job or to be triggered by the Extensions Build.
  • Can also be built as part of the extensions reactor.

Root POM: extensions/packager/pom.xml.

mvn -B -U -e clean deploy

OR

Root POM: extensions.

mvn -B -U -e clean deploy -Pwith-deployment-package
Commerce Manager System Tests
  • Runs Commerce Manager Selenium + Cucumber tests using a deployed server as the test target.

Root POM: extensions/cm/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: Test-ids must be enabled on the target server using JVM parameter -Dorg.eclipse.rap.rwt.enableUITests=true.
Deploy to Dev Team Server

Root POM: devops/pom.xml 

mvn -B -U -e clean package

After Maven has completed, the CI server should execute the following script:

ssh $DEPLOYER_USER@$DEPLOYER_HOST """
cd ~/
rm -rf target &&
rm -rf deploy &&
mkdir deploy
"""

scp $WORKSPACE/pusher-package/target/*.zip $DEPLOYER_USER@$DEPLOYER_HOST:deploy

ssh $DEPLOYER_USER@$DEPLOYER_HOST """
cd deploy
chmod +x *.zip &&
unzip *pusher-package*.zip
"""

ssh $DEPLOYER_USER@$DEPLOYER_HOST """
cd deploy/the-pusher*
chmod +x PushDeploy.sh && ./PushDeploy.sh -p ../*deployment-package*.zip -f ../environments/dev/pusher.conf 
-f ../environments/dev/database.properties -d $DATA_POPULATION_COMMAND
"""

where the following parameters are supplied by the CI job:

Parameter Description
$WORKSPACE The devops project directory on the CI server
$DEPLOY_ENVIRONMENT The environment to be deployed
$DEPLOYER_HOST The host on which the deployment script is to be run
$DEPLOYER_USER The username for connecting to the deployer host
$DATA_POPULATION_COMMAND The data population command to be executed. Values are:
  • reset-db: Drops the database if it exists, then creates and populates a new database.
  • update-db: Updates the current database with schema and data changes.
  • none: Deploys without running data population.

Notes

  • A valid settings.xml is required to build modules. The recommended practice is to use maven/ci-settings.xml in the devops module and check this out from SCM at the beginning of each job.
  • You can choose to add the following profiles to each of the maven commands:
    1. pass-build-even-if-tests-fail - Using Jenkins, if a test fails then the build does not fail. This is useful because the build will continue running and it will find all test failures. The build will turn unstable instead of passing or failing.
    2. pass-build-even-if-code-compliance-fails - Same logic as (a) but with regards to code compliance/code checking rules.

Distribution Management

In order to deploy artifacts to your Maven repository you need a settings.xml file with the repository URLs and credentials to match the distribution management defined for Elastic Path projects, as shown below:

Note:

The <distributionManagement> element is defined as follows:

    <distributionManagement>
        <repository>
            <id>ep-releases</id>
            <url>${ep.releases.repository.url}</url>
        </repository>
        <snapshotRepository>
            <id>ep-snapshots</id>
            <url>${ep.snapshots.repository.url}</url>
        </snapshotRepository>
    </distributionManagement>

Configuring ci-settings.xml

To configure Maven for CI builds and distribution management, replace the following tokens in devops/maven/ci-settings.xml and commit to source control.

Token Description
PROJECT_REPOSITORY_GROUP_URL The URL of the project repository group used as the project mirror.
PROJECT_RELEASE_REPOSITORY_URL The URL of the project Elastic Path Releases Repository
PROJECT_SNAPSHOT_REPOSITORY_URL The URL of the project Elastic Path Snapshots Repository
MAVEN_DEPLOYER_USER_NAME The username for the Maven repository account used for deployment
MAVEN_DEPLOYER_PASSWORD

The password for the Maven repository account used for deployment

Note:

See the Maven How to encrypt server passwords if you wish to use encrypted passwords in your ci-settings.xml.

Deliverables

  • A working Continuous Integration server that builds and deploys Elastic Path projects.