Getting Started

This document explains what you need to get started using Kill Bill in your chosen environment. The first step is installing Kill Bill itself and the Kaui administrative console, along with their required database, in the environment you will be using. Make sure you read the overview to familiarize yourself with some concepts prior moving forward.

Kill Bill Installation

There are several different ways to get Kill Bill and Kaui up and running. The packages can be installed on your local computer (Windows, Mac, or Linux) or on a Linux server in the cloud. The three principal options are:

Use our one-click installer to install the programs using a ready-to-run container on a fresh AWS Ubuntu instance that you provide
Install Docker on your local machine or a new or existing cloud server instance. Then install Kill Bill and Kaui in a Docker container.
Install Kill Bill and Kaui, together with a MySQL database, directly on an Apache Tomcat server in your chosen environment.

These options are discussed in the subsequent sections.

AWS (One-Click)

If you prefer to run Kill Bill on a cloud server, and are familiar with AWS, this is the easiest and fastest way to get started. Just try out our One-Click installer. The page shows 3 options, we recommend you use the Single-Tier single AMI with MariaDB in this initial phase.

Docker

Overview

You can run Kill Bill locally or in the cloud using our official Docker images. These require the installation of Docker and Docker Compose. Docker Compose is used to set up and manage the three separate Docker containers required by Kill Bill: One each for Kill Bill itself, for Kaui, and for the shared SQL database engine.

The principal steps in the installation are:

Make sure that the required versions of Docker and Docker Compose are installed in your chosen environment.
Prepare a YAML file to control the loading of KillBill and the other necessary packages using Docker Compose.
Run Docker Compose to launch the packages in the web server.

Docker Installation

We recommend installing Docker Desktop for your operating system as explained here. Docker Desktop includes a GUI dashboard, a command line tool and other required components and makes it very easy to manage Docker containers.

Note that Docker Desktop for Windows requires installing WSL if you are on Windows 10 home as explained in the Windows installation document. If you are using a Linux environment, read the appropriate sections of the Docker Engine Overview.

Once Docker is set up,it greatly simplifies the Kill Bill stack setup, as Tomcat and MySQL configuration will be done for you.

The rest of the discussion assumes you have Docker installed. We will be using the Docker CLI on Mac, Windows, or Linux. Your Linux flavor is assumed to be Ubuntu, either on a local machine or on an AWS instance. Our blog has tips on how to deploy to other popular cloud providers. If you are using a different Linux flavor, you may have to adapt some of the commands.

Kill Bill Installation

Step 1 - Verify the Docker and Docker Compose versions.

To check whether Docker and Docker Compose are already installed, and what versions you have, open a command (or terminal) window and type the following commands:

   docker --version
   docker-compose --version

The versions that we are expecting for this discussion are:

Docker: 19.03.6 or higher
Docker Compose: 1.25.4 or higher

Step 2 - Create the docker-compose.yml file.

The next step is to create a YAML file called docker-compose.yml, similar to the one below. The version of the file shown is 3.2, which works with Docker 17.04.0 or higher. For information on compose file formats see compose file formats.

Ensure that you specify the latest versions of the Kill Bill, Kaui and MariaDB images in your docker-compose file. The latest versions at the time of writing are as follows:

Kill Bill - killbill/killbill:0.24.9
Kaui - killbill/kaui:3.0.6
MariaDB - killbill/mariadb:0.24

version: '3.2'
volumes:
  db:
services:
  killbill:
    image: killbill/killbill:0.24.10
    ports:
      - "8080:8080"
    environment:
      - KILLBILL_DAO_URL=jdbc:mysql://db:3306/killbill
      - KILLBILL_DAO_USER=root
      - KILLBILL_DAO_PASSWORD=killbill
      - KILLBILL_CATALOG_URI=SpyCarAdvanced.xml
  kaui:
    image: killbill/kaui:3.0.9
    ports:
      - "9090:8080"
    environment:
      - KAUI_CONFIG_DAO_URL=jdbc:mysql://db:3306/kaui
      - KAUI_CONFIG_DAO_USER=root
      - KAUI_CONFIG_DAO_PASSWORD=killbill
      - KAUI_KILLBILL_URL=http://killbill:8080
  db:
    image: killbill/mariadb:0.24
    volumes:
      - type: volume
        source: db
        target: /var/lib/mysql
    expose:
      - "3306"
    environment:
      - MYSQL_ROOT_PASSWORD=killbill

Step 3 - Run docker compose

Now place this file in your current directory and run:

docker-compose up

If all goes well 3 containers will start:

one for MariaDB (shared database, used by both Kill Bill and Kaui)
one for Kill Bill (accessible on port 8080)
one for Kaui (accessible on port 9090)

The startup sequence lasts a couple of minutes. It is ready when you see the message "INFO: Server startup". If it takes a long time or if the container crashes, verify you have enough memory allocated to Docker. On a Mac for instance, go to Docker Desktop Preferences and set the Memory to 4GiB in the Advanced panel. On Ubuntu, be sure you have at least 4GiB of RAM.

You should now be able to log-in to Kaui by going to http://<IP>:9090. If Docker is running on your local machine, <IP> is 127.0.0.1. Otherwise, it is the IP of your server.

You will be presented with a login page. Default credentials are:

username: admin
password: password

You can also go to http://<IP>:8080/api.html to explore the KillBill APIs.

FAQ

ERROR: unauthorized: authentication required

Sometimes, after running the docker-compose up command, you may see the following error:

ERROR: unauthorized: authentication required

In such cases, you can logout of docker and login again using the following commands:

docker logout
docker login # Specify your DockerHub credentials when prompted

Viewing Logs

The Kill Bill/Kaui startup logs can be viewed by running the following command:

docker logs <containerid>

In addition, the logs directory of both the Kill Bill and the Kaui containers contain individual log files. These can be viewed using the following commands:

docker exec <Kill Bill Container Id> tail -f logs/killbill.out #displays Kill Bill logs
docker exec <Kaui Container Id> tail -f logs/kaui.out #displays Kaui logs

Installing Docker on Mac and Ubuntu

If Docker or Docker Compose are not installed, on a Mac, one option is to try to install them using Homebrew:

brew install docker docker-compose

This may require that the free package Homebrew be installed first. See How to install Homebrew on Mac.

On Ubuntu we can use the following commands to install Docker:

sudo apt-get update
sudo apt-get install docker virtualbox

We have not installed Docker Compose in these commands, because the Ubuntu archive is not guaranteed to provide the latest version. Instead you should use the command

sudo curl -L https://github.com/docker/compose/releases/download/1.25.4/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose

This command should be set to load the latest stable release. For information on releases see the releases page.

Tomcat

Users familiar with Java technologies can also install Kill Bill and Kaui directly in the Web container of their choice. We recommend using Tomcat version 9.0.x. This section covers the instructions for installing Kill Bill and Kaui in Tomcat. If this approach is followed, you will also need to configure the database manually as explained below.

Tomcat Installation and configuration

The first step in installing Kill Bill in Tomcat is to download and install Tomcat. For this, you need to follow the steps given below:

Download the Core binary distribution of the Tomcat container from here (At the time of writing, 9.0.84 is the latest version, however it can change in the future as newer versions are released.) The downloaded zip file contains a folder called apache-tomcat-9.0.84
Extract apache-tomcat-9.0.91 and place it on any location on your computer. This path will be refered to as TOMCAT_HOME from now on. (For example, if you place apache-tomcat-9.0.91 in a directory called C:\Software, TOMCAT_HOME refers to C:\Software\apache-tomcat-9.0.91). It should look like this:
```
 $TOMCAT_HOME
     --bin
     --conf
     --lib
     --logs
     --temp
     --webapps
     --work
```
Ensure that you have JDK 11 installed ( OpenJDK is the default requirement, though Kill Bill supports all JDKs/JVMs. Oracle JDK can be downloaded from here)
Set the JAVA_HOME environment variable to the path of your JDK installation (For example, if JDK is installed at C:\Software\jdk11, you need to set JAVA_HOME to C:\Software\jdk11)
Start Tomcat using the script TOMCAT_HOME/bin/startup.sh or TOMCAT_HOME/bin/startup.bat (Depending on your operating system)
Open a browser and type http://localhost:8080/. If Tomcat is installed properly, it should display the following page:

Database Configuration (Kill Bill)

As mentioned above, you need to configure the Kill Bill database manually. For this, you need to follow the steps given below:

Install your database (The Kill Bill core team uses MySQL, but we also run regression tests against MariaDB 10 and PostgreSQL 12. Users have also successfully deployed Kill Bill with Oracle, Percona, Aurora, etc)
If you are using MySQL, you need to do the following:
1. Create a Kill Bill user as follows:
  create user killbill identified by 'killbill';
2. Create a Kill Bill database as follows:
  create database killbill;
3. Run the Kill Bill DDL here.
If you are using PostgreSQL, you can refer to the detailed instructions for PostgreSQL setup in our PostgreSQL Configuration document here

You should have a database called killbill (Or whatever name you have specified) with the following tables:

 account_email_history
 account_emails
 account_history
 accounts
 audit_log
 blocking_state_history
 blocking_states
 bundle_history
 bundles
 bus_events
 bus_events_history
 bus_ext_events
 bus_ext_events_history
 catalog_override_block_definition
 catalog_override_phase_definition
 catalog_override_phase_usage
 catalog_override_plan_definition
 catalog_override_plan_phase
 catalog_override_tier_block
 catalog_override_tier_definition
 catalog_override_usage_definition
 catalog_override_usage_tier
 custom_field_history
 custom_fields
 invoice_billing_events
 invoice_history
 invoice_item_history
 invoice_items
 invoice_parent_children
 invoice_payment_control_plugin_auto_pay_off
 invoice_payment_history
 invoice_payments
 invoice_tracking_id_history
 invoice_tracking_ids
 invoices
 node_infos
 notifications
 notifications_history
 payment_attempt_history
 payment_attempts
 payment_history
 payment_method_history
 payment_methods
 payment_transaction_history
 payment_transactions
 payments
 roles_permissions
 rolled_up_usage
 service_broadcasts
 sessions
 subscription_event_history
 subscription_events
 subscription_history
 subscriptions
 tag_definition_history
 tag_definitions
 tag_history
 tags
 tenant_broadcasts
 tenant_kvs
 tenants
 user_roles
 users

Kill Bill Configuration

The next step is to configure Kill Bill. For this, you need to follow the steps given below:

Download the current stable version of the Kill Bill war from Maven Central (Ensure that you download the killbill-profiles-killbill-X.Y.Z.war file and not the jetty-console.war, jar-with-dependencies.war or jar-with-dependencies-sources.war)
Rename the killbill-profiles-killbill-X.Y.Z.war to ROOT.war (Ensure that ROOT is in uppercase)
Ensure that Tomcat server is stopped
Delete everything under TOMCAT_HOME/webapps
Place ROOT.war at TOMCAT_HOME/webapps. So, webapps folder should look like this:
```
 $TOMCAT_HOME/webapps
     --ROOT.war
```

Open TOMCAT_HOME/conf/catalina.properties file.

Add the following database properties at the end of this file (Use appropriate values as per your database):

 org.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill
 org.killbill.dao.user=killbill
 org.killbill.dao.password=killbill
 org.killbill.billing.osgi.dao.url=jdbc:mysql://127.0.0.1:3306/killbill
 org.killbill.billing.osgi.dao.user=killbill
 org.killbill.billing.osgi.dao.password=killbill

Add the following property that specifies the Kill Bill URL for Kaui:
```
 kaui.url=http://127.0.0.1:8080
```

Start Tomcat using the script TOMCAT_HOME/bin/startup.sh or TOMCAT_HOME/bin/startup.bat (Depending on your operating system)
Verify that there are no errors in the Tomcat logs at TOMCAT_HOME/logs/catalina.log
Verify that there are no errors in the Kill Bill logs on the console and that the logs display a line which states that Kill Bill server has started
Open a browser and type http://localhost:8080/index.html. If Kill Bill is configured properly, it should display the following page:

Database Configuration (Kaui)

In addition to the Kill Bill database, you will also need to configure the Kaui database. For this, you need to follow the steps given below. By default Kill Bill expects MySQL, but you can also use PostgreSQL.

MySQL Configuration

Create a database. In MySQL, you can run the following commands to create a database called kaui:
```
    create database kaui;
```
Run the Kaui DDL here.
If you are using PostgreSQL, you can refer to the detailed instructions for PostgreSQL setup in our PostgreSQL Configuration document here

You should have a database called kaui (Or whatever name you have specified in step 1) with the following tables:

 kaui_users
 kaui_tenants
 kaui_allowed_users
 kaui_allowed_user_tenants

Kaui Configuration

Finally, Kaui needs to be configured. For this, you need to follow the steps given below:

Download the current stable version ( V 3.0.9 ) of the Kaui war from Maven Central.
Rename the downloaded war to ROOT.war (Ensure that ROOT is in uppercase)
Ensure that Tomcat server is stopped
Create a folder called TOMCAT_HOME/webapps2
Place ROOT.war at TOMCAT_HOME/webapps2. So, webapps2 folder should look like this:
```
 $TOMCAT_HOME/webapps2
     --ROOT.war
```

Open TOMCAT_HOME/conf/server.xml. Add the following section below </Service> (specify a port other than 8080. The snippet below specifies 9090):

 <!-- KAUI -->
  <Service name="Catalina">


    <Connector port="9090"
               protocol="HTTP/1.1"
               connectionTimeout="20000" />

    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost"
            appBase="webapps2"
            unpackWARs="true"
            autoDeploy="false"><!-- Disable autoDeploy to avoid restarts when running KPM install -->

        <Valve className="org.apache.catalina.valves.RemoteIpValve"
               protocolHeader="x-forwarded-proto"
               portHeader="x-forwarded-port" />

        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs"
               prefix="localhost_kaui_log."
               suffix=".txt"
               pattern="%h %l %u %t &quot;%m %U&quot; %s %b %D %{X-Request-id}i" />

        <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" />
      </Host>
    </Engine>
  </Service>

Open TOMCAT_HOME/conf/catalina.properties file. Add the following database properties related to Kaui at the end of this file (Use appropriate values as per your database):
```
 kaui.db.url=jdbc:mysql://127.0.0.1:3306/kaui
 kaui.db.username=killbill
 kaui.db.password=killbill
```
Add the following Kaui config property as well to TOMCAT_HOME/conf/catalina.properties file (Use appropriate string as per your choice):
```
 kaui.secret_key_base=abcadtfsetdyghuiyhtyehfktgn
```
Start Tomcat using the script TOMCAT_HOME/bin/startup.sh or TOMCAT_HOME/bin/startup.bat (Depending on your operating system)
Verify that there are no errors in the Tomcat logs at TOMCAT_HOME/logs/catalina.log
Verify that there are no errors in the Kill Bill logs on the console and that the logs display a line which states that Kill Bill server has started
Open a browser and type http://localhost:9090 This should display the following sign in page:
Sign in with admin/password. This should display the following page:

Customizing Log File Path

The steps above configure the application so that the Kill Bill and Kaui logs are displayed on the console. You can however customise this to save the logs in a separate log file. In order to set this up, you need to follow the steps given below:

Create a file called logback.xml as follows:

 <?xml version="1.0" encoding="UTF-8"?>
 <configuration scan="true" scanPeriod="30 seconds">
   <jmxConfigurator />
   <property name="LOGS_DIR" value="<log_file_path>" />
   <appender name="MAIN" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <file>${LOGS_DIR:-./logs}/killbill.out</file>
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
         <!-- rollover daily -->
         <fileNamePattern>${LOGS_DIR:-./logs}/killbill-%d{yyyy-MM-dd}.%i.out.gz</fileNamePattern>
         <maxHistory>3</maxHistory>
         <cleanHistoryOnStart>true</cleanHistoryOnStart>
         <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
            <!-- or whenever the file size reaches 100MB -->
            <maxFileSize>100MB</maxFileSize>
         </timeBasedFileNamingAndTriggeringPolicy>
      </rollingPolicy>
      <encoder>
         <pattern>%date{"yyyy-MM-dd'T'HH:mm:ss,SSSZ", UTC} lvl='%level', log='%logger{0}', th='%thread', xff='%X{req.xForwardedFor}', rId='%X{req.requestId}', tok='%X{kb.userToken}', aRId='%X{kb.accountRecordId}', tRId='%X{kb.tenantRecordId}', %msg%n</pattern>
      </encoder>
   </appender>
   <appender name="KAUI" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <file>${LOGS_DIR:-./logs}/kaui.out</file>
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
         <!-- rollover daily -->
         <fileNamePattern>${LOGS_DIR:-./logs}/kaui-%d{yyyy-MM-dd}.%i.out.gz</fileNamePattern>
         <maxHistory>3</maxHistory>
         <cleanHistoryOnStart>true</cleanHistoryOnStart>
         <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
            <!-- or whenever the file size reaches 100MB -->
            <maxFileSize>100MB</maxFileSize>
         </timeBasedFileNamingAndTriggeringPolicy>
      </rollingPolicy>
      <encoder>
         <pattern>%date{"yyyy-MM-dd'T'HH:mm:ss,SSSZ", UTC} lvl='%level', log='%X{rails.actionName}', th='%thread',
                xff='%X{req.xForwardedFor}', rId='%X{req.requestId}', aId='%X{kb.accountId}', tId='%X{kb.tenantId}',
                %msg%n</pattern>
      </encoder>
   </appender>
   <logger name="jdbc" level="OFF" />
   <root level="INFO">
      <appender-ref ref="MAIN" />
      <appender-ref ref="KAUI" />
   </root>
</configuration>

Replace <log_file_path> above with the path where you want the logs to be created. For example, if you’d like the logs to be in a directory called c:/logs, you need to replace <log_file_path> with c:/logs
Open TOMCAT_HOME/conf/catalina.properties file. Add the following property:
```
  logback.configurationFile=<path_of_logback.xml>
```
Replace <path_of_logback.xml> above with the actual path of your logback.xml. For example, if logback.xml is placed at c:/logbackpath, you need to replace <path_of_logback.xml> with c:/logbackpath/logback.xml
Restart Tomcat. Now, the logs will be created at the path specified in the logback.xml file. Separate log files will get created for Kill Bill and Kaui as follows:
```
  <log_file_path>/killbill.out
  <log_file_path>/kaui.out
```

Masking Data in Logs

Sometimes, you may wish to mask some sensitive data in the logs. For this, you need to do the following:

Set the following system properties (Refer docs):

  killbill.server.log.obfuscate.keywords=xxx
  killbill.server.log.obfuscate.patterns=xxx
  killbill.server.log.obfuscate.patterns.separator=xxx

In your logback.xml, configure the ObfuscatorConverter by adding the following line below <jmxConfigurator />:

 <conversionRule conversionWord="maskedMsg" converterClass="org.killbill.billing.server.log.obfuscators.ObfuscatorConverter" />

Restart Kill Bill - Sensitive data in the logs (as configured by the system properties above) should now be masked.

Some key-value pattern examples that can be specified corresponding to the killbill.server.log.obfuscate.patterns property:

\s*=\s*'([^']+)' - Matches key = 'value'
\s*=\s*"([^"]+)" - Matches key = "value"
\s*:\s*'([^']+)' - Matches key: 'value'
\s*=\s*([^ '",{}]+) - Matches name = value
\s*:\s*'([^'",{}]+)' - Matches key: 'value'

Setting up KPM in Kaui

KPM stands for Kill Bill Package Manager. It can be used to manage plugins. You can read this article to know more about kpm.

Setting up kpm in Kaui is an optional step. It is required only for performing plugin-related actions like install, uninstall, restart plugins directly via Kaui.

In order to set up KPM in Kaui, you need to do the following:

Ensure that you have kpm installed as per the instructions here.
Open a command prompt/terminal window and run the following command (Replace <kpm_bundles_path> with the actual path where you would like to install the kpm bundles):
```
kpm pull_defaultbundles --destination=<kpm_bundles_path>
```

Ensure that this downloads the jar files corresponding to the kpm bundles. So, your kpm_bundles_path should look like this:

$kpm_bundles_path
--platform
--platform/killbill-platform-osgi-bundles-kpm-0.40.4.jar
--platform/killbill-platform-osgi-bundles-logger-0.40.4.jar
--sha1.yml

Add the following properties to the TOMCAT_HOME/conf/catalina.properties file:
```
org.killbill.osgi.bundle.install.dir=<kpm_bundles_path>
```
Replace <kpm_bundles_path> with the actual path where the kpm bundles are installed in Step 2 above.
Restart Tomcat.
Verify that there are no errors in the Kill Bill logs.
Open a browser and type `http://localhost:8080/kaui. Sign in using admin/password. This should now display a plug icon in Kaui as follows:
On Clicking kpm, you should see the following screen:
On clicking Install New Plugin you should see the following screen:

In order to know more about how to use kpm in kaui, you can refer to our Kaui tutorial.

Other Notes

We recommend installing the Apache Tomcat Native Library. In order to do this, you need to follow the steps given below:

Download the Tomcat Native Library from here.
Install the Tomcat Native Library as per the instructions given here.

If you are unable to install the Tomcat Native Library on Windows, you may skip this step.

Further Debugging

The Debugging Tips document includes some additional debugging tips for Kill Bill in general. You may also reach out to the Kill Bill mailing list, with the kpm diagnostic output as explained in the Seeking Help section.

FAQ

This section lists some errors that are commonly encountered while setting up Kill Bill and Kaui with Tomcat and how you can fix these errors.

Logs not created

Sometimes, even after configuring your logback.xml file as specified in the Customizing Log File Path section, logs might not be created. This is most probably because your logback.xml is not a valid XML file. Some reasons for an XML file to be invalid are leading spaces, unclosed XML tags. In general, if you are able to open the XML file in a web browser without any errors, your XML file is valid.

Application points to the default Database

Sometimes, when the application is started, it may use the default H2 database and cause the following errors:

Caused by: org.h2.jdbc.JdbcSQLNonTransientConnectionException: A file path that is implicitly relative to the current working directory is not allowed in the database URL "jdbc:h2:file:/var/tmp/killbill;MODE=MYSQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE". Use an absolute path, ~/name, ./name, or the baseDir setting instead. [90011-200]
        at org.h2.message.DbException.getJdbcSQLException(DbException.java:622)
        at org.h2.message.DbException.getJdbcSQLException(DbException.java:429)
        at org.h2.message.DbException.get(DbException.java:205)
        at org.h2.message.DbException.get(DbException.java:181)
        at org.h2.engine.ConnectionInfo.getName(ConnectionInfo.java:396)
        at org.h2.engine.Engine.openSession(Engine.java:50)
        at org.h2.engine.Engine.openSession(Engine.java:192)
        at org.h2.engine.Engine.createSessionAndValidate(Engine.java:171)
        at org.h2.engine.Engine.createSession(Engine.java:166)
        at org.h2.engine.Engine.createSession(Engine.java:29)
        at org.h2.engine.SessionRemote.connectEmbeddedOrServer(SessionRemote.java:340)
        at org.h2.jdbc.JdbcConnection.<init>(JdbcConnection.java:173)
        at org.h2.jdbc.JdbcConnection.<init>(JdbcConnection.java:152)
        at org.h2.Driver.connect(Driver.java:69)
        at org.h2.jdbcx.JdbcDataSource.getJdbcConnection(JdbcDataSource.java:189)
        at org.h2.jdbcx.JdbcDataSource.getConnection(JdbcDataSource.java:178)
        at com.zaxxer.hikari.pool.PoolBase.newConnection(PoolBase.java:358)
        at com.zaxxer.hikari.pool.PoolBase.newPoolEntry(PoolBase.java:206)
        at com.zaxxer.hikari.pool.HikariPool.createPoolEntry(HikariPool.java:477)
        at com.zaxxer.hikari.pool.HikariPool.access$100(HikariPool.java:71)
        at com.zaxxer.hikari.pool.HikariPool$PoolEntryCreator.call(HikariPool.java:725)
        at com.zaxxer.hikari.pool.HikariPool$PoolEntryCreator.call(HikariPool.java:711)
        at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)

This error is mostly because the database properties are not correctly specified. Ensure that the database properties are specified correctly in the TOMCAT_HOME/conf/catalina.properties file as specified in the Kill Bill Configuration section above

Plug Icon not seen in Kaui

Sometimes, even after configuring kpm in kaui as specified in the Setting up KPM in Kaui section above, the plug icon is not visible in Kaui. The following error is displayed in the KillBill logs:

org.osgi.framework.BundleException: Duplicate import: org.joda.time.format
	at org.apache.felix.framework.util.manifestparser.ManifestParser.normalizeImportClauses(ManifestParser.java:366)
	at org.apache.felix.framework.util.manifestparser.ManifestParser.<init>(ManifestParser.java:180)
	at org.apache.felix.framework.BundleRevisionImpl.<init>(BundleRevisionImpl.java:121)
	at org.apache.felix.framework.BundleImpl.createRevision(BundleImpl.java:1243)
	at org.apache.felix.framework.BundleImpl.<init>(BundleImpl.java:112)
	at org.apache.felix.framework.Felix.installBundle(Felix.java:2907)
	at org.apache.felix.framework.BundleContextImpl.installBundle(BundleContextImpl.java:165)
	at org.apache.felix.framework.BundleContextImpl.installBundle(BundleContextImpl.java:138)
	at org.killbill.billing.osgi.FileInstall.installOSGIBundle(FileInstall.java:151)
	at org.killbill.billing.osgi.FileInstall.installAllOSGIBundles(FileInstall.java:142)
	at org.killbill.billing.osgi.FileInstall.installBundles(FileInstall.java:91)
	at org.killbill.billing.osgi.BundleRegistry.installBundles(BundleRegistry.java:64)
	at org.killbill.billing.osgi.DefaultOSGIService.initialize(DefaultOSGIService.java:92)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.killbill.billing.lifecycle.DefaultLifecycle.doFireStage(DefaultLifecycle.java:154)
	at org.killbill.billing.lifecycle.DefaultLifecycle.fireSequence(DefaultLifecycle.java:141)
	at org.killbill.billing.lifecycle.DefaultLifecycle.fireStartupSequencePriorEventRegistration(DefaultLifecycle.java:82)
	at org.killbill.billing.server.listeners.KillbillPlatformGuiceListener.startLifecycle(KillbillPlatformGuiceListener.java:308)
	at org.killbill.billing.server.listeners.KillbillPlatformGuiceListener.contextInitialized(KillbillPlatformGuiceListener.java:130)
	at org.apache.catalina.core.StandardContext.listenerStart(StandardContext.java:4689)
	at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:5155)
	at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:183)
	at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:743)
	at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:719)
	at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:705)
	at org.apache.catalina.startup.HostConfig.deployWAR(HostConfig.java:970)
	at org.apache.catalina.startup.HostConfig$DeployWar.run(HostConfig.java:1840)
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
	at java.lang.Thread.run(Thread.java:745)

This typically happens on Windows machines. In such a case, delete <kpm_bundles_path>/platform/killbill-platform-osgi-bundles-jruby-0.40.4.jar if present. Restart Tomcat. This should fix the issue.

SQLException on startup

Sometimes, even after configuring everything as explained above, the following exception might occur when Kill Bill is started:

Caused by: java.sql.SQLTransientConnectionException: Could not connect to address=(host=127.0.0.1)(port=3306)(type=master) : RSA public key is not available client side (option serverRsaPublicKeyFile not set)
	at org.mariadb.jdbc.internal.util.exceptions.ExceptionFactory.createException(ExceptionFactory.java:79)
	at org.mariadb.jdbc.internal.util.exceptions.ExceptionFactory.create(ExceptionFactory.java:153)
	at org.mariadb.jdbc.MariaDbDataSource.getConnection(MariaDbDataSource.java:305)
	at com.zaxxer.hikari.pool.PoolBase.newConnection(PoolBase.java:364)
	at com.zaxxer.hikari.pool.PoolBase.newPoolEntry(PoolBase.java:206)
	at com.zaxxer.hikari.pool.HikariPool.createPoolEntry(HikariPool.java:476)
	at com.zaxxer.hikari.pool.HikariPool.access$100(HikariPool.java:71)
	at com.zaxxer.hikari.pool.HikariPool$PoolEntryCreator.call(HikariPool.java:726)
	at com.zaxxer.hikari.pool.HikariPool$PoolEntryCreator.call(HikariPool.java:712)
	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
	at java.lang.Thread.run(Thread.java:745)

Some later versions of MySQL require requesting a public key from the server. Thus, the database connection string needs to be specified as follows in the TOMCAT_HOME/conf/catalina.properties file file:

org.killbill.dao.url=jdbc:mysql://127.0.0.1:3306/killbill?allowPublicKeyRetrieval=true&useSSL=false
org.killbill.billing.osgi.dao.url=jdbc:mysql://127.0.0.1:3306/killbill?allowPublicKeyRetrieval=true&useSSL=false

ClassNotFoundException on startup

Sometimes, even after configuring everything as explained above, the following exception might occur when Kill Bill is started:

Caused by: java.lang.ClassNotFoundException: jar file 'killbill-api-0.53.17.jar' could not be instantiate from file path. Error: C:\Users\<username>\.m2\repository\org\kill-bill\billing\killbill-api\0.53.17\killbill-api-0.53.17.jar (The system cannot find the path specified)
    at org.killbill.billing.lifecycle.ServiceFinder.findClasses (ServiceFinder.java:130)
    at org.killbill.billing.lifecycle.ServiceFinder.initialize (ServiceFinder.java:64)
    at org.killbill.billing.lifecycle.ServiceFinder.<init> (ServiceFinder.java:48)
    at org.killbill.billing.util.glue.IDBISetup.mapperFactoriesToRegister (IDBISetup.java:65)
    at org.killbill.billing.server.modules.KillbillServerModule.configureDao (KillbillServerModule.java:127)
    at org.killbill.billing.server.modules.KillbillPlatformModule.configure (KillbillPlatformModule.java:86)
    at org.killbill.billing.server.modules.KillbillServerModule.configure (KillbillServerModule.java:99)
    at com.google.inject.AbstractModule.configure (AbstractModule.java:61)
    at com.google.inject.spi.Elements$RecordingBinder.install (Elements.java:347)
    at com.google.inject.spi.Elements.getElements (Elements.java:104)
    at com.google.inject.internal.InjectorShell$Builder.build (InjectorShell.java:137)

This error typically occurs on Windows machines and is most probably due to a space being present in the Maven repository path. By default, on Windows, Maven uses the C:\Users\<username>\.m2\ path for the local repository. If there is a space in the <username>, this error can occur. In order to get rid of this error you can change the path of the Maven local repository using the following steps:

Open <MAVEN_HOME>/conf/settings.xml.
Update <localRepository> to the desired path. For example, to create the Maven local repository at the c:/mavenrepo path, you need to specify <localRepository>c:/mavenrepo</localRepository>.
Restart tomcat.

Next steps

Create your first tenant, simple catalog, account, payment method, and subscription by following the steps in the either of these guides:

Explore our full API documentation.

We also have lots of examples in our Ruby and Java integration tests.

For support along the way, do not open GitHub issues. Instead, reach out to our Google Group. Our GitHub sponsors can also jump on our VIP community Slack channel.

PreviousPrev NextNext