Fork me on GitHub

n. Slang a rough lawless young Kuali developer.
[perhaps variant of Houlihan, Irish surname]
kualiganism n

Blog of an rSmart Java Developer. Full of code examples, solutions, best practices, et al.

Sunday, February 19, 2012

Mavenized KFS Distribution Available on GitHub

Introduction

I have been getting a good deal of feedback lately about the Convert Your KFS Distribution to Maven post. I was really hoping the repository of the source would be made available publicly, but it was not. I decided that with some refinements I had been planning for the Maven/KFS distribution, I would release the next distribution publicly on GitHub.

Now I have done so. You may not reach my new-and-improved Maven distribution of KFS 4.1.1 on GitHub. The official kfs-maven site can be found here.

Straight-away, you will notice that there are 4 sub-projects (kfs-assembly, kfs-parent, kfs-common, and kfs-public). I will explain each.

kfs-assembly

In Maven, there is this concept of an assembly which is like an artifact counterpart. If you've worked with maven, you'll know that artifacts are the products of a release or build. These are usually jars or wars. If you have a non-software piece like configuration or help files, you may distribute these as assemblies. KFS happens to have several configuration and help files available which are placed into an assembly. I will explain how to use this later.

kfs-common

This is a common POM. The Kuali Foundation is now starting to make available common POMs that can be used to aggregate plugin configuration and dependencies to each of its umbrella'd projects for consistency. This will help make projects more manageable, but it will also make them easier to get started. No more hassle of trying to figure out what's the best way. It's already provided for you.

kfs-public

I will talk about this more in a later post. For now, I will explain it as the public POM. It is for non-Kuali Foundation projects. Who cares about these? Well, institutions should care. Your project is not part of the Kuali Foundation. Maybe someday it will be, but for now, it is not. There are some settings like CI information, site deployment details, and urls that are not where you want your project to be directed. I don't mean usernames and passwords. What I mean is that kuali-common is configured specifically for the Kuali Foundation. If you want to build a project that makes use of the plugin configuration, dependencies, and properties of the kuali-common POM to get your project started easier, you will halso have to get all the Kuali Foundation configuration with it. The kuali-public POM let's you get all of that without the messy Kuali Foundation configuration your project doesn't need.

kfs-parent

This is the REAL maven distribution. It's a lot leaner than the previous distribution I had described in the Convert Your KFS Distribution to Maven post. I have gotten rid of all the ant stuff. There is no more of that.

Getting Started

In case you wanted to get started and use distribution, here's what you need to do.

Check Out the Project

% git clone git@github.com:r351574nc3/kfs-maven.git
% cd kfs-maven

Install the Assembly

% cd kfs-assembly
% mvn clean install

Install the Common POM

% cd kfs-common
% mvn clean install

Package the war file

Now, you're probably familiar with how things used to be done with the kfs-build.properties. I am going to outright recommend this file primarily be used for credentials and user-specific overrides. That is, developers should probably make the most use of this because they are they only one's with user-specific overrides (like home directory, etc...). Server environments shouldn't have anything of the sort, so you would expect that a server environment will only have credentials. Further, server environments are probably going to be packaged and built using something like Jenkins. This means, any necessary overrides that are not credentials will probably be provided through Jenkins.

If you are a developer, you already have your kfs-build.properties. You won't need to change a thing. Just use what you already have and run the following:
% mvn -Pmysql clean install

Now I am going to demonstrate what you would typically be doing to deploy to a server environment.
CONFIGDIR=$HOME/kuali/main/dev mvn -Pmysql clean install \
-Dant.project.name=kfs \
-Duse.p6spy=false \
-Duse.quartz.scheduling=true \
-Duse.dd.schema.validation=false \
-Dtests.includes=**/*Test.java \
-Dappenders="INFO, LogFile, StdOut" \
-Dexternal.config.directory=$CONFIGDIR \
-Dbase.security.directory=$CONFIGDIR/security \
-Dbase.settings.directory=$CONFIGDIR/settings \
-Dbase.logs.directory=$CONFIGDIR/logs \
-Dbase.work.directory=$CONFIGDIR/work \
-Ddatasource.username=KUALIUSER \
-Dmysql.datasource.url=jdbc:mysql://localhost:3306/KUALIUSER \
-Doracle.datasource.url=jdbc:oracle:thin:@localhost:1521:XE \
-Dmail.relay.server= \
-Dbatch.mailing.list= \
-Dincident.mailing.list= \
-Ddeploy.local.rice.server=false \
-Drice.standalone=false \
-Drice.server.datasource.username=KUALIUSER \
-Drice.kew.xml.pipeline.lifecycle.enabled=true \
-Drice.dev.mode=false \
-Dtomcat.version=6

This will produce a kfs-dev.war file in kfs-parent/web/target

Details

Ok. What Changed?

Among the refinements, the huge one was the kfs-common POM file. It takes advantage of the kuali-common POM file as a parent.
<parent<
  <groupId>org.kuali.pom</groupId>
  <artifactId>kuali-common</artifactId>
  <version>1.0.31</version>
</parent>
What we get from this are all the plugin configurations that are at home with the Kuali Foundation including things like checkstyle, the graph plugin, findbugs configuration, etc... It also allows us to leave our KFS specific plugins with in the kfs-common with things like properties and profiles. If you look at the kfs-common POM, it is 2270 lines long. Sure, that's huge, but when we care mostly about what we want to override, it's not so bad. Now our POM is much simpler in kfs-parent.
<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.kuali.pom</groupId>
    <artifactId>kfs-common</artifactId>
    <version>0.0.1</version>
  </parent>
  <groupId>org.kuali.kfs</groupId>
  <artifactId>kfs-parent</artifactId>
  <packaging>pom</packaging>
  <name>kfs</name>
  <inceptionYear>2005</inceptionYear>
  <version>4.1.1-maven-SNAPSHOT</version>
  <description></description>
  <url>http://${kuali.site.hostname}/kfs/${project.version}</url>
  
  <modules>
    <module>core</module>
    <module>config</module>
    <module>module</module>
    <module>rice</module>
    <module>web</module>
  </modules>
</project>
Pretty nice, right? Not cluttered by all that other stuff. All that is described here is the modules. Now that's great. Much cleaner. If you take a look at the modules, you'll see that they have much more specific information which is good. That is also due to the kfs-common POM.

Profiles

You've probably been wondering for a while now what the whole -Pmysql thing is about. That's another improvement. There are profiles for what you want.
Mysql You can build KFS to use mysql or oracle. There is no profile for oracle though. Oracle is the default. You merely specify if you want to use mysql.
dev,tst,cnv,cfg,prd,stg These are environments. You can specify an environment you want to build with, and it will use the appropriate ${environment}-build.properties file.
cas You can build with CAS or without. It defaults to without, but use -Pcas and now it will build with cas. It's fakecas though.
p6spy Use this to flip on/off p6spy.
production Are you building for production? What to stop using those silly test urls? This is for you.
standalone Sets all your properties to work with rice standalone. Of course, you need to fix the URLs. We can't read minds afterall.
coeus Turn on coeus integration. No urls, but some spring beans need to be activated. This will do that for you.

Artifacts

kfs-config-4.1.1-maven-SNAPSHOT-external.zip
kfs-config-4.1.1-maven-SNAPSHOT-src.tar.bz2
kfs-config-4.1.1-maven-SNAPSHOT-tests.jar
kfs-core-4.1.1-maven-SNAPSHOT-sources.jar
kfs-core-4.1.1-maven-SNAPSHOT-tests.jar
kfs-core-4.1.1-maven-SNAPSHOT.jar
kfs-module-endow-4.1.1-maven-SNAPSHOT-sources.jar
kfs-module-endow-4.1.1-maven-SNAPSHOT-tests.jar
kfs-module-endow-4.1.1-maven-SNAPSHOT.jar
kfs-module-external-4.1.1-maven-SNAPSHOT-sources.jar
kfs-module-external-4.1.1-maven-SNAPSHOT-tests.jar
kfs-module-external-4.1.1-maven-SNAPSHOT.jar
kfs-module-4.1.1-maven-SNAPSHOT-tests.jar
kfs-rice-4.1.1-maven-SNAPSHOT-sources.jar
kfs-rice-4.1.1-maven-SNAPSHOT-tests.jar
kfs-rice-4.1.1-maven-SNAPSHOT.jar
kfs-parent-4.1.1-maven-SNAPSHOT-tests.jar
kfs-dev.war
kfs-dev-sources.jar
kfs-dev-tests.jar

kfs-dev.war

This is the main application artifact. This is what gets deployed to your tomcat/jetty/JBoss appserver.

kfs-config-4.1.1-maven-SNAPSHOT-external.zip

KFS has this concept of external configurations. This is a space where the application has read/write access for batch input/output files, logs, and of course security credentials. You wouldn't normally build these things into your application space because it becomes a security and auditing issue. Normally, you would deploy this to the same system as your application and unzip it there. If you look inside, it should be something like this:

Archive: /Users/leo/kfs-config-external-4.1.1-maven-SNAPSHOT-external.zip
Length Date Time Name
-------- ---- ---- ----
0 02-18-12 12:13 kuali/
0 02-18-12 12:13 kuali/main/
0 02-18-12 12:13 kuali/main/dev/
0 02-18-12 12:13 kuali/main/dev/security/
0 02-18-12 12:13 kuali/main/dev/security/kfs/
0 02-18-12 12:13 kuali/main/dev/settings/
0 02-18-12 12:13 kuali/main/dev/settings/kfs/
0 02-18-12 12:13 kuali/main/dev/work/
0 02-18-12 12:13 kuali/main/dev/work/kfs/
0 02-18-12 12:13 kuali/main/dev/work/kfs/attachments/
0 02-18-12 12:13 kuali/main/dev/work/kfs/attachments/pending/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ar/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/bc/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cab/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cam/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cg/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/coa/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ec/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/fp/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/gl/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ld/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/pdp/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/purap/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/sys/
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/vnd/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ar/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ar/customer/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ar/invoiceWriteoff/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/cm/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/cm/barcode/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/collectorXml/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/correctionProcess/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/originEntry/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/correctionProcess/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/enterpriseFeed/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/originEntry/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/bankFederalReserve/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentExtract/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentImport/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentLoadSummary/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/purap/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/purap/electronicInvoice/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/loaded/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/pending/
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/problems/
0 02-18-12 12:13 kuali/main/dev/work/kfs/temp/
2006 02-18-12 12:13 kuali/main/dev/security/kfs/security.properties
5528 02-18-12 12:13 kuali/main/dev/settings/kfs/log4j.properties
0 02-18-12 12:13 kuali/main/dev/work/kfs/attachments/pending/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ar/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/bc/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cab/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cam/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/cg/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/coa/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ec/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/fp/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/gl/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/ld/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/pdp/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/purap/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/sys/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/reports/vnd/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ar/customer/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ar/invoiceWriteoff/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/cm/barcode/placeholder.txt
3610 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/allTransDifferentCC.xml
3580 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/allTransSameCC.xml
1830 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/badChartData.xml
679 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/badXmlFile.xml
2720 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/fieldsInWrongOrder.xml
18775 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/transactions1.xml
3965 02-18-12 12:13 kuali/main/dev/work/kfs/staging/fp/procurementCard/transactionWithExtraFields.xml
3472 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/collectorXml/gl_collector1.xml
3434 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/collectorXml/gl_collector2.xml
10242 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/collectorXml/gl_collector3.xml
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/correctionProcess/placeholder.txt
187 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_001.data
45 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_001.recon
137632 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_002.data
56 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_002.recon
137632 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_003.data
25 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_003.recon
297143 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_004.data
56 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_004.recon
1927409 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_005.data
60 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_005.recon
1927409 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_006.data
49 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_006.recon
60 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_007.recon
187 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_008.data
839 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/enterpriseFeed/entp_test_file_readme.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/gl/originEntry/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/correctionProcess/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/enterpriseFeed/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/ld/originEntry/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/bankFederalReserve/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentExtract/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentImport/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/pdp/paymentLoadSummary/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/purap/electronicInvoice/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/loaded/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/pending/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/staging/workflow/problems/placeholder.txt
0 02-18-12 12:13 kuali/main/dev/work/kfs/temp/placeholder.txt
-------- -------
4488630 114 files

The reason for the kuali/main/dev is that this is where the application was configured to put the external config at build time. Notice, I did not give an exact path. The reason is because this is intended to go into the home directory of the user running the appserver (tomcat). If I used the ${user.home} path, the paths in the zip would show the build user's home instead which is not what I want; therefore, I made it relative, so it may be deployed within the user's directory. You don't have to do this though. It is just a matter of changing the external config directory's path like I did above to put it wherever.

Conclusion

The new mavenization is cleaner and easier to use. It's also easier to modify. I'll discuss that in my next post. I'll walk through overlays and customizing things like properties. In fact, at the time that I am writing this, there is a kfs-overlay-reference project on github. The trouble is, nothing is there yet. My next post will be specifically about that though, so of course, it will be available soon.

No comments:

Post a Comment