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.
Pre-built binaries (recommended, Linux and MacOS only)
Note that this installation method assumes
/bin/bash to be available on your system.
KPM builds are available on Maven Central with coordinates
Download the package matching your architecture.
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
You can then run:
gem install kpm
The following commands
mkdir killbill cd killbill kpm install
Tomcat (open-source Java web server) is setup in the
The Kill Bill application (war) is installed in the
The Kill Bill UI (Kaui war) is installed in the
Default plugins are installed in the
/var/tmp/bundlesdirectory, 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
You can then verify Kill Bill is running by going to http://127.0.0.1:8080/kaui.
Custom Installation Through
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
killbill: version: 0.18.0 plugins: java: - name: analytics ruby: - name: stripe
This instructs kpm to:
To start the installation:
kpm install kpm.yml
Here is a more advanced example:
killbill: group_id: org.kill-bill.billing artifact_id: killbill-profiles-killbill version: 0.18.10 default_bundles_version: 0.36.11 nexus: ssl_verify: false url: http://nexus.acme repository: public-all plugins: java: - name: analytics - name: acme:custom artifact_id: custom-plugin version: 0.0.1-SNAPSHOT ruby: - name: kpm plugins_dir: /var/tmp/bundles webapp_path: /var/lib/tomcat/webapps/ROOT.war
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
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
kpm install_java_plugin 'dev:adyen' --from-source-file="<PATH_TO>/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2"
kpm inspect can be used to see what has been installed. In the case of
dev plugins, most of the infofrmation related to
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 Done! > kpm inspect _____________________________________________________________________________________________________________ | PLUGIN NAME | PLUGIN KEY | TYPE | GROUP ID | ARTIFACT ID | PACKAGING | VERSIONS sha1=, def=(*), del=(x) | _____________________________________________________________________________________________________________ | 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 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:
installcommand by pulling artifacts from maven repository
migrationcommand. This requires setting the
TOKENsystem property with a valid GITHUB api token.
KPM mysql test
Test suite that requires an instance of
mysql running and verifies the following:
account_spec.ymlfile 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
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:
When installing a binary (
tar.gz..), KPM will download both the binary and the
sha1from the server, compute the
sha1for the binary and compare the two (verify that binary indeed matches its remote
sha1). Then, binary is installed and
sha1.ymlfile is updated. The
sha1entry in that
sha1.ymlfile will now represent the local
sha1version (note that for
tar.gzbinaries which have been uncompressed, the local
sha1is not anymore easily recomputable).
When attempting to download again the same binary, KPM will compare the value in the
sha1.ymland 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):
sha1is not available: Binary will be downloaded again (and no
sha1check can be performed)
sha1.ymldoes not exist: Binary will be downloaded again
sha1entry in the
sha1.ymlexists 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
Note that you can override that behavior with the