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.
Prerequisites
Ruby
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.
Java
Kill Bill runs on the Java platform, version 6 and above (8 is recommended).
Installation
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 http://127.0.0.1:8080/kaui.
Configuration
You can configure the installation process using a kpm.yml file.
For example:
killbill:
version: 0.14.0
plugins:
java:
- name: analytics
ruby:
- name: stripe
This instructs kpm to:
To start the installation:
kpm install kpm.yml
Common configuration options:
jvm
: JVM propertieskillbill
: Kill Bill propertiesplugins_dir
: OSGI bundles and plugins base directorywebapp_path
: path for the Kill Bill war (if specified, Tomcat isn’t downloaded)
There are many more options you can specify. Take a look at the configuration file used in the Docker image for example.
Internals and Advanced Commands
Caching
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:
- For the Kill Bill artifact itself, kpm will first extract the sha1 from the remote repository and compare with the current sha1 installed under the default
webapp_path
; if those are the same, the file is not downloaded again. - For the plugins, since some of those are downloaded as an archive (*.tgz) and then decompressed/expanded, kpm will use an internal file,
<plugins_dir>/sha1.yml
to keep track of the sha1 archive. If there is an entry and the sha1 matches, then the file is not downloaded again.
Note that you can override that behavior with the --force-download
switch.
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 pull_ruby_plugin <artifact_id>
For more details see kpm --help
.