Kill Bill

Key Features

• Advanced subscription lifecycle management with support for trials, upgrades, downgrades, and complex proration calculations
• Flexible catalog system supporting multiple pricing models including flat-rate, tiered, usage-based, and hybrid billing structures
• Plugin architecture with pre-built integrations for Stripe, Adyen, PayPal, and other major payment gateways
• Comprehensive dunning management with customizable retry logic and payment failure handling workflows
• Multi-tenant architecture supporting multiple business units or white-label scenarios within a single deployment
• Advanced invoice generation with customizable templates, line-item breakdowns, and automatic tax calculation support
• Real-time analytics and reporting through Kaui's dashboard with subscription metrics, churn analysis, and revenue tracking
• REST API with comprehensive webhook system for integrating billing events into external systems and business intelligence tools

Common Use Cases

• 1SaaS companies with tiered pricing plans requiring automated upgrade/downgrade handling and usage-based billing components
• 2Subscription box services needing flexible billing cycles, seasonal adjustments, and inventory-linked subscription management
• 3Enterprise software vendors requiring complex contract billing with custom terms, annual prepayments, and mid-cycle adjustments
• 4Digital content platforms managing freemium models with trial periods, feature-based upgrades, and usage metering
• 5Managed service providers billing for infrastructure usage, support tiers, and add-on services with detailed invoice breakdowns
• 6Multi-brand organizations needing centralized billing infrastructure with tenant isolation and brand-specific payment processing
• 7Fintech companies building billing capabilities into their platforms while maintaining PCI compliance and payment gateway flexibility

Prerequisites

• Minimum 2GB RAM available for the full stack, with 1GB dedicated to Kill Bill and 512MB for MySQL operations
• Basic understanding of subscription billing concepts including proration, dunning, and payment gateway integration workflows
• Ports 8080 and 9090 available on the host system for Kill Bill API and Kaui web interface access
• Familiarity with XML catalog configuration for defining products, plans, phases, and pricing rules in Kill Bill
• MySQL administration knowledge for backup procedures, performance tuning, and troubleshooting database connectivity issues
• SSL certificates and reverse proxy setup knowledge for production deployments handling sensitive payment data

docker-compose.yml

1services: 
2  killbill: 
3    image: killbill/killbill:latest
4    container_name: killbill
5    restart: unless-stopped
6    environment: 
7      KILLBILL_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
8      KILLBILL_DAO_USER: ${DB_USER}
9      KILLBILL_DAO_PASSWORD: ${DB_PASSWORD}
10    ports: 
11      - "8080:8080"
12    depends_on: 
13      - mysql
14    networks: 
15      - killbill
16
17  kaui: 
18    image: killbill/kaui:latest
19    container_name: kaui
20    environment: 
21      KAUI_CONFIG_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
22      KAUI_CONFIG_DAO_USER: ${DB_USER}
23      KAUI_CONFIG_DAO_PASSWORD: ${DB_PASSWORD}
24      KAUI_KILLBILL_URL: http://killbill:8080
25    ports: 
26      - "9090:8080"
27    depends_on: 
28      - killbill
29    networks: 
30      - killbill
31
32  mysql: 
33    image: mysql:8.0
34    container_name: killbill-mysql
35    environment: 
36      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
37      MYSQL_DATABASE: ${DB_NAME}
38      MYSQL_USER: ${DB_USER}
39      MYSQL_PASSWORD: ${DB_PASSWORD}
40    volumes: 
41      - mysql_data:/var/lib/mysql
42    networks: 
43      - killbill
44
45volumes: 
46  mysql_data: 
47
48networks: 
49  killbill: 
50    driver: bridge

.env Template

1DB_ROOT_PASSWORD=rootpassword
2DB_NAME=killbill
3DB_USER=killbill
4DB_PASSWORD=changeme

Usage Notes

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

killbill:
  image: killbill/killbill:latest
  container_name: killbill
  restart: unless-stopped
  environment:
    KILLBILL_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
    KILLBILL_DAO_USER: ${DB_USER}
    KILLBILL_DAO_PASSWORD: ${DB_PASSWORD}
  ports:
    - "8080:8080"
  depends_on:
    - mysql
  networks:
    - killbill

kaui:
  image: killbill/kaui:latest
  container_name: kaui
  environment:
    KAUI_CONFIG_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
    KAUI_CONFIG_DAO_USER: ${DB_USER}
    KAUI_CONFIG_DAO_PASSWORD: ${DB_PASSWORD}
    KAUI_KILLBILL_URL: http://killbill:8080
  ports:
    - "9090:8080"
  depends_on:
    - killbill
  networks:
    - killbill

mysql:
  image: mysql:8.0
  container_name: killbill-mysql
  environment:
    MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    MYSQL_DATABASE: ${DB_NAME}
    MYSQL_USER: ${DB_USER}
    MYSQL_PASSWORD: ${DB_PASSWORD}
  volumes:
    - mysql_data:/var/lib/mysql
  networks:
    - killbill

Quick Start

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  killbill:
5    image: killbill/killbill:latest
6    container_name: killbill
7    restart: unless-stopped
8    environment:
9      KILLBILL_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
10      KILLBILL_DAO_USER: ${DB_USER}
11      KILLBILL_DAO_PASSWORD: ${DB_PASSWORD}
12    ports:
13      - "8080:8080"
14    depends_on:
15      - mysql
16    networks:
17      - killbill
18
19  kaui:
20    image: killbill/kaui:latest
21    container_name: kaui
22    environment:
23      KAUI_CONFIG_DAO_URL: jdbc:mysql://mysql:3306/${DB_NAME}
24      KAUI_CONFIG_DAO_USER: ${DB_USER}
25      KAUI_CONFIG_DAO_PASSWORD: ${DB_PASSWORD}
26      KAUI_KILLBILL_URL: http://killbill:8080
27    ports:
28      - "9090:8080"
29    depends_on:
30      - killbill
31    networks:
32      - killbill
33
34  mysql:
35    image: mysql:8.0
36    container_name: killbill-mysql
37    environment:
38      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
39      MYSQL_DATABASE: ${DB_NAME}
40      MYSQL_USER: ${DB_USER}
41      MYSQL_PASSWORD: ${DB_PASSWORD}
42    volumes:
43      - mysql_data:/var/lib/mysql
44    networks:
45      - killbill
46
47volumes:
48  mysql_data:
49
50networks:
51  killbill:
52    driver: bridge
53EOF
54
55# 2. Create the .env file
56cat > .env << 'EOF'
57DB_ROOT_PASSWORD=rootpassword
58DB_NAME=killbill
59DB_USER=killbill
60DB_PASSWORD=changeme
61EOF
62
63# 3. Start the services
64docker compose up -d
65
66# 4. View logs
67docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

1curl -fsSL https://docker.recipes/api/recipes/killbill/run | bash

Troubleshooting