Deploying Kill Bill

Introduction

Kill Bill is the leading open-source subscription billing and payments platform, designed to handle complex billing scenarios at enterprise scale. Whether you need simple recurring subscriptions, usage-based billing, or sophisticated hybrid models, Kill Bill provides the flexibility and reliability to power your billing operations.

Built with Java and battle-tested by companies processing millions of transactions, Kill Bill offers a complete billing system including catalog management, subscription lifecycle handling, invoicing, payment processing, and comprehensive analytics. The plugin architecture allows integration with virtually any payment gateway, tax service, or external system.

Key highlights of Kill Bill:

Subscription Management: Handle complex subscription lifecycles with upgrades, downgrades, and cancellations
Flexible Billing Models: Support recurring, usage-based, one-time, and hybrid billing
Multi-Currency: Process payments in multiple currencies with automatic conversion
Payment Gateway Plugins: Integrate with Stripe, Adyen, PayPal, and many more
Invoicing Engine: Automatic invoice generation with customizable templates
Tax Integration: Connect with Avalara, TaxJar, or custom tax providers
Dunning Management: Automated payment retry and failed payment handling
Analytics: Comprehensive reporting on revenue, churn, and customer metrics
Multi-Tenancy: Isolate data for multiple business units or clients
REST API: Full API coverage for all billing operations

This guide walks through deploying Kill Bill on Klutch.sh using Docker, configuring the database, and setting up Kaui (the admin console).

Why Deploy Kill Bill on Klutch.sh

Deploying Kill Bill on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Kill Bill from your Dockerfile without complex Java infrastructure management.

Persistent Storage: Attach persistent volumes for database storage and configuration persistence.

HTTPS by Default: Secure billing operations with automatic SSL certificates.

Environment Variable Management: Store database credentials and API keys securely.

Scalable Resources: Allocate CPU and memory based on transaction volume.

Prerequisites

Before deploying Kill Bill on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and billing concepts
A MySQL or PostgreSQL database

Preparing Your Repository

To deploy Kill Bill on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

killbill-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM killbill/killbill:latest

# Environment variables configured via Klutch.sh dashboard
# KILLBILL_DAO_URL - Database connection URL
# KILLBILL_DAO_USER - Database username
# KILLBILL_DAO_PASSWORD - Database password

EXPOSE 8080

Environment Variables Reference

Variable	Required	Description
`KILLBILL_DAO_URL`	Yes	JDBC database URL
`KILLBILL_DAO_USER`	Yes	Database username
`KILLBILL_DAO_PASSWORD`	Yes	Database password
`KILLBILL_CATALOG_URI`	No	URI to catalog configuration
`KILLBILL_SECURITY_SHIRO_NB_HASH_ITERATIONS`	No	Hash iterations (set to 1 for Docker)

For PostgreSQL, also set:

Variable	Value
`KILLBILL_DAO_DRIVER`	`org.postgresql.Driver`

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Deploying Kill Bill on Klutch.sh

Set Up Database

Kill Bill requires MySQL or PostgreSQL:

Use a managed database service
Deploy a database on Klutch.sh
Note your connection details

For MySQL, the connection URL format is: jdbc:mysql://host:3306/killbill

For PostgreSQL: jdbc:postgresql://host:5432/killbill

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Kill Bill deployment configuration"
git remote add origin https://github.com/yourusername/killbill-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “killbill” or “billing”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Kill Bill repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

Variable	Value
`KILLBILL_DAO_URL`	`jdbc:mysql://host:3306/killbill`
`KILLBILL_DAO_USER`	Your database username
`KILLBILL_DAO_PASSWORD`	Your database password
`KILLBILL_SECURITY_SHIRO_NB_HASH_ITERATIONS`	`1`

Deploy Your Application

Click Deploy to start the build process. Kill Bill initialization may take a few minutes.

Access Kill Bill

Once deployment completes, access the API at https://your-app-name.klutch.sh.

Deploying Kaui (Admin Console)

Kaui is Kill Bill’s web admin interface. Deploy it alongside Kill Bill:

Kaui Dockerfile

Create a separate repository or app for Kaui:

FROM killbill/kaui:latest

# Point to your Kill Bill instance
ENV KAUI_KILLBILL_URL=https://your-killbill-app.klutch.sh
ENV KAUI_KILLBILL_API_KEY=bob
ENV KAUI_KILLBILL_API_SECRET=lazar

# Database for Kaui (can share with Kill Bill or separate)
ENV KAUI_CONFIG_DAO_URL=${KAUI_DB_URL}
ENV KAUI_CONFIG_DAO_USER=${KAUI_DB_USER}
ENV KAUI_CONFIG_DAO_PASSWORD=${KAUI_DB_PASSWORD}

EXPOSE 8080

Kaui Environment Variables

Variable	Description
`KAUI_KILLBILL_URL`	URL of your Kill Bill instance
`KAUI_KILLBILL_API_KEY`	API key (default: bob)
`KAUI_KILLBILL_API_SECRET`	API secret (default: lazar)
`KAUI_CONFIG_DAO_URL`	Kaui database URL
`KAUI_CONFIG_DAO_USER`	Database username
`KAUI_CONFIG_DAO_PASSWORD`	Database password

Initial Configuration

Default Credentials

Kill Bill default admin credentials:

Username: admin
Password: password
API Key: bob
API Secret: lazar

Change these immediately in production.

Creating a Tenant

Multi-tenancy is core to Kill Bill:

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -H "X-Killbill-CreatedBy: admin" \
  -d '{
    "apiKey": "my-api-key",
    "apiSecret": "my-api-secret",
    "externalKey": "my-tenant"
  }' \
  https://your-app-name.klutch.sh/1.0/kb/tenants

Uploading a Catalog

Define your products and pricing:

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/xml" \
  -H "X-Killbill-ApiKey: my-api-key" \
  -H "X-Killbill-ApiSecret: my-api-secret" \
  -H "X-Killbill-CreatedBy: admin" \
  -d @catalog.xml \
  https://your-app-name.klutch.sh/1.0/kb/catalog

Example Catalog

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <effectiveDate>2024-01-01T00:00:00+00:00</effectiveDate>
  <catalogName>MyCompany</catalogName>
  <currencies>
    <currency>USD</currency>
  </currencies>
  <products>
    <product name="Basic">
      <category>BASE</category>
    </product>
    <product name="Pro">
      <category>BASE</category>
    </product>
  </products>
  <rules>
    <changePolicy>
      <changePolicyCase>
        <policy>IMMEDIATE</policy>
      </changePolicyCase>
    </changePolicy>
  </rules>
  <plans>
    <plan name="basic-monthly">
      <product>Basic</product>
      <finalPhase type="EVERGREEN">
        <duration>
          <unit>UNLIMITED</unit>
        </duration>
        <recurring>
          <billingPeriod>MONTHLY</billingPeriod>
          <recurringPrice>
            <price>
              <currency>USD</currency>
              <value>9.99</value>
            </price>
          </recurringPrice>
        </recurring>
      </finalPhase>
    </plan>
  </plans>
  <priceLists>
    <defaultPriceList name="DEFAULT">
      <plans>
        <plan>basic-monthly</plan>
      </plans>
    </defaultPriceList>
  </priceLists>
</catalog>

Installing Payment Plugins

Stripe Plugin

# Install Stripe plugin
curl -X POST \
  -u admin:password \
  -H "X-Killbill-CreatedBy: admin" \
  https://your-app-name.klutch.sh/1.0/kb/nodesInfo \
  -d 'pluginKey=stripe&pluginVersion=LATEST'

Configure Plugin

After installation, configure with your Stripe keys through the Kill Bill API or Kaui interface.

Production Best Practices

Security

Change Default Credentials: Update admin password and API keys immediately
Database Security: Use strong passwords and encrypted connections
API Key Rotation: Regularly rotate tenant API keys

Performance

Database Tuning: Optimize MySQL/PostgreSQL for transactional workloads
Connection Pooling: Configure appropriate pool sizes
Caching: Enable Kill Bill’s caching layers

Monitoring

Health Checks: Monitor /1.0/healthcheck endpoint
Metrics: Export metrics to your monitoring system
Audit Logs: Review audit trails regularly

Troubleshooting Common Issues

Database Connection Errors

Solutions:

Verify JDBC URL format
Check database credentials
Ensure database is accessible from Klutch.sh

Slow Startup

Solutions:

Kill Bill initialization takes 2-5 minutes
Allocate sufficient memory (2GB+ recommended)
Check database performance

Plugin Issues

Solutions:

Verify plugin compatibility with Kill Bill version
Check plugin logs in Kill Bill logs
Ensure plugin dependencies are available

Additional Resources

Conclusion

Deploying Kill Bill on Klutch.sh gives you an enterprise-grade subscription billing platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Kill Bill’s comprehensive billing features and Klutch.sh’s deployment simplicity means you can focus on your business model rather than billing infrastructure.

Whether handling simple subscriptions or complex enterprise billing scenarios, Kill Bill on Klutch.sh provides the foundation for reliable, scalable billing operations.