Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


KPM: the Kill Bill Package Manager

The goal of KPM is to facilitate the installation of Kill Bill, its plugins and Kaui.

kpm can be used interactively to search and download individual artifacts (Kill Bill war, plugins, etc.) or to perform an automatic Kill Bill installation using a configuration file.


Note that this installation method assumes /bin/bash to be available on your system.

KPM builds are available on Maven Central with coordinates org.kill-bill.billing.installer:kpm.

Download the package matching your architecture.

Through Rubygems

Ruby is required to run KPM itself (it is not a dependency of Kill Bill).

Ruby 2.1+ or JRuby 1.7.20+ is recommended. If you don’t have a Ruby installation yet, use RVM:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
\curl -sSL https://get.rvm.io | bash -s stable --ruby

After following the post-installation instructions, you should have access to the ruby and gem executables.

You can then run:

gem install kpm

Quick start

The following commands

mkdir killbill
cd killbill
kpm install

will setup Kill Bill and Kaui, i.e.:

  • Tomcat (open-source Java web server) is setup in the killbill directory

  • The Kill Bill application (war) is installed in the killbill/webapps directory

  • The Kill Bill UI (Kaui war) is installed in the killbill/webapps directory

  • Default plugins are installed in the /var/tmp/bundles directory, among them:

  • jruby.jar, required to run Ruby plugins

  • the KPM plugin, required to (un-)install plugins at runtime

To start Kill Bill, simply run

./bin/catalina.sh run

You can then verify Kill Bill is running by going to

Using KPM

Custom Installation Through kpm.yml File

KPM allows you to specify a configuration file, kpm.yml, to describe what should be installed. The configuration file is a yml. The following shows the syntax of the kpm.yml file:

  version: 0.18.0
      - name: analytics
      - name: stripe

This instructs kpm to:

  • Download Kill Bill version 0.18.0

  • Setup the Analytics (Java) plugin and the Stripe (Ruby) plugin

To start the installation:

kpm install kpm.yml

Here is a more advanced example:

  group_id: org.kill-bill.billing
  artifact_id: killbill-profiles-killbill
  version: 0.18.10
  default_bundles_version: 0.36.11
    ssl_verify: false
    url: http://nexus.acme
    repository: public-all
      - name: analytics
      - name: acme:custom
        artifact_id: custom-plugin
        version: 0.0.1-SNAPSHOT
      - name: kpm
  plugins_dir: /var/tmp/bundles
  webapp_path: /var/lib/tomcat/webapps/ROOT.war

Custom Downloads

You can also download specific versions/artifacts directly with the following commands – bypassing the kpm.yml file:

  • kpm pull_kaui_war <version>

  • kpm pull_kb_server_war <version>

  • kpm install_ruby_plugin plugin-key <kb-version>

  • kpm install_java_plugin plugin-key <kb-version>

For more details see kpm help.

Dev Mode

If you are a developer and either modifying an existing plugin or creating a new plugin, KPM can be used to install the code of your plugin. Before going further, make sure you read the Plugin Development Documentation first.

Let’s assume you are modifying the code for the (Ruby) CyberSource plugin. You would have to first build the plugin package, and then you could use KPM to install the plugin. We suggest you specify a plugin_key with a namespace dev: to make it clear this is not a released version.

kpm install_ruby_plugin 'dev:cybersource' --from-source-file="<PATH_TO>/killbill-cybersource-3.3.0.tar.gz"

Let’s assume now that you are modifying the code for the (Java) Adyen plugin. The plugin first needs to be built using the maven-bundle-plugin to produce the OSGI jar under the target directory. Then, this jar can be installed using KPM (you would also need to specify a version here since the archive does not embed any metadata, unlike Ruby plugins packages). The same applies with regard to the plugin_key where we suggest to specify a namespace dev:.

kpm install_java_plugin 'dev:adyen' --from-source-file="<PATH_TO>/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2"

The command kpm inspect can be used to see what has been installed. In the case of dev plugins, most of the infofrmation related to GROUP ID, ARTIFACT ID, PACKAGING and SHA1 will be missing because no real download occured.

Finally, when it is time to use a released version of a plugin, we first recommend to uninstall the dev version, by using the kpm uninstall command and using the plugin_key, and then installing the released version. For instance the following sequence could happen:

> kpm inspect
|          PLUGIN NAME |      PLUGIN KEY | TYPE | GROUP ID | ARTIFACT ID | PACKAGING | VERSIONS sha1=[], def=(*), del=(x) |
| killbill-cybersource | dev:cybersource | ruby |      ??? |         ??? |       ??? |                      3.3.0[???](*) |
|                adyen |       dev:adyen | java |      ??? |         ??? |       ??? |                      0.3.2[???](*) |

> kpm uninstall 'dev:cybersource'
Removing the following versions of the killbill-cybersource plugin: 3.3.0

> kpm inspect

|       adyen |  dev:adyen | java |      ??? |         ??? |       ??? |                      0.3.2[???](*) |

> kpm install_ruby_plugin cybersource

> kpm inspect
|          PLUGIN NAME |  PLUGIN KEY | TYPE |                          GROUP ID |        ARTIFACT ID | PACKAGING | VERSIONS sha1=[], def=(*), del=(x) |
| killbill-cybersource | cybersource | ruby | org.kill-bill.billing.plugin.ruby | cybersource-plugin |    tar.gz |                 4.0.2[e0901f..](*) |
|                adyen |   dev:adyen | java |                               ??? |                ??? |       ??? |                      0.3.2[???](*) |


Test required setups

There are 3 suites of tests for KPM (see rake -T):

  • rake test:spec : Fast suite of unit tests

  • rake test:remote:spec : Test suite that relies on maven artifacts

  • rake test:mysql:spec : Test suite that requires an instance of Kill Bill server running and a properly setup database

KPM Unit test

Unit tests don’t require any third party system or configuration.

KPM remote test

Test suite that verifies the following:

  • KPM install command by pulling artifacts from maven repository

  • KPM migration command. This requires setting the TOKEN system property with a valid GITHUB api token.

KPM mysql test

Test suite that requires an instance of mysql running and verifies the following:

  • KPM account command: The account_spec.yml file needs to be modified with correct credentials and user must have correct privileges; also the database schema must not exist. In addition, one must start an instance of a Kill Bill server

Plugin Keys

In the kpm.yml example provided above, the plugins are named using their pluginKey (the value for the name in the kpm.yml) . The pluginKey is the identifier for the plugin: * For plugins maintained by the Kill Bill team, this identifier matches the key in the file based repository of well-known plugins * For other plugins, this key is either specified when installing the plugin through api call, or default to the pluginName. For more information, please refer to the Plugin Developer Guide.


KPM relies on the kpm.yml file to know what to install, and as it installs the pieces, it keeps track of what was installed so that if it is invoked again, it does not download again the same binaries. The generic logic associated with that file is the following:

  1. When installing a binary (war, jar, tar.gz..), KPM will download both the binary and the sha1 from the server, compute the sha1 for the binary and compare the two (verify that binary indeed matches its remote sha1). Then, binary is installed and sha1.yml file is updated. The sha1 entry in that sha1.yml file will now represent the local sha1 version (note that for tar.gz binaries which have been uncompressed, the local sha1 is not anymore easily recomputable).

  2. When attempting to download again the same binary, KPM will compare the value in the sha1.yml and the one on the remote server and if those match, it will not download the binary again.

There are some non standard scenario that could occur in case of users tampering with the data (or remove server unavailable):

  • Remote sha1 is not available: Binary will be downloaded again (and no sha1 check can be performed)

  • sha1.yml does not exist: Binary will be downloaded again

  • sha1 entry in the sha1.yml exists but has the special value SKIP : Binary will not be downloaded again

  • Binary does not exist on the file system (or has been replaced with something else): KPM will ignore. Note that correct way to remove plugins is to use the KPM uninstall command.

Note that you can override that behavior with the --force-download switch.