Installer Maven Projects

At Yale, an "Installer" is a Maven project that runs an Ant script to copy WAR or EAR files into a JBoss or Tomcat application directory and configure Datasources and application parameters. It is typically checked into Subversion under the project that builds the WAR or EAR it deploys. Jenkins uses Maven and the Installer project to deploy to DEV, TEST, and PROD.

An Installer separates sensitive parameters from the WAR or EAR artifact created by the developers. These parameters may include database URLs, userids, and passwords, AD service accounts, LDAP URLs, and so on.

The developer works on the "trunk" project to edit application source and produce JAR, WAR, and EAR artifacts. There is a single version of the resulting artifact which must be tested on the developer desktop, then deployed to DEV and TEST before going into production. It is important that the artifact not have to be rebuilt between testing and production, and it is important the that Subversion source not contain any sensitive information like passwords. In fact, the developer typically is not given access to production passwords.

So the Installer project externalizes the parameters that are different in the different environments (desktop, DEV, TEST, and prod) and allows production services to insert passwords during deployment that the developer doesn't have and that are neither in the source nor the artifact.

The Installer uses an Ant build.xml file and Ant *.properties files. Non sensitive but environment specific properties are checked into the Installer project source as install-DEV.properties, install-TEST.properties, and install-PROD.properties. These files contain the URL for the database and maybe the userid, but they never contain the password. The DEV properties will point to the development database instance, and so on.

Each Jenkins deploy job (DEV, TEST, and PROD deploy jobs) has a parameter screen that is displayed before the job is submitted. The developer gets to fill in parameters for the DEV deploy, but production services has to fill in parameters for TEST and PROD. This screen contains the password and may contain the userid. When the Jenkins job is submitted, the Installer project is checked out of subversion to a directory on the target machine, the screen parameters are used to create an install.properties file, and the Ant build.xml is executed. The generated properties.xml is processed first, then the properties-DEV.xml (or other environment file) is merged in. The Ant rule is that the first property value encountered wins and subsequent definitions of the same property are ignored.

Build.xml files for Installer projects have a Tomcat version and a JBoss version. The Tomcat version creates a context.xml file that is copied to the /conf/catalina/localhost directory inside the Tomcat installation. In Tomcat, the context.xml can define datasources for the application and can provide the JNDI environment variables. JBoss has a different configuration syntax, so that version of build.xml creates a xxxname-ds.xml file that defines the Datasource, and a separate XML file that provides parameters to a JBoss utility service that stores the parameters from the XML file into the JBoss JNDI environment storage. These two versions of build.xml accomplish exactly the same thing using the two different versions of configuration syntax in the two J2EE containers.

To accomplish the same thing on your desktop, you check out the Installers project into your Eclipse workspace. You then manually create your own "install.properties" file in that project directory with the property names and values that would have been typed into the Jenkins parameter screen and used to generate an install.properties file in a Jenkins job. Since you are not running Jenkins, you build the file yourself. If the Jenkins DEV install job exists, copy over the parameter names from the screen. If you are creating a new project and there is no Jenkins job yet, create the parameter names you expect that Jenkins will want to populate when the job is created. Look at existing DEV install jobs for examples of the sort of parameters to put here.

A typical install.properties file begins like this:

target.environment=DEV
artifact.version=2.0.6-SNAPSHOT
tomcat.deploy.dir=/appservers/apache-tomcat-7.0.26
db.url=jdbc:oracle:thin:@rick.its.yale.edu:1521:ACS3
db.username=yyyyy
db.password=xxxxxxx

The "target.environment" property tells Ant which additional properties file to merge in (install-DEV.properties when "DEV" is specified as in this case). The "artifact.version" matches the version number of the WAR or EAR file specified in your application POM and during desktop development will always be a -SNAPSHOT of the next release number. The tomcat.deploy.dir is the location on your machine of the Tomcat into which the application is to be installed (or jboss.deploy.dir for a JBoss).

If something in Eclipse is runnable, then when you right click on the file you get a Run As ... option in the menu. You can run applications, JUnit tests, and Maven pom.xml files. You can also create a Run Configuration which saves specific run parameters (what Java rutime to use, what parameters to pass, etc. For a Maven POM, you can select a specific installed version of Maven to run. When you develop this type of application, it is useful to configure two Maven Run Configurations, one that corresponds on your desktop to what Jenkins does with a Trunk Build job (a "mvn install" on the top pom.xml for the application) and a second Eclipse Maven Run Configuration for the Installer that copies the WAR or EAR generated by the previous step over to the Tomcat or JBoss and builds all the configuration files. When Jenkins runs the Trunk Build it stores the WAR or EAR in the Yale Artifactory repository, but when you run these steps on your desktop the WAR or EAR is just stored in your .m2/repos in your personal home directory.