Back to Blog

Deploying Kill Bill on OpenShift

by | Jan 14, 2014 | System Integration

Note! An updated version of this tutorial can be found here.

Thanks to the entry-level offering of the Cloud Application Platform by Red Hat — OpenShift, you can run in the cloud Kill Bill and the Kill Bill admin UI — Kaui, for free. This article will guide you through it.

Note that you only have free access to small containers (so called gears), which are less than ideal to run Kill Bill on: RAM is capped at 512MB, which is a bit small for the JVM (especially if you install Kill Bill plugins). This is reflected in the UI, which feels slow. While it is probably good enough for quick prototyping, we recommend you use at least a medium gear for your production environment.

Once you created an account, the first step is to setup the OpenShift command line client:

gem install rhc
rhc setup

Check the OpenShift documentation for more details.

Let’s create our Demo app, which will be running Tomcat and MySQL:

rhc create-app Demo jbossews-2.0
rhc cartridge add mysql-5.1 -a Demo

Note that for simplicity, we created a non-scaled application. This means that Tomcat and MySQL will be installed on the same gear. For a real production environment, we would create a scaled application instead, which would make OpenShift install automatically MySQL on its own dedicated gear.

The next step is to download Kill Bill. Grab the latest jar-with-dependencies.war artifact from Maven Central.

Creating the Demo app should have cloned a demo.git repository. Go to that directory and copy the war file (you can also cleanup the src/ directory and pom.xml file):

cp /path/to/killbill-server-*.war webapps/ROOT.war
git rm -r src/ pom.xml

Kill Bill system properties can be defined in .openshift/config/catalina.properties. At the minimum, add the following ones:

# Kill Bill properties
com.ning.jetty.jdbi.user=...
com.ning.jetty.jdbi.password=...
ANTLR_USE_DIRECT_CLASS_LOADING=true

Replace user and password with the MySQL credentials generated when you added the mysql-5.1 cartridge.

The last property missing is the JDBC connection string. Unfortunately, since OpenShift defines the host and port as environment variables, we cannot simply add a line such as

com.ning.jetty.jdbi.url=jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/demo

because variables are not expanded in catalina.properties.

The workaround is to define a pre-start action hook and to configure this property via JAVA_OPTS. To do so, create the file .openshift/action_hooks/pre_start_jbossews-2.0 with the following content:

export JAVA_OPTS="-Dcom.ning.jetty.jdbi.url=jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/demo"

And also make sure it is executable:

chmod +x .openshift/action_hooks/pre_start_jbossews-2.0

Commit and push your changes to restart your application.

The final step is to install the Kill Bill DDL. To do so, log-in to the remote machine, fetch the latest Kill Bill schema, and install it:

# Locally
rhc ssh

# On the remote machine
ruby -e "$(curl -skSfL http://kill-bill.org/schema)" > /var/tmp/ddl.sql
mysql demo
mysql> source /var/tmp/ddl.sql

That’s it for Kill Bill! You can check the logs by running rhc tail.

The first thing you want to do is to create your own tenant:

curl -X POST 
     -u admin:password 
     -H 'Content-Type: application/json' 
     -H 'X-Killbill-CreatedBy: admin' 
     -d '{"apiKey": "bob", "apiSecret": "lazar"}' 
     http://demo-YOUR_DOMAIN.rhcloud.com/1.0/kb/tenants

For more details on this, check our Getting started guide.

To install Kaui, let’s create another app (again, single gear with its own MySQL for simplicity):

# Don't call it Kaui or it will confuse Rails later on (since the Kaui gem is called kaui)
rhc create-app KauiDemo ruby-1.9
rhc cartridge add mysql-5.1 -a KauiDemo

Pull in the OpenShift Rails example to create the skeleton app:

git remote add upstream -m master git://github.com/openshift/rails-example.git
git pull -s recursive -X theirs upstream master
git rm -f public/index.html

Delete the gem pg from the Gemfile, as we will be using MySQL:

# After removing the line:  gem 'pg'
bundle install

Next, mount Kaui inside this skeleton app:

gem install kaui
kaui .
rake kaui:install:migrations

Configure Kaui by putting your tenant credentials in config/initializers/killbill_client.rb:

# Kill Bill tenant credentials
KillBillClient.api_key = 'bob'
KillBillClient.api_secret = 'lazar'

Configure the following environment variable to point to Kill Bill (use the public DNS from the demo application):

rhc set-env -e KILLBILL_URL=http://demo-YOUR_DOMAIN.rhcloud.com/

Commit and push your changes to restart your application.

You should be all set! You can now point your browser to http://kauidemo-YOUR_DOMAIN.rhcloud.com/ and log-in (default credentials are admin/password).

Jump to the “Create an account” section of our Kill Bill in 5 minutes tutorial to create your first customer.

Related Articles