Best Practices from Oracle Development's A‑Team
-
Products and Services / Cloud
August 31, 2017
Build ATG Commerce applications in Oracle Developer Cloud
Introduction
This post will demonstrate how to setup and build an Oracle ATG Commerce application in Oracle Developer Cloud Service (devCS).
There are multiple ways to accomplish several steps described in this post. Things will intentionally be shown in a way to help give an understanding of how to accomplish tasks in a variety of environment configurations.
To build ATG applications, a product installation is required. At the time of creating this post, the Oracle Developer Cloud build environment has ATG 11.1 patch 1 libraries embedded in it. To build with other versions/patch levels of the ATG Commerce stack, additional steps are required not included in this post. Additional information on building with other versions will come in the future.
You can actually add builds to devCS with code from other versions of ATG. And you can upload libraries from other versions of ATG to your devCS maven repository. The code will likely build fine. However, this is not recommended for anything other than development purposes (not to be used with a production deployment).
Prerequisites
ATG is installed locally – version 11.1 or greater
Maven 3.x installed locally
GIT client installed locally
You have a Oracle Developer Cloud Service (devCS) domain
All steps in this post executed locally are assumed to be in your environment containing the ATG and Maven installations.
Local Setup Steps
Build ATeam ATGDust
- Download the source code for ATGDust, available here:
- http://www.oracle.com/technetwork/indexes/samplecode/commerce-samples-2766867.html
- Unzip the ATGDust archive
- Install ATG product libraries into your local maven repository
- Use the provided install-atglibs-maven.sh included in the ATGDust archive. This will give you many of the commonly used ATG product libraries. You may need to add others for your own application builds, depending on your custom code.
- This file is configured to install ATG 11.1 libraries. Edit the file if you have a different version of ATG. Instructions are in the file.
- Use the provided install-atglibs-maven.sh included in the ATGDust archive. This will give you many of the commonly used ATG product libraries. You may need to add others for your own application builds, depending on your custom code.
- Edit the pom.xml in the root of the folder where you extracted ATGDust if needed.
- The pom is set to build with ATG 11.1 by default. You only need to edit if you are using a different version of ATG. Edit the value of atg.version if using another version.
- Set environment variables. Adjust DYAMO_ROOT to match your ATG installation
export DYNAMO_ROOT=/u02/atg11.1 export DYNAMO_HOME=$DYNAMO_ROOT/home export ATG_ROOT=$DYNAMO_ROOT export ATG_HOME=$ATG_ROOT/home
mvn clean install
ATGDust should now be built, and installed in your local maven repository. ATG applications built with maven will now be able to execute ATGDust test cases.
Note – if you have not used maven much in the past, it is likely to download a large number of libraries the first time you use it. These will be cached locally after the initial download. Installing ATGDust locally is a one time setup step. Once it is in your local maven repository, this never has to be done again for future projects (unless it gets deleted from your maven repository).
Build sample code and test cases locally
- cd to the ATeam folder that was included with the ATGDust archive.
- If you are using a version of ATG other than 11.1, edit the pom.xml file and edit the atg.version value.
- Build the sample code, and execute the sample test cases by executing:
mvn clean install
For more information on ATGDust and the sample application and test cases included, refer to the PDF document that was in the ATGDust archive.
Developer Cloud Setup Steps
Create a Developer Cloud project
Log in to your devCS environment and create a new project. Name it atgbuilddemo.
On your local server, clone the GIT repository created with your project. This will be on the project tab of your devCS console.
To clone the repository, execute:
git clone https://username.username%40oracle.com@developer.us2.oraclecloud.com/developer41561-atgdemo/s/developer41561-atgdemo_atgbuilddemo_19815/scm/atgbuilddemo.git .
Replace the URL with the value you obtained from your devCS project.
The directory you clone this into will be called GIT_ROOT for this post.
Create maven settings.xml
- Create settings.xml in your MVN_HOME directory. This is typically in ~/.m2.
- Get the value of your devCS maven URL. Your devCS maven url is on the project screen in your devCS console
- Add the following, replacing the username and password with your devCS login info, and setting the URL to match your devCS maven repository URL. Do not change the repositoryId - leave it set to atgbuildrepo for this example.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
<server>
<id>atgbuildrepo</id>
<username>devcs-USERNAME</username>
<password>devcs-PASSWORD</password>
</server>
</servers>
<profiles>
<profile>
<id>default</id>
<repositories>
<repository>
<id>atgbuildrepo</id>
<name>ATGBuild Maven Repository</name>
<url>https://developer.us2.oraclecloud.com/profile/developer36822-ateamatgpoc3/s/developer36822-ateamatgpoc3_atgbuild/maven/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
</settings>
This file allows you to execute maven commands against your devCS environment, while automatically passing in login credentials.
Add ATG product libraries to Developer Cloud
Just like you did locally, you need to add ATG product libraries to your devCS environment so they are available to your code at build time.
Download sample script to push libraries to remove maven repo here:
- https://github.com/oracle/atg-commerce-iaas/blob/master/install-atglibs-maven-remote.sh
- Edit the provided install-atglibs-maven-remote.sh
- Set the REMOTE_URL to match your devCS maven repository URL.
- Save and execute install-atglibs-maven-remote.sh
Manually adding files to your devCS maven repository
You can look at the sample script provided, but the general format for adding files to a remote maven repository is:
mvn deploy:deploy-file \
-DgroupId=atg \
-DartifactId=webui-preview-1_0 \
-Dpackaging=jar \
-Dversion=${ATG_VERSION} \
-Dfile=${DYNAMO_ROOT}/WebUI/Preview/taglibs/webui-preview/lib/webui-preview-1_0.jar \
-DrepositoryId=${REPO_ID} \
-Durl=${REMOTE_URL}
Add ATGDust to your devCS maven repository
Just like you added ATGDust to your local maven repository, you need to add it to your devCS maven repository.
Instead of building the code in devCS, we are going to deploy the built code from the local environment to the devCS environment.
- Edit the pom.xml in the root of the ATGDust folder.
- At the end of the file, before the closing </project> tag, add the following, replacing the URL with the value of your devCS maven repository URL:
<distributionManagement>
<repository>
<id>atgbuildrepo</id>
<url>https://developer.us2.oraclecloud.com/profile/developer41561-atgdemo/s/developer41561-atgdemo_atgbuilddemo_19815/maven</url>
</repository>
</distributionManagement>
This tells maven where to send your built maven artifacts when you use the deploy command.
Now deploy ATGDust to your devCS maven repo by executing:
mvn deploy
You can verify the deployment by going to the maven menu item in your devCS console. You should see an item that looks like "com/…/1.3.1" Click on the 1.3.1, and you should see the ateamDust artifact.
Example:
Add sample project and test cases to devCS
- cd to the ATeam folder located in the root of the ATGDust tree.
- Execute "mvn clean" to get rid of build artifacts.
- cd back to the root of the ATGDust tree. Recurisvely copy the ATeam tree to the root of the atgbuilddemo GIT repository you cloned earlier - GIT_ROOT.
- The ATeam folder should be located in the root of your GIT_ROOT directory
- cd to GIT_ROOT/ATeam and edit pom.xml
- You need to add entries to the pom that tell maven where to pull dependencies from. Since this build will be executed in devCS, maven needs to know where in devCS the ATG product libraries you added earlier are located.
- Add the following to the pom, just before the closing </project> tag. Set the value of the 3 URL tags to match your devCS maven repo URL.
<repositories> <repository> <id>atgbuildrepo</id> <name>atgbuildrepo</name> <url>https://developer.us2.oraclecloud.com/profile/developer41561-atgdemo/s/developer41561-atgdemo_atgbuilddemo_19815/maven</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>atgbuildrepo</id> <name>atgbuildrepo</name> <url>https://developer.us2.oraclecloud.com/profile/developer41561-atgdemo/s/developer41561-atgdemo_atgbuilddemo_19815/maven</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </pluginRepository> </pluginRepositories> <distributionManagement> <repository> <id>atgbuildrepo</id> <url>https://developer.us2.oraclecloud.com/profile/developer41561-atgdemo/s/developer41561-atgdemo_atgbuilddemo_19815/maven</url> </repository> </distributionManagement> - Execute: git status
- You should see the ATeam folder listed as untracked.
- Execute: git add ATeam
- This adds the tree to GIT control.
- Execute: git commit -m "initial add"
- This commits the files
- Execute: git push
- This pushed your files to the remote devCS GIT repository. You should be asked to enter your devCS password.
- Go to the Code tab in your devCS console, and you should see the ATeam folder now.
Create devCS build
Go to the build tab in your devCS console and click new job. Name the job ATGTest.
- Set the JDK version to 7
- Go to source control tab. Select git.
- In the repository field, select your atgbuilddemo.git repo.
- Go to the build parameters menu and add ATG_ROOT, and DYNAMO_HOME.
- In the build parameters menu, click add parameter and select string parameter. Set values as follows:
- ATG_ROOT = ${DYNAMO_ROOT}
- DYNAMO_HOME = ${DYNAMO_ROOT}/home
- example:
- The value of DYNAMO_ROOT is provided by the devCS environment. It will point to an installation of ATG 11.1 patch 1 which is embedded in your build environment.
- Go to the build steps menu
- Click Add Build Step and select Maven 3
- Set the value of the POM FIle to ATeam/pom.xml
- We are doing things this way to demonstrate how to build a specific folder/module in your repo. You do not have to build a top level pom. You can break things up into smaller build units.
- Example:
- Click Save near the top right.
- Your code will automatically start building in a minute or two. The build screen you are on should automatically update once started.
Automatic building
The build is now configured to build in manual mode. You have to initiate a build through the devCS console.
If you want to make build automatic – for example when a commit of code occurs:
Go to the ATGTest build. Click configure.
Go to triggers
Select based on SCM polling schedule
Leave schedule blank. When you commit to the git repo, a build will be kicked off.
Example:
General Development Process
You can now work on your code locally. Whenever you commit to your git repository, the code is pushed to your devCS instance. If you leave the SCM Polling Schedule enabled, the build will occur automatically.
If you want to integrate development with an IDE, like Eclpise, just import an existing maven project.
In eclipse – select import -> Maven -> Existing Maven Projects
Click next
Navigate to the ATeam folder you pushed to devCS. This will be in the root of your git clone you created earlier.
Leave on defaults. All boxes should be checked. Click finish.
Your sample build should now be imported. You should have 3 projects, corresponding to the 3 pom files in the build. One top level, one for ATeamCommon, and one for ATeamWebApp.
You project is also linked up to your remote GIT repository now. You can commit and push from eclipse, and your changes will be added to your devCS environment.
