Deploying Kill Bill on Heroku

by | Jan 24, 2014 | System Integration

Similar to OpenShift, Heroku grants you a limited set of free resources each month (750 free dyno-hours per app) that you can leverage to run Kill Bill and the Kill Bill admin UI — Kaui, for free, in the cloud. This article will guide you through it.

The same word of caution applies here as well regarding scalability: your free 750 dyno-hours will allow you to run one 1X dyno for an entire month free of charge, which is limited to 512MB of RAM. This is a bit small for the JVM (especially if you install Kill Bill plugins). While it is probably good enough for quick prototyping, we recommend you use a 2X dyno for your production environment.

To create a Heroku account, go to Even though Kill Bill will run free of charge, you need to verify you account by entering your credit card at This is required as MySQL support is provided as an add-on only (and you need to verify your account to install add-ons, even free ones).

The first step is to install the Herok Toolbelt by going to and verify you can log-in by running

heroku login

To deploy WARs, you need to install the heroku-deploy CLI plugin:

heroku plugins:install

Kill Bill deployment

Grab the latest jar-with-dependencies.war artifact from Maven Central and create our kbdemo app, which will be running Tomcat and MySQL:

heroku create kbdemo

heroku deploy:war --war /path/to/killbill-server-*.war --app kbdemo

heroku addons:remove heroku-postgresql:dev --app kbdemo --confirm kbdemo
heroku addons:add cleardb --app kbdemo

Kill Bill system properties are defined via the JAVA_OPTS environment variable. You can inspect it by running:

heroku config --app kbdemo

Locate the CLEARDB_DATABASE_URL variable from that output, which should look like mysql://USER:PASS@HOST/DB?reconnect=true.

Populate JAVA_OPTS as follow:

heroku config:set JAVA_OPTS='-Xmx512m -Xss512k -Dcom.ning.jetty.jdbi.url=jdbc:mysql://HOST/DB -Dcom.ning.jetty.jdbi.user=USER -Dcom.ning.jetty.jdbi.password=PASS -DANTLR_USE_DIRECT_CLASS_LOADING=true' --app kbdemo

The final step is to install the Kill Bill DDL. Fetch the latest Kill Bill schema, and install it:

ruby -e "$(curl -skSfL" > /var/tmp/ddl.sql
mysql -uUSER -p -HHOST DB
mysql> source /var/tmp/ddl.sql

That’s it for Kill Bill! You can restart the app and check the logs by running:

heroku restart --app kbdemo
heroku logs -t --app kbdemo

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"}'

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

Kaui deployment

To install Kaui, let’s first create our skeleton Rails app:

rails new kauidemo --database=mysql
cd kauidemo
rm -f public/index.html

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'

Add the Heroku specific gem to your Gemfile:

gem 'rails_12factor', group: :production

To deploy Kaui, we need to create a git tree for Heroku:

git init
git add .
git commit -m "init"

Create a new app:

heroku create kauidemo
# Enable user-env-compile (this is for config vars to be present during the build)
heroku labs:enable user-env-compile -a kauidemo
# Setup the git tree
git remote add heroku [email protected]:kauidemo.git

Configure the following environment variable to point to Kill Bill:

heroku config:set KILLBILL_URL= --app kauidemo

Similarly, override DATABASE_URL with the content of CLEARDB_DATABASE_URL of the kbdemo app (replace the mysql:// prefix with mysql2:// to match the adapter name).

Push your changes to deploy your application:

git push heroku master

And finally run the migrations:

heroku run rake db:migrate --app kauidemo

If you see an error such as User 'USER' has exceeded the 'max_user_connections' resource, wait a few minutes before retrying.

You should be all set! You can now point your browser to 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