kpm 0.7.2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c651b2089fe9f33b3484e82dcdb4471980b6f4ad
-  data.tar.gz: 8c746fc62e9332919f0082ffd25b96d450a91d64
+SHA256:
+  metadata.gz: ee0a0c6bd9401fa083710541772db690618749d31ea65a6531aee02bfcbc075b
+  data.tar.gz: b46b7a3777be07cd3b6ca5be05ef5c76504e4c8ca7e54938487c42b017b251c7
 SHA512:
-  metadata.gz: c0da2ef993caf070b2aaa3840e75220c1c9f26f4490bd3a2f5a3c4ca309de9a431e7198600733c2db317e2e2bff557438c447a753ddabc6f08f0c98f21ca4a09
-  data.tar.gz: 859900d8b192dd29cdd7f0ecd925b527654e397baac2c0771e7c145876da58ef03ea0508cc4ac5b3fb3595e1017d7820e0203487e28dfbb13aaf1b17c7de05ad
+  metadata.gz: f1d274c79ad9762432a649c144d32f4365cc93ab57f841a58293c666d432895056872882b1edee2b1e6493e83a5f27d719825f490f8ca594188c906665253cf4
+  data.tar.gz: 9fbe10b774582a2bf60f534b134d1180109efcd18ff8dc6cc901de74a4e9ee1ee8e11416c5848cee4a7658b3703c67d2c93c590804ec9a25500e9902a7f6189d

data/.gitignore

@@ -7,3 +7,5 @@ kpm-*-linux-x86_64.tar.gz
 kpm-*-osx.tar.gz
 traveling-ruby-*.tar.gz
 *.asc
+.rakeTasks
+pom.xml.versionsBackup

data/.rubocop.yml

@@ -0,0 +1,138 @@
+# RuboCop 0.69.0 dropped support for 2.2
+#AllCops:
+#  TargetRubyVersion: 2.2
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+# Alternative?
+Gemspec/RubyVersionGlobalsUsage:
+  Enabled: false
+
+Layout/DefEndAlignment:
+  AutoCorrect: true
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/SuppressedException:
+  AllowComments: true
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Security/YAMLLoad:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyElse:
+  EnforcedStyle: empty
+
+# We must support old Rubies
+Style/HashSyntax:
+  Enabled: false
+
+# Ruby 2.3+ only
+Style/NumericPredicate:
+  Enabled: false
+
+# Ruby 2.3+ only
+Style/SafeNavigation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/AccessorGrouping:
+  Enabled: true
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/README.adoc

@@ -3,65 +3,50 @@
 :toclevels: 9
 
 [[kpm-the-kill-bill-package-manager]]
-# KPM: the Kill Bill Package Manager
+= 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.
+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::[]
 
-[[installation]]
-## Installation
+[[kpm-installation]]
+== KPM Installation
 
-[[pre-built-binaries-recommended-linux-and-macos-only]]
-### Pre-built binaries (recommended, Linux and MacOS only)
+[[pre-built-binaries-recommended]]
+=== Pre-built binaries (recommended)
+image:https://img.shields.io/maven-central/v/org.kill-bill.billing.installer/kpm?color=blue&label=kpm[kpm]
 
-Note that this installation method assumes `/bin/bash` to be available on your system.
+On Linux and MacOS, you can use the pre-built binaries. 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`.
 
-KPM 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).
 
-Download the package matching your architecture.
+Note that this installation method assumes `/bin/bash` to be available on your system.
 
 [[through-rubygems]]
-### 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 https://rvm.io/rvm/install[RVM]:
-
-....
-gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
-\curl -sSL https://get.rvm.io | bash -s stable --ruby
-....
+=== Through Rubygems
+image:https://img.shields.io/gem/v/kpm?color=blue&label=kpm[kpm]
 
-After following the post-installation instructions, you should have access to the `ruby` and `gem` executables.
+On Windows, you can install KPM via https://rubygems.org/gems/kpm[RubyGems.org]. For this, you need to first install Ruby. Ruby can be installed via https://rubyinstaller.org/[RubyInstaller]. Once installed, you can run the following command to install KPM:
+[source,bash]
+gem install kpm 
 
-You can then run:
 
-....
-gem install kpm
-....
 
-[[quick-start]]
-## Quick start
+[[kpm-commands]]
+== KPM Commands
 
-The following commands
+[[kill-bill-installation]]
+=== Kill Bill installation
 
-....
-mkdir killbill
-cd killbill
-kpm install
-....
+[[kpm-install]]
+==== kpm install
 
-will setup https://github.com/killbill/killbill[Kill Bill] and https://github.com/killbill/killbill-admin-ui-standalone[Kaui], i.e.:
+`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) 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 https://github.com/killbill/killbill-kpm-plugin[KPM plugin], required to (un-)install plugins at runtime
+* 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
 
@@ -71,28 +56,23 @@ To start Kill Bill, simply run
 
 You can then verify Kill Bill is running by going to http://127.0.0.1:8080/kaui.
 
-[[using-kpm]]
-## Using KPM
+[[kpm-install-using-a-kpm.yml-file]]
+==== kpm install Using A `kpm.yml` File
 
-[[custom-installation-through-kpm.yml-file]]
-### 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:
+KPM also lets you specify a configuration file, `kpm.yml`, to describe what should be installed. For example:
 
 ....
 killbill:
-  version: 0.18.0
+  version: 0.20.12
   plugins:
     java:
       - name: analytics
-    ruby:
-      - name: stripe
 ....
 
 This instructs kpm to:
 
-* Download Kill Bill version 0.18.0
-* Setup the https://github.com/killbill/killbill-analytics-plugin[Analytics] (Java) plugin and the https://github.com/killbill/killbill-stripe-plugin[Stripe] (Ruby) plugin
+* 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:
 
@@ -100,14 +80,11 @@ To start the installation:
 kpm install kpm.yml
 ....
 
-Here is a more advanced example:
+Here is a more advanced example, specifying a custom Nexus repository and non-standard deployment directories:
 
 ....
 killbill:
-  group_id: org.kill-bill.billing
-  artifact_id: killbill-profiles-killbill
-  version: 0.18.10
-  default_bundles_version: 0.36.11
+  version: 0.20.12
   nexus:
     ssl_verify: false
     url: http://nexus.acme
@@ -118,70 +95,45 @@ killbill:
       - 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
 ....
 
-[[custom-downloads]]
-### Custom Downloads
+[[artifacts-downloads]]
+==== Artifacts Downloads
 
-You can also download specific versions/artifacts directly with the following commands – bypassing the kpm.yml file:
+You can download specific artifacts with the following commands:
 
-* `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>`
+* `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
 
-For more details see `kpm help`.
+This is especially useful when scripting deployments.
 
-[[dev-mode]]
-### Dev Mode
+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`.
 
-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.
+[[kpm-uninstall]]
+==== kpm uninstall
 
-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 uninstall plugin-key` will uninstall a plugin identified by `plugin-key` (all versions are uninstalled by default).
 
-....
-kpm install_ruby_plugin 'dev:cybersource' --from-source-file="<PATH_TO>/killbill-cybersource-3.3.0.tar.gz"
-....
+[[kpm-migrations]]
+==== kpm migrations
 
-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 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.
 
-....
-kpm install_java_plugin 'dev:adyen' --from-source-file="<PATH_TO>/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2"
-....
+[[operations]]
+=== Operations
 
-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.
+[[kpm-inspect]]
+==== kpm inspect
 
-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:
+The command `kpm inspect` can be used to see which plugins have been installed:
 
 ....
-> 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
+kpm inspect --destination=/var/tmp/bundles
 _______________________________________________________________________________________________________________________________________________________
 |          PLUGIN NAME |  PLUGIN KEY | TYPE |                          GROUP ID |        ARTIFACT ID | PACKAGING | VERSIONS sha1=[], def=(*), del=(x) |
 _______________________________________________________________________________________________________________________________________________________
@@ -190,6 +142,56 @@ ________________________________________________________________________________
 _______________________________________________________________________________________________________________________________________________________
 ....
 
+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="<PATH_TO>/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2"
+....
+
 [[internals]]
 ## Internals
 
@@ -225,14 +227,17 @@ Test suite that requires an instance of `mysql` running and verifies the followi
 [[plugin-keys]]
 ### 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 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 Plugin Developer Guide.
+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, 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).
+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):
@@ -242,4 +247,36 @@ There are some non standard scenario that could occur in case of users tampering
 * `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.
+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)
+
+[[gh-packages]]
+### GitHub Packages
+
+Starting with version 0.9.0, experimental support for GitHub packages has been added:
+
+....
+kpm install_java_plugin acme:plugin \
+        --overrides url:https://maven.pkg.github.com/acme/plugin token:<TOKEN> \
+        --group-id com.acme \
+        --artifact-id plugin \
+        --version 0.0.1
+....
+
+Replace `TOKEN` with a GitHub personal access token.
+
+[[cloudsmith]]
+### Cloudsmith
+
+Starting with version 0.10.0, experimental support for Cloudsmith has been added:
+
+....
+kpm pull_kb_server_war 0.22.21-SNAPSHOT \
+        --overrides url:https://dl.cloudsmith.io/<TOKEN>/<ORG>/<REPO>/maven \
+        --group-id org.kill-bill.billing \
+        --artifact-id killbill-profiles-killbill
+....
+
+Replace `TOKEN` with a Cloudsmith entitlement token, and specify the right `ORG` and `REPO`.