Tuesday, October 1, 2013

Going Agile: Pentaho Community Build Framework (CBF)

Going Agile: Pentaho Community Build Framework (CBF)

Info Sources


CBF is an excellent tool to automate the build of your Pentaho BI/BA servers. Say you have various environments like dev, test, prod and you want an easy way of configuring and building your servers automatically, then CBF is for you.

Create basic folder structure

http://www.webdetails.pt/ctools/cbf.html provides a tar file with the basic structure. Download this file and extract it in a convenient location. Follow all the basic install instructions mentioned on this page.

Replace the build.xml file

Currently the quickstart package ships with an old version of the build.xml, which you have to replace:

cd cbf-quickstart
rm build.xml
wget --no-check-certificate https://raw.github.com/webdetails/cbf/master/build.xml

Setup project

Navigate inside the cbf-quickstart folder and rename the project-client folder to something more meaningful/project specific (by changing client to the real client or project name, i.e. project-puma).

Setup configs for different environments

To create configs for different environments, create build properties files for each of them:

In example:

You can use the existing build.properties as a template. For now you will not have many properties in these files, once we start working on the patches, we will be able to added many more properties to these files.

Provide patch files

Patch files are all those files that you want CBF to replace in the original generic source packages. This can be completely static files (in example PDR jar library) but more importantly all these config files etc for which you want to have different settings on the various environments. You can copy these files in to the respective folders (solution for pentaho-solution and target-dist/server for all the Tomcat or JBoss related config files (by retaining the original folder structure). Once copied there, you can make these files’ content dynamic by adding tokens (syntax: @token@) for the config settings that you want to define.

Example web.xml (which is already part of the cbf-qickstart package):

This file was put into following folder:  

As you can see, we retain the full folder structure for the web.xml.

Example of a token you could set in this file:

The value for this token is set in project-*/config/build-*.properties:
solution.deploy.path = ../../solution/

If required, you can add other files and tokenize them in similar fashion.

Where do you get these files from you wonder? Simply build the BI server once without any special settings are download a compiled version of it (i.e. from sourceforge.net).

Examples of relevant files that you want to have various versions of depending on the environment (as said these are example, your milage may vary):








If required, you can remove all the startup actions from this last file. The beans part will then look like this:

   <bean id="sessionStartupActionsList" class="java.util.ArrayList">

Web Server:

Original folder/file
CBF folder/file
JDBC Drivers
JDNI Database connections: Add resource entry for each connection you want to define

Providing different files for each environment (optional)

In the standard setup only one patch folder exists:

This should be fine as long as you don’t need specific versions of static files in the various environments. In example, you might want to test the latest stable version of the PRD library on the test environment whereas your production environment is still on the previous version.

Pro-tip by Pedro Alves:

I'd leave the current patches dir as is but add another feature:


That way, on your cbf config file you could have:

useExtraPatchesDir = true
extraPatchesDir = dev (or whatever)

and you'd add the patch files to that dir. Then CBF would apply the standard patches first and then the extraPatches.

DS: So this would translate in following folder structure in example:

Get Pentaho BI Server source code

Within the top level CBF folder create a folder for storing the required version of the Pentaho BI server:

cd cbf-quickstart
mkdir pentaho-4.8
svn co http://source.pentaho.org/svnroot/bi-platform-v2/tags/4.8.0-stable/ ./pentaho-4.8

Add Ctools

There is no separate installation necessary. Andrea Torre kindly added support to the CBF ant file to install C* Tools (see this blog post).
In the build-*.properties file you can specify if ctools should be installed after the cbf build and you can specify which branch you want to use (defaults to stable):
ctools.install = true
ctools.branch = dev
Alternatively, if you require some specific parameters of the c-tools installer which are not covered by the ant script (in example currently you cannot specify specific components), you will have to run the c-tools-installer yourself, in example:
rm -rf ctools
mkdir -p ctools/system
./ctools-installer.sh -b stable -c cdf,cda,cde,cgg, cdb,saiku,saikuadhoc -s ctools -y -n

Later on you can write a custom shell script to install these files automatically into the target-dist/solution.

Installing Tomcat

You can install Tomcat anywhere on your system, it doesn’t have to reside in the cbf-quickstart folder. To reference your Tomcat installation, add (example):
tomcat.path = /usr/share/tomcat
to project-*/config/build-*.properties

If you have not Tomcat installed yet, go to the Tomcat Version 6 Download Page and choose the Binary Distribution > Core > Zip or tar.gz.

Once the file is downloaded, navigate to the cbf-quickstart directory and run:
cp ~/Downloads/apache-tomcat-6.0.37.zip .
unzip apache-tomcat-6.0.37.zip

In this case, you should reference Tomcat like this in the project-*/config/build-*.properties:
tomcat.path = ../../apache-tomcat-6.0.37

Finish configuring CBF

The build.properties file located in project-*/config holds all the essential settings for your project. As mentioned before, you can also create specific build properties files for each environment, which inherits from the main build.properties file (properties in build-*.properties override those in build.properties). Make sure you finished configuring all the properties now!

vi project-*/config/build-*.properties

tomcat.path = /usr/share/tomcat
pentaho.dir = pentaho-4.8
solution.path = project-client/solution/
#Example of a token:
solution.deploy.path = ../../solution/


Now it is time to run the Ant build:
ant -Dproject=<project-name> -Denv=<environment-name> dist-clean all

Replace <project-name> and <environment-name> with the respective real world names.

Remember: the <project-name> has to be the same as to define for the project folder (in example: project-puma). <environment-name> has to be from one of the build properties files that you created (i.e. one we used here is build-dev.properties). Following our example, this would be:
ant -Dproject=puma -Denv=dev dist-clean all

Target (Build) Options

(This section is mostly copied from the CBF website for completeness sake)
See all available target options:
$ ant -Dproject=<project-name> -Denv=<environment-name> -p

Doing a full compile
When we want to "start from scratch", with a clean system, this is the command to use:

$ ant -Dproject=<project-name> -Denv=<environment-name> dist-clean all

Start the project after compiled
This will simply start tomcat

$ ant -Dproject=<project-name> -Denv=<environment-name> run

Full compile and start server
You can guess this one:

$ ant -Dproject=<project-name> -Denv=<environment-name> dist-clean all run

Deploy to a remote server, solutions only
$ ant -Dproject=<project-name> -Denv=<environment-name> dist-clean deploy-solutions

Apply the patches only without a full compile
No need to do the dist-clean here.

$ ant -Dproject=<project-name> -Denv=<environment-name> copy-init run

Full deploy to a remote server
This will transfer both server and solutions.

$ ant -Dproject=<project-name> -Denv=<environment-name> dist-clean deploy-all
Ctools build targets (source):
ctools-installer: Install ctools (prompts for modules)
ctools-installer-auto: Install ctools silently
ant -Dproject=<project-name> -Denv=<environment-name> ctools-installer

Fixing Build Errors

Blacklisted class javax.servlet.Servlet found

If you get an error message like this one:
/opt/pentaho/cbf/cbf-quickstart/build.xml:374: The following error occurred while executing this line:
/opt/pentaho/cbf/cbf-quickstart/target-build/bi-platform-assembly/build-res/assembly_shared.xml:19: !!! Blacklisted class javax.servlet.Servlet found in a retrieved jar.  Assembly cannot proceed !!!


mkdir -p project-client/patches/target-build/bi-platform-assembly/build-res

cp pentaho-4.8/bi-platform-assembly/build-res/assembly_shared.xml project-client/patches/target-build/bi-platform-assembly/build-res

Copy the contents of the assembly_shared.xml in there and add following argument:
<available property="Servlet.class.present" classname="javax.servlet.Servlet" ignoresystemclasses="true">

Deploying to the various environments

CBF offers 2 methods of deploying the build (fully configured BI server) or only the solution to the various servers (i.e. test, prod). One of them is rsync - see for CBF details. CBF comes with a feature to build RPMs (see here).

Register Plugins once server started

Without registering the plugins you might get following error message when opening a report:

ERROR [GenericServlet] GenericServlet.ERROR_0004 - Resource /reporting/reportviewer/cdf/cdf-module.js not found in plugin reporting

In the following order:
  1. Refresh solution repository
  2. Refresh the plugin adapter
  3. Refresh system settings

Recommended folder structure with Git

Why git? Version control - enough said - it should be part of every project. Read this excellent blog post by Pedro Alves (CBF and Versioning - How to develop Pentaho solutions in a team)

Usually you will have one git repo per client project. Inside the project folder create a folder called cbf and add a .gitignore file with following content (this setup was kindly suggested by Paul Stoellberger):

Once you ran the shell script - which we will talk about in a second (see next section) - you will have following files and folders inside your cbf folder:

folder name
in git
tomcat web server
Holds the biserver source code
Holds the sql files to create the Pentaho repository DB and quartz DB (excludes any hypersonic shell scripts). This folder was copied over from a BI server installation downloaded from sourceforge.net
N (although, on one occasion I had to add a bug fix in which case I put it on git)
project specific folders
This folder holds custom created start and stop scripts for the BI server (not part of CBF)
This is a custom created shell script which further automated the build for a specific project (and environment)
Ant build xml, part of CBF

Further automate the build using a shell file

Please find below a sample of a custom created build-*-*.sh file. This example was kindly provided by Paul Stoellberger:


## Custom script - created by Paul - not included in original CBF

# if not done - check out pentaho 4.8
if [ -d "pentaho-4.8" ]
  echo "Found pentaho-4.8"
   echo "Checking out pentaho-4.8 sources...."
   svn checkout svn://source.pentaho.org/svnroot/bi-platform-v2/branches/4.8/ pentaho-4.8

# svn checkout svn://source.pentaho.org/svnroot/bi-platform-v2/branches/4.8/ pentaho-4.8

# do we have a tomcat?
if [ -d "apache-tomcat" ]
  echo "Found tomcat"
   echo "Downloading tomcat....."
   wget http://tweedo.com/mirror/apache/tomcat/tomcat-6/v6.0.37/bin/apache-tomcat-6.0.37.tar.gz
   tar -xf apache-tomcat-6.0.37.tar.gz
   mv apache-tomcat-6.0.37 apache-tomcat
   rm apache*.gz

rm -rf ctools-installer.sh

rm -rf solution
mkdir solution

# build the package
ant -Dproject=aaa -Denv=dev dist-clean all

# custom c-tools installation
wget https://raw.github.com/pmalves/ctools-installer/master/ctools-installer.sh
mkdir solution/system
sh ctools-installer.sh -b stable -s solution/ -c cdf,cda,cde,cgg,saiku,saikuadhoc -y -n

# copy over our solution and patches
cp -r ../pentaho-solutions/* solution/

# copy over sql scripts to create repository, hibernate and quartz (added by DS)
cp -R data target-dist
cp scripts/* target-dist/

# copy over solution folder
mv solution/ target-dist/solution/

chmod +x target-dist/*.sh
chmod +x target-dist/server/bin/*.sh

# copy over sql scripts to create repository, hibarnate and quartz (added by DS)
cp -r data target-dist

# cleanup
# we dont need the kettle plugins - way too big
rm -rf target-dist/solution/system/kettle/plugins/*
rm -rf target-dist/solution/system/BIRT
rm -rf target-dist/licenses

# package it all up into tar.gz
#mkdir dist
#tar zcf aaa-package.tar.gz -C target-dist .
#mv aaa-package.tar.gz dist/

BI server runtime errors

For some unknown reason my CBF build was not quite cheering up with c-tools. Basically when I opened CDE I could see the interface, but parts of it were not functional and I got following error message (logs/catalina.out):
12:19:31,928 ERROR [DashboardDesignerContentGenerator] Could not get component definitions: null
12:19:31,928 ERROR [DashboardDesignerContentGenerator] getcomponentdefinitions: null
at pt.webdetails.cdf.dd.util.Utils.getRelativePath(Utils.java:216)
at pt.webdetails.cdf.dd.util.Utils.getRelativePath(Utils.java:182)
at pt.webdetails.cdf.dd.model.meta.reader.cdexml.fs.XmlFsPluginModelReader.readBaseComponents(XmlFsPluginModelReader.java:228)
at pt.webdetails.cdf.dd.model.meta.reader.cdexml.fs.XmlFsPluginModelReader.read(XmlFsPluginModelReader.java:148)
at pt.webdetails.cdf.dd.model.meta.reader.cdexml.fs.XmlFsPluginModelReader.read(XmlFsPluginModelReader.java:120)
at pt.webdetails.cdf.dd.model.meta.reader.cdexml.fs.XmlFsPluginModelReader.read(XmlFsPluginModelReader.java:43)

I could see the solution repository in PUC and PRD reports were just working fine.
Unfortunately nobody else seemed to have run into this problem, so there was no info available on how to fix this. After several trial and errors I pinned the problem down to the relative solution path I had configured in the web.xml. I just replaced this one with an absolute path and everthing was working fine then in CDE.

I'd like to say special thanks to Paul Stoellberger and Pedro Alves for sharing some of their ideas with me on this particular topic and everyone involved in CBF for their hard work!

No comments:

Post a Comment