RubyDoc.info: File: README – Documentation for kpm (0.8.0)

KPM is a command line utility which facilitates the installation of Kill Bill, its plugins and Kaui. It also provides utility helpers useful for the day-to-day management of a production system.

KPM Installation

Pre-built binaries (recommended)

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

Download the .tar.gz package matching your architecture (Linux and MacOS only).

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

Through Rubygems

KPM is also available on RubyGems.org.

KPM Commands

Kill Bill installation

kpm install

kpm install (with no argument) will setup Kill Bill and Kaui in your current directory, including:

Tomcat (open-source Java web server)
The Kill Bill application (war) is installed in the ./webapps directory
The Kill Bill UI (Kaui war) is installed in the ./webapps directory
Default OSGI bundles are installed in the /var/tmp/bundles directory

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.

kpm install Using A `kpm.yml` File

KPM also lets you specify a configuration file, kpm.yml, to describe what should be installed. For example:

killbill:
  version: 0.20.12
  plugins:
    java:
      - name: analytics

This instructs kpm to:

Download Kill Bill version 0.20.12
Setup the Analytics (Java) plugin (you would still need to manually install the plugin DDL file)

To start the installation:

kpm install kpm.yml

Here is a more advanced example, specifying a custom Nexus repository and non-standard deployment directories:

killbill:
  version: 0.20.12
  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
  plugins_dir: /var/tmp/bundles
  webapp_path: /var/lib/tomcat/webapps/ROOT.war

Artifacts Downloads

You can download specific artifacts with the following commands:

kpm pull_kaui_war <version>: downloads the Kaui war
kpm pull_kb_server_war <version>: downloads the Kill Bill war
kpm install_java_plugin plugin-key <kb-version>: downloads a Java plugin identified by plugin-key
kpm install_ruby_plugin plugin-key <kb-version>: downloads a Ruby plugin identified by plugin-key
kpm pull_defaultbundles <kb-version>: downloads the default Kill Bill OSGI bundles

This is especially useful when scripting deployments.

Note: previous plugin versions aren’t cleaned up by default to facilitate rollbacks. If your deployment is stateful, unused, old plugin versions will slow the Kill Bill startup time. To cleanup these entries, use kpm cleanup which will delete all non-default plugin versions, or kpm uninstall.

kpm uninstall

kpm uninstall plugin-key will uninstall a plugin identified by plugin-key (all versions are uninstalled by default).

kpm migrations

kpm migrations is used to download database migration files when upgrading Kill Bill or plugins. See our database migrations guief for more details.

Operations

kpm inspect

The command kpm inspect can be used to see which plugins have been installed:

kpm inspect --destination=/var/tmp/bundles
_______________________________________________________________________________________________________________________________________________________
|          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[???](*) |
_______________________________________________________________________________________________________________________________________________________

Note: GROUP ID, ARTIFACT ID, PACKAGING and SHA1 can be missing (???) when installing plugins which aren’t hosted in a Nexus repository. This isn’t an issue.

kpm system

The command kpm system is a superset of the inspect command. In addition to plugins information, the command will return details about the Kill Bill and Kaui installation, Java and Ruby environment, details about the OS, CPU, Memory and disks, entropy available, etc.

Note: for non-standard deployments, you will need to tell KPM the location of the Kill Bill and Kaui webapp (see kpm help system).

kpm diagnostic

The command kpm diagnostic is a superset of the system command. It will connect to your Kill Bill instance to gather tenant configuration information and account data (if a specific account is specified) and will gather all log files.

You will need to instruct KPM how to connect to your Kill Bill instance (see kpm help diagnostic).

kpm account

kpm account exports all account data from a running system and re-imports it in another Kill Bill installation. This is an advanced command and is usually run as part of kpm agnostic.

kpm tenant_config

kpm tenant_config exports tenant specific data from a running system. This is an advanced command and is usually run as part of kpm agnostic.

kpm cleanup

kpm cleanup which will delete all non-default plugin versions. The --dry-run option can be used to double check first what would be deleted.

Plugins development

kpm info

kpm info lists the libraries to use when writing a plugin for a specific Kill Bill version. It also lists all of the official plugins for that specific version.

Installing Custom Plugins

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 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. We suggest you specify a plugin_key with a namespace dev: to make it clear this is not a released version:

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

Internals

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

Plugins are named using their pluginKey (the value for the name entry 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 Development guide.

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. The generic logic associated with that file is the following:

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, the 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).
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.

Notes:

You can override that behavior with the --force-download switch
When --force-download is specified (false by default), network access to a Nexus instance is required. Otherwise, downloads are idempotent even if no outbound networking is allowed (on initial download, the Nexus metadata is cached in the sha1.yml file which is re-used on subsequent installation if no outbound networking is allowed — by default, KPM will try to get the latest metadata from Nexus though)