:toc: macro :toc-title: :toclevels: 9 [[kpm-the-kill-bill-package-manager]] = KPM: the Kill Bill Package Manager 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. toc::[] [[kpm-installation]] == KPM Installation [[pre-built-binaries-recommended]] === Pre-built binaries (recommended) KPM self-contained builds are available on http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.kill-bill.billing.installer%22%20AND%20a%3A%22kpm%22[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]] === Through Rubygems KPM is also available on https://rubygems.org/gems/kpm[RubyGems.org]. [[kpm-commands]] == KPM Commands [[kill-bill-installation]] === Kill Bill installation [[kpm-install]] ==== kpm install `kpm install` (with no argument) will setup https://github.com/killbill/killbill[Kill Bill] and https://github.com/killbill/killbill-admin-ui-standalone[Kaui] in your current directory, including: * http://tomcat.apache.org/[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 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 https://github.com/killbill/killbill-analytics-plugin[Analytics] (Java) plugin (you would still need to manually install the plugin https://github.com/killbill/killbill-analytics-plugin/blob/master/src/main/resources/org/killbill/billing/plugin/analytics/ddl.sql[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]] ==== Artifacts Downloads You can download specific artifacts with the following commands: * `kpm pull_kaui_war `: downloads the Kaui war * `kpm pull_kb_server_war `: downloads the Kill Bill war * `kpm install_java_plugin plugin-key `: downloads a Java plugin identified by `plugin-key` * `kpm install_ruby_plugin plugin-key `: downloads a Ruby plugin identified by `plugin-key` * `kpm pull_defaultbundles `: 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 `kpm uninstall plugin-key` will uninstall a plugin identified by `plugin-key` (all versions are uninstalled by default). [[kpm-migrations]] ==== kpm migrations `kpm migrations` is used to download database migration files when upgrading Kill Bill or plugins. See our http://docs.killbill.io/0.20/database_migrations.html[database migrations guief] for more details. [[operations]] === Operations [[kpm-inspect]] ==== 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]] ==== 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]] ==== 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 `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 `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 `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]] === Plugins development [[kpm-info]] ==== 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]] ==== 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 http://docs.killbill.io/latest/plugin_development.html[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="/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2" .... [[internals]] ## Internals [[test-required-setups]] ### 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]] #### KPM Unit test Unit tests don’t require any third party system or configuration. [[kpm-remote-test]] #### 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]] #### 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]] ### 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 https://github.com/killbill/killbill-cloud/blob/master/kpm/lib/kpm/plugins_directory.yml[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 http://docs.killbill.io/latest/plugin_development.html[Plugin Development guide]. [[caching]] ### 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: 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, 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). 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. 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)