CBF - Community Build Framework
Author and Maintainer: Unlicensed user
Contributors: Unlicensed user,Unlicensed user
Latest Version: 3.7.0 - Pentaho 3.7 compatible
Latest Update: December 13th, 2010
New Version available
Released version 3.7.0 compatible with pentaho 3.7
Table of contents
- 1 Table of contents
- 2 Concepts
- 2.1 Overview
- 2.2 Description
- 2.3 Configuration files
- 2.4 Tokens
- 3 CBF execution and available targets
- 3.1 Building and executing
- 3.2 Deploy
- 3.3 Debug
- 3.4 Ctools
- 4 Download
- 5 Old versions
- 6 FAQ
- 7 Changelog
Concepts
Overview
Community Build Framework (CBF) is an ant build.xml file script and alternate way to setup and deploy Pentaho based applications. Focused on a multi-project/ multi-environment scenario, here are the main characteristics:
Ability to switch from totally different projects on the fly
Supports multiple environments (eg: development, production, worker1, worker2...)
No changes to the original files that could get overwritten in a upgrade
Supports multiple platform versions
Version 2.0 support for jboss and tomcat (the latest only for platform >= 1.7)
Version 2.1/3.x supports tomcat only (as imposed by Pentaho's dev build)
Simplifies version upgrades
Debug-friendly
VCS-friendly
Support all kinds of different customization in different projects, from using a different databases to different security types.
Supports patches to the source code for fine-grain customization
Supports deploy to local/remote machines
OS independent
Description
Project pentaho already has a good dev_build.xml ant script, but it wasn't enough for my needs, since I needed to change the svn sources in order to configure a solution. So I built my own structure, and its like this:
Directory layout and code checkout
MyProjectDir
|-- build.xml
|-- pentaho
| |-- bi-platform-api
| |-- bi-platform-appserver
| |-- bi-platform-assembly
| |-- bi-platform-assembly-open
| |-- bi-platform-build
| |-- bi-platform-engine-core
| |-- bi-platform-engine-security
| |-- bi-platform-engine-services
| |-- bi-platform-legacy
| |-- bi-platform-plugin-actions
| |-- bi-platform-plugin-services
| |-- bi-platform-repository
| |-- bi-platform-sample-data
| |-- bi-platform-sample-solution
| |-- bi-platform-scheduler
| |-- bi-platform-test-foundation
| |-- bi-platform-ui-foundation
| |-- bi-platform-util
| |-- bi-platform-web
| |-- bi-platform-web-portlet
| |-- bi-platform-web-servlet
| |-- dummy-jre
| |-- mantle
| `-- test-solutions
|-- project-client
| |-- patches
| | |-- pentaho
| | `-- target-preconfiguredinstall
| `-- solution
|-- target-build
`-- target-dist
pentaho/* directories are cheched out from svn, and for me are read-only. Feel free to use any svn client you want; I usually work in linux, or on a windows machine with cygwin, so I use the original client. I checked out the sources with:
$ svn co svn://source.pentaho.org/svnroot/bi-platform-v2/branches/3.0
If you are under a proxy you can use http:// instead of svn:// . I'm currently using version 3.5 from trunk. For earlier releases please check earlier CBF versions
target-/* directories are the ones generated by the build script. target-build is the temporary build directory. Since we may need to patch the pentaho source, CBF will make an entire copy of pentaho/ to target-build and patch the later, leaving the original source intact.
Pentaho 3.x build system requires tomcat to be downloaded separately. This has been tested with Tomcat 5.5. The location of the tomcat directory is not important, and can be placed almost any where. The location of the tomcat will be set inside of the build.properties file. For now don't worry about this, it will be mentioned later on in this articale. The same build system also requires xmltask to be installed.
xmltask installation
The xmltask.jar should be placed in /home/<username>/.ant/lib/ directory to be accessible by ant.
This leaves us with the "project-client" directory. As mentioned before, the idea is not write anything under pentaho/* directories, so all my changes go to this directory. Here is an example structure in more detail:
project-client/
|-- config
| |-- build.properties
| `-- build-pedro.properties
|-- patches
| |-- target-build
| | `--
| `-- target-dist
| `-- server
| |-- conf
| | |--
| | `-- jboss-service.xml
| |-- webapps
| | |-- pentaho
| | | `-- WEB-INF
| | | `-- web.xml
| `-- lib
| `-- postgresql-8.2-505.jdbc3.jar
`-- solution
|-- Portal.properties
|-- Portal.url
|-- Portal_pt.properties
|-- admin
.... etc
All this is created manually according to the specific project needs.
Note to CBF version 2 users
the old target-preconfiguredinstall is now target-dist, where you will find the server, the admin console and licences
The idea is very simple: All changes that would normally go to pentaho/* are placed under "patches" directory (project-client/patches/). The CBF ant script will pick up the files in the project-client/patches/ directory, scan for tokens and replace the tokens with the variables defined inside the project-client/config/build.properties files, and copy the files to the top level directory of the entire project (In this example MyProjectDir). It's not recommended to patch anything under pentaho/*; sources changes are patched in to target-build/* and all other changes are made by patching the final directory, target-dist.
For the example scenario, those were the files I had to change. I had to change some jboss's config files just because I had to change a port that was unavailable; added my datasource (client-ds.xml) and changed the jboss-web.xml and web.xml to register it; changed all other ds's cause I'm using postgresql instead of hsql; added the jdbc lib; changed the security system from memory to jdbc.
Getting and setting web.xml
web.xml can be found at pentaho/bi-platform-appserver/webapps/pentaho/WEB-INF/web.xml and should be copied to the inside of your patches directory at project-client/patches/target-dist/server/webapps/pentaho/WEB-INF/web.xml
Inside of this file, tokens can be placed that will be set by the CBF ant script. See the example snippet of web.xml bellow.
Example snippet of web.xml:
<context-param>
<param-name>solution-path</param-name>
<param-value>@solution.deploy.path@</param-value>
</context-param>
<context-param>
<param-name>base-url</param-name>
<param-value>@BASE_URL@</param-value>
</context-param>
The tokens
@solution.deploy.path@ and @BASE_URL@
are defined in the project-client/config/build.properties or project-client/config/build-client.properties files and will be replaced by the CBF ant script and the new revised web.xml with the replaced tokens will be copied to the top level directory (In this example MyProjectDir).
This is scalable. Just change files there and they will be copied to the destination target. CBF does not allow (yet) to remove files from target to destination, but I also don't think that's a relevant issue.
Tip: Upgrading Jars
Sometimes there's the need to upgrade some Jar version. A very simple way to do so is to patch 2 files: myJar-oldversion.jar and myJar-newVersion.jar where the first one is an empty zip file that will overwrite the original one
The solution is under project-client/solution, and our build.properties points to this dir. For now, I just copied pentaho-solutions to here, and will start from there by adding new solutions and playing a bit.
The idea is to be able to check in the whole project-client directory into svn.
Tip: Maintaining system files
Tip: Unlike previous version, 3.0.1 doesn't require to manually copy admin and system directories, and can even copy samples
Aside: Heres a screenshot of all the files I changed to make pentaho 3.0 work for me:
Configuration files
The main config file is in config/build.properties; specific environment configurations can then be set in config/build-env.properties . Here's an example file: