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 projects 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.
Tip: Jenkins server setup
If you plan to use the Jenkins CI Server, shell scripts are available to help install and configure Jenkins and create the necessary jobs.
  1. See Jenkins Setup for detailed instructions on how to install and configure Jenkins.
  2. Then follow Jenkins Job Setup to create Jenkins jobs.

Build sequence

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

Build Dependencies Fall-2014-SP2

CI jobs

At this time, we only need to setup CI jobs on the primary development branch (e.g. develop in Git, trunk in SVN). 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 project
  • Builds project and deploys generated artifacts to Maven repository
  • On completion triggers
    • Commerce Engine Tests
    • Extensions Build

Root POM: commerce-engine/pom.xml 

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

Root POM: commerce-engine/pom.xml 

mvn -B -U -e clean install
Extensions Build
  • Triggered by commits to extensions project, or by Commerce Engine Build job
  • Builds project and deploys generated artifacts to Maven repository.
  • On completion triggers
    • CM Client Build

Root POM: extensions/pom.xml 

mvn -B -U -e clean deploy
EP AEM Commerce Build
  • Requires the ep-aem-commerce project from EP-for-AMC-Fall-2014-SP1 release package
  • Triggered by commits to the ep-aem-commerce project, or by Extensions Build job
  • Builds project and deploys generated artifacts to Maven repository

Root POM: ep-aem-commerce/pom.xml 

mvn -B -U -e clean deploy
Geometrixx Demo Build
  • Requires the geometrixx-demo project from EP-for-AMC-Fall-2014-SP2 release package
  • Triggered by commits to the geometrixx-demo project, or by EP AEM Commerce Build job
  • Builds project and deploys generated artifacts to Maven repository

Root POM: geometrixx-demo/pom.xml 

mvn -B -U -e clean deploy
CM Client Build
  • Triggered by commits to cmclient project, or by Extensions Build job
  • Builds project and deploys generated artifacts to Maven repository

Root POM: cmclient/pom.xml 

mvn -B -U -e clean deploy -Pmulti-platform
Deployment Package
  • Packages up artifacts created by Commerce Engine, CM Client and Extensions builds for deployment to an application server.
  • Can be configured to run as a nightly job or to be triggered by the CM Client Build.

Root POM: extensions/packager/pom.xml.

mvn -B -U -e clean deploy
Deploy to Dev Team Server

Root POM: devops/pom.xml 

-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 projects. The recommended practice is to use maven/ci-settings.xml in the devops project 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 EP projects, as shown below:

Note:

The <distributionManagement> for commerce-engine and cmclient projects is defined as:

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

The <distributionManagement> for the extensions project is defined as:

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

And the <distributionManagement> for the ep-aem-commerce and geometrixx-demo project is defined as:

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

Configure 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 EP Releases Repository
EP_FOR_AEM_PROJECT_RELEASE_REPOSITORY_URL The URL of the project EP for AEM Releases Repository (includes geometrixx demo store)
PROJECT_SNAPSHOT_REPOSITORY_URL The URL of the project EP Snapshots Repository
EP_FOR_AEM_PROJECT_SNAPSHOT_REPOSITORY_URL The URL of the project EP for AEM Snapshots Repository (includes geometrixx demo store)
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 http://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwordsif you wish to use encrypted passwords in your ci-settings.xml.

Deliverables

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