CI/CD Cheatsheet. Lars Fabian Tuchel Date: 18.March 2014 DOC:

CI/CD Cheatsheet Title: CI/CD Cheatsheet Author: Lars Fabian Tuchel Date: 18.March 2014 DOC:

Table of Contents 1. Build Pipeline Chart 5 2. Build. 6 2.1. Xpert.ivy. 6 2.1.1. Maven Settings 6 2.1.2. Project Configuration. 7 2.1.3. Xpert.ivy Dependencies. 7 2.1.4. JAR Dependencies.. 7 2.1.5. Jenkins Configuration. 8 2.2. JEE 10 2.2.1. EJB Module 10 2.2.2. EAR Application 11 2.2.3. JAR Dependencies 12 2.3. SQL Scripts.. 12 2.4. Documentation. 13 2.4.1. A Document s POM.. 13 3. Test. 15 3.1. Xpert.ivy.. 15 3.1.1. Unit Tests. 15 3.1.2. Integration Tests.. 19 3.1.2.1. Database Configuration. 19 3.1.2.2. Environment Configuration 20 3.1.3. Implement a Test Case 21 3.1.3.1. Run the Test Cases with PowerMockito 21 3.1.3.2. Setup the Environment Before the Test Execution.. 22 3.1.3.3. Provide a Clean Environment for the Tests. 22 3.1.3.4. Tear Down the Environment After the Tests Are Finished.. 23 3.1.3.5. Naming Convention 23 3.1.3.6. Known Limitations. 23 3.1.4. Build Trigger. 23 3.2. JEE 25 3.2.1. Unit Tests. 25 4. Quality Assurance. 27 4.1. Sonar Code Analyzis. 27 4.1.1. Maven Settings. 27 4.1.2. Xpert.ivy Project.. 27 4.1.3. JEE 28 4.1.3.1. Jenkins Plugin 28 5. Publish 29 5.1. Xpert.ivy.. 29 6. Deploy 30 6.1. Xpert.ivy Server.. 30 6.2. JEE Application Server. 30 6.2.1. Glassfish 30 Lars Fabian Tuchel 18.March 2014 2

6.2.2. JBoss. 31 6.2.3. Without settings.xml 33 7. Release.. 35 7.1. Prepare. 35 7.1.1. Xpert.ivy 35 7.1.2. Other Maven Projects.. 36 7.2. Packaging. 40 7.2.1. READMEs 42 7.2.2. Result 42 Lars Fabian Tuchel 18.March 2014 3

List of Figures 1.1. CI/CD Overview Diagram.. 5 2.1. Example Libraryconfig.. 7 2.2. Adding a Classpath Entry.. 8 2.3. Build Job Selection 9 2.4. SVN Configuration. 9 2.5. Maven Configuration 10 2.6. Artifactory Configuration 10 3.1. Declare an Eclipse Project as a Maven Project. 16 3.2. Configure the Project s Build Path. 17 3.3. Add a Library.. 18 3.4. Selecting a Library.. 18 3.5. Select the Current JUnit Version 19 3.6. Dependency for the test_base_ivy Project. 19 3.7. Test Project Build Parameter.. 23 3.8. Clean Pre Step. 24 3.9. Test Project Trigger. 25 4.1. MAVEN_OPTS for Sonar 27 4.2. Jenkins Sonar Plugin 28 7.1. Prepare Release for Xpert.ivy Projects Link.. 35 7.2. Xpert.ivy Release Configuration. 36 7.3. Activate the Release Plugin 38 7.4. Prepare Release for Default Maven Projects.. 39 7.5. Release Configuration for Other Maven Projects 39 7.6. Release Package Structure.. 40 Lars Fabian Tuchel 18.March 2014 4

1. Build Pipeline Chart The following diagram shows an overview about Continuous Integration/Delivery. Figure 1.1. CI/CD Overview Diagram Lars Fabian Tuchel 18.March 2014 5

2. Build 2.1. Xpert.ivy An Xpert.ivy project may be structured as follows: Project Name demo_ria common_ria demo_ria_test demo_webportal_jsf Description The main project of the application. This project will be packaged and installed. An additional ivy project which is required by the demo_ria project. It will be packaged and installed too. The ivy project containing the tests for the demo_ria project. It s not included in the release package. An additional module of the application it is packaged and may or may not be installed. 2.1.1. Maven Settings To build projects with maven you need to define the following configuration in your %M2_HOME%/ settings.xml: <settings> <servers> <server> <id>soreco_central</id> <username>jenkins</username> <password>******************</password> </server> <server> <id>soreco_snapshots</id> <username>jenkins</username> <password>******************</password> </server> </servers> <activeprofiles> <activeprofile>artifactory</activeprofile> </activeprofiles> <profiles> <profile> <id>artifactory</id> <properties> <!-- adapt this path with your ivy server installation path --> <ivy-server-path>c:\servers\xpert.ivy5</ivy-server-path> <!-- If true no svn files should be exported in the Ivy iar artifacts --> <skip-svn-in-export>true</skip-svn-in-export> <!-- If you are on UNIX replace the ";" with ":" --> <dataclassbuilderclasspath>${ivy-server-path}/lib/ivy/*;${ivy-server-path}/lib/shared/*;${java.home}/ lib/*;</dataclassbuilderclasspath> </properties> <repositories> <repository> <id>repo</id> <url>http://192.168.48.10/artifactory/repo</url> </repository> </repositories> <pluginrepositories> <pluginrepository> <id>repo</id> <url>http://192.168.48.10/artifactory/repo</url> </pluginrepository> </pluginrepositories> </profile> </profiles> </settings> Lars Fabian Tuchel 18.March 2014 6

2.1.2. Project Configuration The required configuration to build Xpert.ivy projects with Maven is available in the custom ParentIvyMavenPOM. Declare it in your pom.xml as follows: <?xml version="1.0" encoding="utf-8"?> <project xmlns="http://maven.apache.org/pom/4.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xsi:schemalocation="http://maven.apache.org/pom/4.0.0 http://maven.apache.org/mavenv4_0_0.xsd"> <modelversion>4.0.0</modelversion> <parent> <groupid>ch.ivyteam.ivy</groupid> <artifactid>parentivymavenpom</artifactid> <version>1.0</version> </parent> Instead of the version 1.0 you should allways declare the latest version. Additionally you ll have to declare at least the following details: <groupid>ch.soreco.demo</groupid> <artifactid>demo_ria</artifactid> <version>1.0.0.0</version> <packaging>iar</packaging> </project> 2.1.3. Xpert.ivy Dependencies Dependencies must be declared at two different locations. First in the Xpert.ivy libraryconfig: Figure 2.1. Example Libraryconfig And in your pom.xml: <dependencies> <dependency> <groupid>ch.soreco.demo.common</groupid> <artifactid>common_ria</artifactid> <version>[1.0.0.0,)</version> <type>iar</type> </dependency> </dependencies> 2.1.4. JAR Dependencies If your project depends on third pary libraries you will have to add the JAR file to your project (e.g. lib/ guava-16.0.1.jar) and then add a classpath entry to the projects.classpath file. Lars Fabian Tuchel 18.March 2014 7

<?xml version="1.0" encoding="utf-8"?> <classpath> <classpathentry kind="lib" path="lib/guava-16.0.1.jar"/> </classpath> Eclipse can add the classpath entry automatically. Figure 2.2. Adding a Classpath Entry 2.1.5. Jenkins Configuration You can build ivy projects with Maven on a Jenkins server by following the steps listed below: 1. Create a Build a maven2/3 project build job Lars Fabian Tuchel 18.March 2014 8

Figure 2.3. Build Job Selection 2. Define the path to your project s svn repository Figure 2.4. SVN Configuration 3. Define the clean deploy sonar:sonar as goals to be executed and make sure the MAVEN_OPTS - Djava.awt.headless=true and -Xmx2048m -XX:MaxPermSize=1024m are defined. If you don t use sonar you can let the latter be. Lars Fabian Tuchel 18.March 2014 9

Figure 2.5. Maven Configuration Note: The MAVEN_OPTS input field is only shown after you click the Advanced button. 4. This last step is optional. If you d like to have the build information published to the artifactory add a Deploy artifacts to Artifactory Post-build Action. You can deselect the Deploy maven artifacts option as the deployment is configured by defining the deploy goal in the step before and just select the Capture and publish build info option. Figure 2.6. Artifactory Configuration 2.2. JEE The project ear consists of one ore more modules. 2.2.1. EJB Module The easiest way to build a module is to just declare the parent_ejb_pom as parent pom and add the other required maven properties: <parent> <groupid>ch.soreco.common</groupid> <artifactid>parent_ejb_pom</artifactid> <version>1.0</version> </parent> Lars Fabian Tuchel 18.March 2014 10

<groupid>ch.soreco.demo</groupid> <artifactid>demo_service</artifactid> <version>0.0.4-snapshot</version> <packaging>ejb</packaging> If the parent POM doesn t fit your needs you can build a module by declaring the following configurations in your pom.xml. <project xmlns="http://maven.apache.org/pom/4.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://maven.apache.org/pom/4.0.0 http://maven.apache.org/xsd/ maven-4.0.0.xsd"> <modelversion>4.0.0</modelversion> <groupid>ch.soreco.demo</groupid> <artifactid>demo_service</artifactid> <version>1.0.0.0</version> <packaging>ejb</packaging> <dependencies> <dependency> <groupid>javax</groupid> <artifactid>javaee-api</artifactid> <version>6.0</version> <scope>provided</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-ejb-plugin</artifactid> <version>2.3</version> <configuration> <ejbversion>3.1</ejbversion> </configuration> </plugin> </plugins> </build> </project> 2.2.2. EAR Application To build the ear you must declare the modules in the ear s pom.xml. First add a dependency to the ear: <dependencies> <dependency> <groupid>ch.soreco.demo</groupid> <artifactid>demo_service</artifactid> <version>1.0.0.0</version> <type>ejb</type> </dependency> </dependencies> And then declare it in the maven-ear-plugin configuration: <build> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-ear-plugin</artifactid> <version>2.6</version> <configuration> <version>6</version> <defaultlibbundledir>lib</defaultlibbundledir> Lars Fabian Tuchel 18.March 2014 11

<modules> <ejbmodule> <groupid>ch.soreco.demo</groupid> <artifactid>demo_service</artifactid> </ejbmodule> </modules> </configuration> </plugin> </plugins> </build> </project> 2.2.3. JAR Dependencies If you declare a dependency in one of your modules it will automatically be included in the ear.. <dependency> <groupid>org.apache.commons</groupid> <artifactid>commons-lang3</artifactid> <version>3.3</version> </dependency> </dependencies> E.g. the dependency declared above will be packaged in the ear at demo_ear-0.0.1-snapshot.ear\lib \commons-lang3-3.3.jar. 2.3. SQL Scripts You may want to package your SQL scripts (update scripts, demo data etc.) so they are available in the repository and can later be included in the release package. Create a project in the following structure: project_folder +-- mssql +-- some.sql \-- other.sql +-- postgress \-- pom.xml As you see you basically just put all your sql scripts into the project folder and add a pom.xml. Which looks like the following: <project> <modelversion>4.0.0</modelversion> <groupid>ch.soreco.demo</groupid> <artifactid>demo_scripts</artifactid> <version>1.0.0.0</version> <packaging>pom</packaging> <build> <plugins> <plugin> <artifactid>maven-assembly-plugin</artifactid> <version>2.2.1</version> Lars Fabian Tuchel 18.March 2014 12

<configuration> <finalname>${project.name}-${project.version}</finalname> <appendassemblyid>false</appendassemblyid> <descriptorrefs> <descriptorref>sql-scripts</descriptorref> </descriptorrefs> </configuration> <dependencies> <dependency> <groupid>ch.soreco.common</groupid> <artifactid>base_assemblies</artifactid> <version>1.2</version> </dependency> </dependencies> <executions> <execution> <phase>package</phase> <goals> <goal>single</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project> 2.4. Documentation The documentation is written in Asciidoc [http://asciidoc.org] and parsed with Asciidoctor [http:// asciidoctor.org]. Those documents are written in plain text and can be exported to multiple output formats including pdf and html. We recommend the following structure for your documentation: ${project_name}_docs +-- InternalDoc +-- InternalDoc.asciidoc \-- pom.xml \-- PublicDoc +-- PublicDoc.asciidoc \-- pom.xml 2.4.1. A Document s POM The documentation consists of multiple asciidoc documents. For every document you must define a seperate pom.xml: <project xmlns="http://maven.apache.org/pom/4.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://maven.apache.org/pom/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelversion>4.0.0</modelversion> <parent> <groupid>ch.soreco.docs</groupid> <artifactid>docs-parent</artifactid> <version>1.0.1</version> </parent> <artifactid>internal-documentation</artifactid> <packaging>jdocbook</packaging> <properties> <docname>internaldoc</docname> </properties> <build> <plugins> <plugin> <groupid>org.jboss.maven.plugins</groupid> <artifactid>maven-jdocbook-plugin</artifactid> Lars Fabian Tuchel 18.March 2014 13

</plugin> <plugin> <groupid>org.asciidoctor</groupid> <artifactid>asciidoctor-maven-plugin</artifactid> </plugin> </plugins> </build> </project> As you see most configuration is done in the parent pom which is referenced with the project.parent property. Make sure the docname property is equal to the *.asciidoc file name (without the.asciidoc extension). E.g. the InternalDoc directory contains a InternalDoc.asciidoc file, so the docname property is InternalDoc. Note Your file should be UTF-8 encoded, so umlauts and the like are rendered correctly. Lars Fabian Tuchel 18.March 2014 14

3. Test 3.1. Xpert.ivy Tests for Xpert.ivy projects are created in an external project. Which follows the naming pattern {project_to_test}_test (e.g. demo_ria_test for tests of the demo_ria project). The automated Java tests should be put into the src_test folder. 3.1.1. Unit Tests To write the tests properly in the Xpert.ivy Designer you have to add JUnit to your build path. There are two possibilities to archive this: 1. Make sure you have the m2e extension installed in the Xpert.ivy Designer and that your project is declared as a Maven project. You can install the plugin from the eclipse plugin site http://download.eclipse.org/releases/indigo/ and then declare your project as a maven project as shown below: Lars Fabian Tuchel 18.March 2014 15

Figure 3.1. Declare an Eclipse Project as a Maven Project 2. Add the JUnit Library to your project s build path by following the steps bellow: Lars Fabian Tuchel 18.March 2014 16

Figure 3.2. Configure the Project s Build Path Click Add Library Lars Fabian Tuchel 18.March 2014 17

Figure 3.3. Add a Library Select JUnit and click Next. Figure 3.4. Selecting a Library You should use the current JUnit version so select JUnit4 and then click Finish. Lars Fabian Tuchel 18.March 2014 18

Figure 3.5. Select the Current JUnit Version Note This only works in the Project Explorer view and not in the Xpert.ivy Projects view. You can open it by clicking: Window > Show View > Project Explorer. All test dependencies for projects are declared in the parentivymavenpom including JUnit, Surefire and PowerMock [http://code.google.com/p/powermock]. So you just have to write your tests in the Designer and they will be executed when your project is built with maven. 3.1.2. Integration Tests For the integration tests we developed a framework. It s a ivy project which can checked out from the SVN at https://vcs.soreco.ch/svn/development/common/trunk/test_base_ivy/. You will need to add it as a dependency to your test project. Figure 3.6. Dependency for the test_base_ivy Project 3.1.2.1. Database Configuration For the environment a HSQL in-memory database is used. Define a persistence unit in your test project at src_test/meta-inf/persistence.xml. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" version="1.0" xsi:schemalocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/ persistence_1_0.xsd"> <persistence-unit name="demo_test"> Lars Fabian Tuchel 18.March 2014 19

<provider>org.hibernate.ejb.hibernatepersistence</provider> <class>ch.soreco.demo.entity.entityclass</class> <!-- And all your other entity classes --> <properties> <property name="javax.persistence.jdbc.driver" value="org.hsqldb.jdbcdriver" /> <property name="javax.persistence.jdbc.url" value="jdbc:hsqldb:mem:demo_test" /> <property name="javax.persistence.jdbc.user" value="sa" /> <property name="javax.persistence.jdbc.password" value="" /> </properties> </persistence-unit> </persistence> As you see the org.hsqldb.jdbcdriver is used and the entity classes the auto detection seems not to work so you ll have to list them manually. The name of the database and the persistence unit don t matter. Choose what you want. Xpert.ivy projects have this driver by default in their class path. But alas it s an old version (1.8.3) which doesn t support essential JPA functionalities. So if you want to run the tests outside of the maven build (e.g. directly in the IDE) you ll have to add a newer version 2.3 to your projects class path. Make sure the dependency is on top of your.classpath file, so the new version is loaded before the Xpert.ivy s driver. <?xml version="1.0" encoding="utf-8"?> <classpath> <!-- Overrides the default Xpert.ivy hsqldb 1.8.3 library to use in integration tests --> <classpathentry kind="lib" path="lib/hsqldb.jar"/> <classpathentry kind="src" path="src"/> <classpathentry excluding="**/*.ivyclass **/*.mod **/*.eventmappings **/ *.rddescriptor" kind="src" path="src_rd"/> <classpathentry excluding="**/*.ivyclass **/*.mod **/*.rddescriptor **/*.eventmappings **/ *.xhtml" kind="src" path="src_hd"/> [] </classpath> To ensure to right persistence.xml is used add the following configuration to your test project s pom: <build> <testresources> <testresource> <directory>src/meta-inf</directory> <excludes> <exclude>persistence.xml</exclude> </excludes> </testresource> <testresource> <directory>src_test</directory> <includes> <include>meta-inf/persistence.xml</include> </includes> </testresource> </testresources>. 3.1.2.2. Environment Configuration Your environment needs some configuration values. For this implement a class which extends the ch.soreco.test.base.environmen.environmentconfig interface. You will have to define the following values: Schema name: If you re using a schema you will have to define it. If no schema is in use just leave this value empty Persistence unit name: The name of the JPA persistence unit used for the tests. In this example it would be xrec_webportal_test Ivy server location: For the tests a valid Xpert.ivy installation is needed. It can be a designer or a server. Lars Fabian Tuchel 18.March 2014 20

public class DesignerEnvironmentConfig implements EnvironmentConfig { @Override public String getschemaname() { return "demo"; } @Override public String getpersistenceunitname() { return "demo_test"; } } @Override public String getivyserverlocation() { return "C:\\Path\\to\\an\\ivy\\server"; } To execute the tests in the maven build you can use the MavenEnvironmentConfig class as your environment configuration. In this case the Xpert.ivy server path will be read from the maven property ivy-server-path property of your pom.xml. This way we can include the integration test in our build process. The two other values you can pass as a parameter to the public constructor 3.1.3. Implement a Test Case Now that the environment is configured you can implement your test cases. We recommend to create an abstract class for your tests to extend according to the following example: 3.1.3.1. Run the Test Cases with PowerMockito The integration tests use Mockito along with PowerMock to mock the Xpert.ivy environment functionalities like logging, persistency access, session information and so forth. Therefore the test cases must be run with Power Mockito. In order to do this annotated your test cases as follows. @RunWith(PowerMockRunner.class) @PrepareForTest({Ivy.class}) If you need to mock additional any additional static classes you can put it in the @PrepareForTest parameter, but make sure not to forget the Ivy class. It s needed to setup the environment. @PowerMockIgnore({"javax.persistence.*", "org.hibernate.*", "ch.ivyteam.ivy.scripting.objects.*", "ch.ivyteam.ivy.scripting.objects.util.*", "ch.xpertline.xrec.webportal.entity.*" }) Hibernate faces some issues when working with PowerMock, which are related to its custom ClassLoader. To avoid them, the persistency related classes must be ignored by PowerMock and loaded with the default class loader. You must at least ignore the packages shown in the example above. Where +ch.soreco.demo.entity.* must be replaced with the package containing your entity classes. You can also list all fully qualified class names instead of packages. See http:// powermock.googlecode.com/svn/docs/powermock-1.3.5/apidocs/org/powermock/core/classloader/ annotations/powermockignore.html If you face an exeption that says something like: java.lang.classcastexception: ch.xpertline.xrec.webportal.entity.scenariogroup cannot be cast to ch.xpertline.xrec.w or: Lars Fabian Tuchel 18.March 2014 21

java.lang.linkageerror: loader constraint violation: when resolving method "ch.xpertline.xrec.webportal.entity.indiv xpertline/xrec/webportal/enums/ IndividualFieldTypeEnum;)V" the class loader (instance of org/powermock/core/classloader/ MockClassLoader) of the current class, ch/xpertline/xrec/webportal/business/synchronization/ IndividualFieldSynchronization, and the class loader (instance of sun/misc/launcher $AppClassLoader) for resolved class, ch/xpertline/xrec/webportal/entity/ IndividualField, have different Class objects for the type ld.settype(lch/xpertline/xrec/webportal/enums/ IndividualFieldTypeEnum;)V used in the signature Try to add the classes mentioned in the exception message to the PowerMockIgnore list. This will solve the issues in most cases. 3.1.3.2. Setup the Environment Before the Test Execution Before your integration tests are executed the environment must be set up. For this a @BeforeClass method is defined. public abstract class IntegrationTestCase { protected static EnvironmentManager env; @BeforeClass public static void setupenvironment() throws EnvironmentSetupException, IOException{ env = new EnvironmentManager(new MavenEnvironmentConfig("xhrm_xrec_webportal", "xrec_webportal_test")); env.setup(); } This will create a new in memory database for your schema in which the tests are executed. This is the simplest configuration but you can extend it with additional MockHandlers. Those are needed if you access some Xpert.ivy engine methods in your environment. Such a configuration could look something like this: public abstract class IntegrationTestCase { protected static EnvironmentManager env; private static IvyLoggerMockHandler logger; @BeforeClass public static void setupenvironment() throws EnvironmentSetupException, IOException{ List<MockHandler> mockhandlers = new ArrayList<MockHandler>(); logger = new IvyLoggerMockHandler(); mockhandlers.add(logger); mockhandlers.add(new JpaEntityManagerMockHandler()); mockhandlers.add(new SessionUsernameMockHandler()); env = new EnvironmentManager(new MavenEnvironmentConfig( "xhrm_xrec_webportal", "xrec_webportal_test"), mockhandlers); env.setup(); } There are some predefined mock handlers in the test_base_ivy project but you can define your own by extending the MockHandler interface. To understand the predefined ones have a look at the API documentation. If your using a custom set of mock handlers make sure to include the JpaEntityManagerMockHandler. It s required to setup the environment and your tests will fail otherwise. 3.1.3.3. Provide a Clean Environment for the Tests Test cases should be executed with the environment in a known state so a @Before method is defined which will clean it. @Before public void prepare(){ env.mock(); Lars Fabian Tuchel 18.March 2014 22

} env.clean(); As you can see additional to the cleaning the mocking stuff is executed too. This is because sometimes you will not receive the properly mocked classes after a previous test was executed therefore it s safer to mock everything again before a test is run. 3.1.3.4. Tear Down the Environment After the Tests Are Finished After the tests are finished the environment can be destroyed. Just define a @AfterClass method and execute the environment s destroy method and add additional custom tasks if any. @AfterClass public static void teardownenvironment(){ if(env!= null){ env.destroy(); } } 3.1.3.5. Naming Convention Make sure your Integration Test s class name ends with IT (e.g. ProjectSetupIT.java) so it s recognized by failsafe as an integration test during the maven build. 3.1.3.6. Known Limitations The framework is currently solely applicable for the standard JPA entity manager. This means Ivy.persistence().get(" ").createentitymanager() will return an actual entity manager for the in memory database whereas only Ivy.persistence().get(" ") will only return an empty mock. For more information about the integration test framework please refer to https://redmine.soreco.ch/ projects/common/wiki/howtoimplementautomaticxpertivyintegrationtests 3.1.4. Build Trigger You may want the tests executed when you build your project. This can be done by following the steps shown below: 1. Add a parameter to your test project build named PARENT_ARTIFACT Figure 3.7. Test Project Build Parameter Lars Fabian Tuchel 18.March 2014 23

2. Add a Execute Shell prestep again in the test project Figure 3.8. Clean Pre Step Add a rm -rf../your_ivy_dependency_project_name command for every ivy dependency. This will ensure current version of the artifacts is used. The unzip command will ensure that the artifact built in the actual build job excuted before is used as ivy dependency. Replace../demo_ria with the project s name. 3. Add a Trigger/call builds on other projects post step and select your test project. Set the PARENT_ARTIFACT parameter s value to the absolute path to the built *.iar file. Usally $WORKSPACE/ target/*.iar will work. Lars Fabian Tuchel 18.March 2014 24

Figure 3.9. Test Project Trigger Note This requires the Parameterized Trigger Plugin [https://wiki.jenkins-ci.org/display/ JENKINS/Parameterized+Trigger+Plugin] to be installed on the Jenkins server. If you re running your own instance make sure to install it. 3.2. JEE 3.2.1. Unit Tests To create unit test for EJB modules you must add a JUnit dependency to your pom.xml as follows: <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> Lars Fabian Tuchel 18.March 2014 25

<version>4.8.1</version> <scope>test</scope> </dependency> </dependencies> Then add the surefire plugin configuration: <project> <build> <pluginmanagement> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-surefire-plugin</artifactid> <version>2.16</version> </plugin> </plugins> </pluginmanagement> </build> </project> Now you can create your unit test in the src/test/java/ directory. They will be executed every time your module is built. Lars Fabian Tuchel 18.March 2014 26

4. Quality Assurance 4.1. Sonar Code Analyzis 4.1.1. Maven Settings Add the following four properites to you settings.xml: <profiles> <profile> <id>artifactory</id> <properties> <sonar.host.url>http://localhost:9000</sonar.host.url> <sonar.jdbc.username>xpertivy</sonar.jdbc.username> <sonar.jdbc.password>xpertivy</sonar.jdbc.password> <sonar.jdbc.url>jdbc:jtds:sqlserver://localhost/sonar;selectmethod=cursor;language=english</ sonar.jdbc.url> 4.1.2. Xpert.ivy Project To analyze your ivy project with Sonar just make sure to use at least the version 1.2.6.0 of the parentivymavenpom. You can run the analysis by executing the following command: mvn sonar:sonar If this doesn t work, try adding the sonar-maven-plugin to your pom.xml: <build> <plugins> <plugin> <groupid>org.codehaus.mojo</groupid> <artifactid>sonar-maven-plugin</artifactid> <version>2.2</version> </plugin> Important: The sonar analyzis can be memory intensive because a Xpert.ivy server is starte with an inmemory database so make sure to increase the heap size with the following MAVEN_OPTS: -Xmx2048m - XX:MaxPermSize=1024m Figure 4.1. MAVEN_OPTS for Sonar You can define them in the Jenkins job or as an environment variable. For more information about the Xpert.ivy Sonar plugin including an installation manual and download instructions please refer to https://redmine.soreco.ch/projects/common/wiki/sonar Lars Fabian Tuchel 18.March 2014 27

4.1.3. JEE As the EJB modules are basically just plain Java projects you just have to add the sonar plugin definition to your pom.xml: <build> <plugins> <plugin> <groupid>org.codehaus.mojo</groupid> <artifactid>sonar-maven-plugin</artifactid> <version>2.2</version> </plugin> You can run the analysis by executing the mvn sonar:sonar command. 4.1.3.1. Jenkins Plugin There is also a Sonar plugin for Jenkins. If said plugin is installed you can add a post build step (provided you have configured the plugin) to your build job: Figure 4.2. Jenkins Sonar Plugin However the Jenkins plugin doesn t work fully with our Xpert.ivy Sonar Plugin. If you use the post build step to analyze your ivy projects the Java sources in the project won t be analyzed at all. So this way of running the Sonar analyzis only works for EJB Modules and other pure Java projects. Lars Fabian Tuchel 18.March 2014 28

5. Publish This chapter will show how you can deploy the built projects to the artifactory. 5.1. Xpert.ivy First off: Don t use the Jenkins plugin it doesn t like \*.iar files. Just let maven do the job. You have to configure the distriubtion management for your project. This is done it the parentivymavenpom but if you have your own maven repository add the follwing to your pom.xml: <distributionmanagement> <repository> <id>soreco_central</id> <url>http://url/to/your/release/repository</url> </repository> <snapshotrepository> <id>soreco_snapshots</id> <url>http://url/to/your/snapshot/repository</url> </snapshotrepository> </distributionmanagement> The ids must match the ones configured in the settings.xml as described in chapter 2.2. In Jenkins configure your build job to run the mvn clean deploy. See Section 2.1.5, Jenkins Configuration. Lars Fabian Tuchel 18.March 2014 29

6. Deploy 6.1. Xpert.ivy Server 6.2. JEE Application Server You will have to differ the deployment configuration depending on the application server you want to deploy your application to. 6.2.1. Glassfish First: Make sure your glassfish server(s) allow remote deployment 1 and are running. Add a server config to your settings.xml. Both on your local environment (where you use the development server) and the jenkins server (where you use your demo server). settings.xml. <servers> <server> <id>demo_glassfish</id> <configuration> <cargo.hostname>[glassfish-host]</cargo.hostname> <cargo.remote.username>[glassfish-admin]</cargo.remote.username> <cargo.remote.password>*****</cargo.remote.password> </configuration> </server> And in you pom add the cargo-maven2-plugin configuration in a specific glassfish profile. pom.xml. <profiles> <profile> <id>glassfish</id> <build> <plugins> <!-- Glassfish Deployment --> <plugin> <groupid>org.codehaus.cargo</groupid> <artifactid>cargo-maven2-plugin</artifactid> <version>1.4.7</version> <executions> <execution> <id>glassfish-deploy</id> <phase>pre-integration-test</phase> <goals> <goal>redeploy</goal> </goals> </execution> </executions> <configuration> <container> <containerid>glassfish3x</containerid> <type>remote</type> </container> <configuration> <type>runtime</type> <properties> <cargo.server.settings>demo_glassfish</cargo.server.settings> 1 see https://blogs.oracle.com/quinn/entry/securing_adminstration_in_glassfish_server1 Lars Fabian Tuchel 18.March 2014 30

</properties> </configuration> <deployables> <deployable> <groupid>${project.groupid}</groupid> <artifactid>${project.artifactid}</artifactid> <properties> <name>${project.groupid}-${project.artifactid}</name> </properties> </deployable> </deployables> </configuration> <dependencies> <dependency> <groupid>org.glassfish.deployment</groupid> <artifactid>deployment-client</artifactid> <version>3.1.1</version> </dependency> </dependencies> </plugin> </plugins> </build> </profile> There are multiple things to remark: 1. The cargo.server.settings refers to the id configured in the settigns.xml. 2. The name property of the deployable is defined to deploy the ear/war application with a name like ch.soreco.demo-demo_ear. This will prevent the deployment of the same application in multiple versions at the same time. 3. The deployment will be done in the pre-integration-test phase after the ear is packaged. You can change this phase depending on your needs 2. Once you run the build make sure to add the -Pglassfish parameter (e.g. mvn clean install - Pglassfish). 6.2.2. JBoss Your JBoss server(s) must be running to be able to deploy your application too. Add another server config to your settings.xml. Again, on both environments. settings.xml. <servers> <server> <id>demo_jboss</id> <configuration> <cargo.hostname>[jboss-host]</cargo.hostname> <cargo.remote.username>[jboss-admin]</cargo.remote.username> <cargo.remote.password>*****</cargo.remote.password> </configuration> </server> In your pom add another cargo-maven2-plugin configuration in a different profile. pom.xml. <profile> <id>jboss</id> 2 For detailed information about the available lifecycle phases refer to https://maven.apache.org/guides/introduction/ introduction-to-the-lifecycle.html#lifecycle_reference Lars Fabian Tuchel 18.March 2014 31

<properties> <deployable.location>${project.build.directory}/deployment</deployable.location> <deployable.name>${project.groupid}-${project.artifactid}.${project.packaging}</deployable.name> </properties> <build> <plugins> <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-dependency-plugin</artifactid> <version>2.4</version> <executions> <execution> <id>copy</id> <phase>package</phase> <goals> <goal>copy</goal> </goals> <configuration> <artifactitems> <artifactitem> <groupid>${project.groupid}</groupid> <artifactid>${project.artifactid}</artifactid> <version>${project.version}</version> <type>${project.packaging}</type> <destfilename>${deployable.name}</destfilename> <outputdirectory>${deployable.location}</outputdirectory> </artifactitem> </artifactitems> </configuration> </execution> </executions> </plugin> <plugin> <groupid>org.codehaus.cargo</groupid> <artifactid>cargo-maven2-plugin</artifactid> <version>1.4.7</version> <executions> <execution> <id>jboss-deploy</id> <phase>pre-integration-test</phase> <goals> <goal>redeploy</goal> </goals> </execution> </executions> <configuration> <container> <containerid>jboss71x</containerid> <type>remote</type> </container> <configuration> <type>runtime</type> <properties> <cargo.server.settings>demo_jboss</cargo.server.settings> </properties> </configuration> <deployables> <deployable> <type>ear</type> <location>${deployable.location}/${deployable.name}</location> </deployable> </deployables> </configuration> <dependencies> <dependency> <groupid>org.jboss.as</groupid> <artifactid>jboss-as-controller-client</artifactid> <version>7.2.0.final</version> </dependency> </dependencies> </plugin> </plugins> </build> </profile> Again let s note some things: 1. The id property in the execution configuration refers to the id of the server configured in the settings.xml. Lars Fabian Tuchel 18.March 2014 32

2. With the JBoss container the name property does not work. The deployment will always use the build s final name instead. To ensure only one version is deployed, the ear is first copied using the naming pattern groupid-artifactid and afterwards the copied file is deployed. 3. The JBoss deployment will be executed in the pre-integration-test phase too. To deploy the ear on the JBoss server add the Pjboss parameter to the maven build command. 6.2.3. Without settings.xml If you can t access the settings.xml file you can also put the authentication information directly into your project s pom. Add two additional profiles to your pom.xml: pom.xml. <profile> <id>development</id> <activation> <property> <name>environment.type</name> <value>dev</value> </property> </activation> <properties> <jboss.host>[jboss-hostname]</jboss.host> <jboss.username>[jboss-admin]</jboss.username> <jboss.password>*****</jboss.password> <glassfish.host>[glassfish-hostname]</glassfish.host> <glassfish.username>[glassfish-admin]</glassfish.username> <glassfish.password>*****</glassfish.password> </properties> </profile> <profile> <id>ci-server</id> <activation> <property> <name>environment.type</name> <value>ci-server</value> </property> </activation> <properties> <!-- dito --> </properties> </profile> This will activate one of the profiles depending on the environment.type property s value. Our CI/CD server is configured to set this value to ci-server on your local environment add the property to your settings.xml. E.g. with the following configuration: pom.xml. <activeprofiles> <activeprofile>artifactory</activeprofile> </activeprofiles> <profiles> <profile> <id>artifactory</id> <properties> <environment.type>dev</environment.type> Back in the project s pom change the cargo deployment configuration as follows: pom.xml. Lars Fabian Tuchel 18.March 2014 33

<configuration> <container> <containerid>jboss71x</containerid> <type>remote</type> </container> <configuration> <type>runtime</type> <properties> <cargo.hostname>${jboss.hostname}</cargo.hostname> <cargo.remote.username>${jboss.username}</cargo.remote.username> <cargo.remote.password>${jboss.password}</cargo.remote.password> </properties> </configuration> respectively pom.xml. <configuration> <container> <containerid>glassfish3x</containerid> <type>remote</type> </container> <configuration> <type>runtime</type> <properties> <cargo.hostname>${glassfish.hostname}</cargo.hostname> <cargo.remote.username>${glassfish.username}</cargo.remote.username> <cargo.remote.password>${glassfish.password}</cargo.remote.password> </properties> </configuration> Warning This way is not recommended as it will make your authentication public for every one who can access your source code. Lars Fabian Tuchel 18.March 2014 34

7. Release 7.1. Prepare 7.1.1. Xpert.ivy You can automatically prepare a release in Jenkins. This will create a tag in the SVN repository and change the version number in both the pom.xml and the libraryconfig file in the trunk and the created tag. Note that the tag will be created from the revision used in the selected build however the pom.xml and libraryconfig adaptions will be done in the HEAD revision. So all revisions between the HEAD and the tagged one will still have the old version configured in the two files. In a build you can click the Prepare release link. Figure 7.1. Prepare Release for Xpert.ivy Projects Link You will have to enter a release version number. The tag url and the trunk version will be computed automatically but you can enter them manually anyway. Lars Fabian Tuchel 18.March 2014 35

Figure 7.2. Xpert.ivy Release Configuration You will see an output as shown below: PREPARING THE PRE_RELEASE release-tag: tagging revision 3950 to https://vcs.soreco.ch/svn/playground/ CICD_Cheatsheet/tags/demo_webportal_jsf/1.0.0 working in /usr/share/tomcat6/.jenkins/jobs/demo_webportal_jsf/workspace CHANGING THE TAG AND TRUNK VERSIONS SVN checkout trunk head and release-tag Changing the Tag POM Version to 1.0.0 Changing the Tag ivy library version based on 1.0.0 Changing the Trunk POM Version to 1.1.0-SNAPSHOT Changing the trunk ivy library version based on 1.1.0-SNAPSHOT SUMMARY A new release tag has been created at: https://vcs.soreco.ch/svn/playground/ CICD_Cheatsheet/tags/demo_webportal_jsf/1.0.0 The release Tag pom version is 1.0.0 The Project Trunk HEAD revision pom version is 1.1.0-SNAPSHOT As the trunk project's version number has been changed, it is of good practice to build the project again. If the build is not automatically triggered by the SVN changes, you should launch a build manually. 7.1.2. Other Maven Projects With the M2 Release Plugin [https://wiki.jenkins-ci.org/display/jenkins/m2+release+plugin] you can release standard maven projects (including EJB Modules and EARs). However this plugin lets you only release the latest trunk version and not a specific build. The release plugin requires some configuration: 1. Declare the svn connection by adding the following configuration to your project s pom.xml. The scm:snv: prefix is required, you can just change the URL. <scm> Lars Fabian Tuchel 18.March 2014 36

<connection>scm:svn:https://url/to/your/project/trunk</connection> </scm> 2. Define the maven repositories <distributionmanagement> <repository> <id>soreco_central</id> <url>http://192.168.48.10/artifactory/labs-release-local</url> </repository> <snapshotrepository> <id>soreco_snapshots</id> <url>http://192.168.48.10/artifactory/labs-snapshot-local</url> </snapshotrepository> </distributionmanagement> If you re using the parent_ejb_pom you don t need to add this configuration. 3. Configure the tag URL and name format. This time no prefix is required in front of the URL. <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-release-plugin</artifactid> <version>2.5</version> <configuration> <tagbase>https://url/to/your/project/tags</tagbase> <tagnameformat>@{project.version}</tagnameformat> </configuration> </plugin> </plugins> </build> You should always use the same tagnameformat as defined above to match the our naming conventions. If you re using the parent_ejb_pom you don t have to add this whole configuration just add the following property: <properties> <tagurl>https://url/to/your/project/tags</tagurl> </properties> You will have to activate the plugin for your build job by activating the following checkbox in the Build Environment job configuration. Lars Fabian Tuchel 18.March 2014 37

Figure 7.3. Activate the Release Plugin To release a project just click the Perform Maven Release link on your project build job s overview page: Lars Fabian Tuchel 18.March 2014 38

Figure 7.4. Prepare Release for Default Maven Projects In the following form you will have to enter a release and a development version where the release version will be the tagged one and the development version the one in the trunk. Figure 7.5. Release Configuration for Other Maven Projects This will create a tag in the svn, increment the version in the pom, both for the tag and the trunk, and deploy the tagged version to the repository. Lars Fabian Tuchel 18.March 2014 39

7.2. Packaging Figure 7.6. Release Package Structure A release package may consist of multiple parts: 1. Xpert.ivy projects packaged as *.iar. 2. The application server part including ears and wars. 3. The documentation as pdf and html Lars Fabian Tuchel 18.March 2014 40

4. Additional database scripts. Everyting you need is create another pom.xml which has the following structure: <project> <modelversion>4.0.0</modelversion> <groupid>ch.soreco.demo</groupid> <artifactid>demo_package</artifactid> <version>1.0.0.0</version> <packaging>pom</packaging> <name>demo-dist-std</name> Fist declare the usual maven stuff about your project package. The name attribute follows the naming convention in the figure above and will be used for the zip s file name. <build> <plugins> <plugin> <artifactid>maven-assembly-plugin</artifactid> <version>2.2.1</version> <configuration> <finalname>${project.name}-${project.version}</finalname> <appendassemblyid>false</appendassemblyid> <descriptorrefs> <descriptorref>ivy-package</descriptorref> </descriptorrefs> </configuration> <dependencies> <dependency> <!-- Entry needed to enable jdocbook unzipping --> <groupid>org.jboss.maven.plugins</groupid> <artifactid>maven-jdocbook-plugin</artifactid> <version>2.3.8</version> </dependency> <dependency> <groupid>ch.soreco.common</groupid> <artifactid>base_assemblies</artifactid> <version>1.2</version> </dependency> </dependencies> <executions> <execution> <phase>package</phase> <goals> <goal>single</goal> </goals> </execution> </executions> </plugin> </plugins> </build> The next bit of configuration is used to refer the base_assemblies project. As you see the ivy_package assembly descriptor is used to define how the project package is structured. <dependencies> <dependency> <groupid>ch.soreco.demo</groupid> <artifactid>demo_ria</artifactid> <version>${project.version}</version> <type>iar</type> </dependency> <dependency> <groupid>ch.soreco.demo</groupid> <artifactid>demo_webportal_jsf</artifactid> <version>1.1.0-snapshot</version> <type>iar</type> </dependency> <dependency> <groupid>ch.soreco.demo.docs</groupid> Lars Fabian Tuchel 18.March 2014 41

<artifactid>public-documentation</artifactid> <version>${project.version}</version> <type>jdocbook</type> </dependency> <dependency> <groupid>ch.soreco.demo</groupid> <artifactid>demo_scripts</artifactid> <version>${project.version}</version> <type>zip</type> </dependency> <dependency> <groupid>ch.soreco.demo</groupid> <artifactid>demo_ear</artifactid> <version>${project.version}</version> <type>ear</type> </dependency> </dependencies> </project> Then you only have to add all of your dependencies: Xpert.ivy projects, EARs, SQL scripts and the documentation. All the maven artifacts will be included in the release package. 7.2.1. READMEs If you have a README file or other plain text files (like a change log). Which aren t generated with asciidoc you can add them to your package project s base directory. Files named README will be in the root directory of the zip other *.txt files will be added to the documents directory. E.g. the demo package project folder contains three files: pom.xml, README.txt and changelog.txt. The two txt files will also be included in the release package as you see below. 7.2.2. Result The following zip is created for the demo project: demo-dist-std-1.0.0.0.zip -- README.txt -- common_ria-1.0.0.0.iar -- demo_ria-1.0.0.0.iar \-- lib \-- guava-16.0.1.jar -- demo_webportal_jsf-1.1.0-snapshot.iar +-- application server \-- demo_ear-1.0.0.0.ear +-- demo_service-1.0.0-snapshot.jar \-- lib \-- commons-lang3-3.3.jar +-- documentation -- changelog.txt +-- html_single \-- PublicDoc.html \-- pdf \-- PublicDoc.pdf \-- scripts +-- mssql \-- create_testdata.sql \-- postgres \-- create_testdata.sql Lars Fabian Tuchel 18.March 2014 42