Kill Bill

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Kill Bill by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTPS (443). Then select Review + create and Create.

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:killbill-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-resource-group \
  --name killbill \
  --image sac1647283583153:killbill-ubuntu-24-04:default:latest \
  --size Standard_B2ms \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open HTTPS to your users, and HTTP as well if you want the redirect:

az vm open-port --resource-group my-resource-group --name killbill --port 443 --priority 900
az vm open-port --resource-group my-resource-group --name killbill --port 80 --priority 910

ssh azureuser@<vm-public-ip>

First boot creates your databases, generates this VM's secrets and starts both applications before anything is served. Allow about three minutes after the VM is created. Kaui is a JRuby application and takes the longest to warm up. When the four services report active, the stack is ready:

systemctl is-active mysql killbill kaui nginx

active active active active

Each application runs on the Java runtime its own upstream supports, and Kill Bill answers its own health check:

curl -s -o /dev/null -w 'Kill Bill health: HTTP %{http_code}\n' http://127.0.0.1:8080/1.0/healthcheck

Kill Bill health: HTTP 200

Only SSH and the two web ports are reachable from outside your VM. Kill Bill, Kaui and MySQL are all bound to the loopback address:

ss -H -lnt | awk '{print $4}' | sort -u

*:1099 *:36003 0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:3306 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::]:80 [::ffff:127.0.0.1]:8080 [::ffff:127.0.0.1]:9090

Three entries deserve an explanation. [::ffff:127.0.0.1]:8080 and :9090 are the IPv4-mapped form of 127.0.0.1, which means Kill Bill and Kaui listen on loopback only.

*:1099 and the second high-numbered port beside it belong to an RMI registry that the Kill Bill plugin framework starts for its own use. The port is 36003 here, but the kernel picks a different one on every boot, so expect another number on your VM. Kill Bill only ever contacts the registry on 127.0.0.1, but the Java call that creates it accepts no bind address, so it binds every interface.

For this reason the image ships a default-deny firewall, which is what actually decides the reachable surface:

nft list chain inet sac_killbill input | grep -E 'policy|tcp dport'

type filter hook input priority filter; policy drop; tcp dport { 22, 80, 443 } accept

Port 80 serves only a health probe and a permanent redirect to HTTPS:

curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://127.0.0.1/

301 -> https://127.0.0.1/

Every secret this image uses is generated on the first boot of your own VM and written to a file only root can read. Nothing is shared with any other VM, and none of the credentials published in Kill Bill's own documentation works here.

ls -l /root/killbill-credentials.txt

-rw------- 1 root root 977 /root/killbill-credentials.txt

sudo sed -E 's/=(.+)/=<generated-on-your-vm>/' /root/killbill-credentials.txt

# Kill Bill on Ubuntu 24.04 by sac - generated on first boot, unique to THIS VM.
# Keep this file safe. Change the administrator password after your first sign in. KILLBILL_URL=<generated-on-your-vm> KILLBILL_API_URL=<generated-on-your-vm> KILLBILL_ADMIN_USER=<generated-on-your-vm> KILLBILL_ADMIN_PASSWORD=<generated-on-your-vm> KILLBILL_TENANT_API_KEY=<generated-on-your-vm> KILLBILL_TENANT_API_SECRET=<generated-on-your-vm> KILLBILL_DB_USER=<generated-on-your-vm> KILLBILL_DB_PASSWORD=<generated-on-your-vm> KAUI_DB_USER=<generated-on-your-vm> KAUI_DB_PASSWORD=<generated-on-your-vm>

To read the real values on your own VM, print the file:

sudo cat /root/killbill-credentials.txt

The image ships a self-test that proves the appliance is working and that every credential published in the Kill Bill documentation is refused on your VM. These include the built-in admin/password administrator, the bob/lazar tenant from the tutorials, blank and weak passwords, and the root/root database login:

sudo /usr/local/sbin/killbill-selftest.sh /root/killbill-credentials.txt | tail -26

The last line is KILLBILL_SELFTEST_OK when every check passed.

Open the KILLBILL_URL value from the credentials file in a browser. It is https://<vm-public-ip>/. Sign in as admin with KILLBILL_ADMIN_PASSWORD.

Your browser warns about the certificate because the image generates a self-signed certificate for your VM's address at first boot. Step 12 explains how to install your own.

Kill Bill is multi-tenant, and first boot has already created a tenant for you with the API key and secret in your credentials file. Kaui stores tenant API secrets itself, encrypted at rest, so it asks you to register that tenant the first time you sign in. This is the normal Kill Bill onboarding, not an error.

On the Add tenant page, enter any name you like (for example production). Paste KILLBILL_TENANT_API_KEY into API key and KILLBILL_TENANT_API_SECRET into API secret, then save.

Kill Bill bills against a catalog: the products, plans and prices you sell. Until you upload one, there is nothing to subscribe an account to. The commands below use the REST API with the credentials from Step 6. Export the credentials first so that they never appear in your shell history:

read -rs KBPW && export KBPW read -rs KBKEY && export KBKEY read -rs KBSEC && export KBSEC

Upload a minimal catalog with one GBP 29/month plan. The catalog endpoint requires the text/xml content type:

curl -sS -X POST \
  -u "admin:$KBPW" \
  -H "X-Killbill-ApiKey: $KBKEY" -H "X-Killbill-ApiSecret: $KBSEC" \
  -H 'X-Killbill-CreatedBy: setup' -H 'Content-Type: text/xml' \
  --data-binary @catalog.xml \
  https://<vm-public-ip>/1.0/kb/catalog/xml

Create an account:

curl -sS -X POST \
  -u "admin:$KBPW" \
  -H "X-Killbill-ApiKey: $KBKEY" -H "X-Killbill-ApiSecret: $KBSEC" \
  -H 'X-Killbill-CreatedBy: setup' -H 'Content-Type: application/json' \
  -d '{"name":"Northwind Trading Ltd","email":"billing@northwind.example","currency":"GBP","externalKey":"northwind"}' \
  https://<vm-public-ip>/1.0/kb/accounts

Then subscribe it to a plan, using the accountId the previous call returned in its Location header:

curl -sS -X POST \
  -u "admin:$KBPW" \
  -H "X-Killbill-ApiKey: $KBKEY" -H "X-Killbill-ApiSecret: $KBSEC" \
  -H 'X-Killbill-CreatedBy: setup' -H 'Content-Type: application/json' \
  -d '{"accountId":"<account-id>","planName":"standard-monthly"}' \
  'https://<vm-public-ip>/1.0/kb/subscriptions?callCompletion=true&callTimeoutSec=40'

Accounts you create appear immediately in Kaui:

Opening an account shows what billing has produced: the balance, the bill cycle day and the date of the next invoice.

The Subscriptions tab shows the recurring plan itself, with the date it is charged up to.

Kaui is built on the REST API at https://<vm-public-ip>/1.0/kb/, so everything Kaui does is available there. Requests use HTTP basic authentication with the administrator credentials, plus the two tenant headers:

curl -sS -u "admin:$KBPW" \
  -H "X-Killbill-ApiKey: $KBKEY" -H "X-Killbill-ApiSecret: $KBSEC" \
  'https://<vm-public-ip>/1.0/kb/accounts/pagination'

Any call that changes data also requires X-Killbill-CreatedBy, which Kill Bill records in its audit log.

Two groups of endpoints are deliberately refused at the front door on this image. /1.0/kb/test is Kill Bill's integration-test clock, which can move time forward and cause invoices to be generated; it is disabled in the application and blocked by nginx. /1.0/kb/admin contains cache-flush and queue endpoints which, in this release, check only that you are authenticated and not what permissions you hold. Both are reachable from a shell on the VM via http://127.0.0.1:8080 if you genuinely need them.

curl -sk -o /dev/null -w '/1.0/kb/test/clock -> %{http_code}\n' https://127.0.0.1/1.0/kb/test/clock

/1.0/kb/test/clock -> 404

Point a DNS record at your VM's public IP address, then replace the self-signed certificate. To do this with certbot, run:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d billing.example.com

Certbot rewrites the nginx server block and reloads it. To install a certificate you already hold instead, replace /etc/ssl/killbill/killbill.crt and /etc/ssl/killbill/killbill.key (keep the key 0600 root:root) and reload nginx.

Everything transactional lives in the two MySQL schemas. Back both up together. The Kaui schema holds your tenant registrations, and a killbill backup without it means re-registering tenants by hand:

sudo mysqldump --single-transaction --routines --databases killbill kaui \
  | gzip > killbill-backup-$(date +%F).sql.gz

Also copy /root/killbill-credentials.txt somewhere safe: it holds the tenant API secret, which Kill Bill stores only as a hash and cannot show you again.

To restore onto a fresh VM, stop the applications, load the dump, and start them again:

sudo systemctl stop kaui killbill gunzip < killbill-backup-2026-09-20.sql.gz | sudo mysql
sudo systemctl start killbill kaui

The image is built entirely from Ubuntu's main archive and unattended-upgrades is enabled, so operating system security updates install themselves. To apply everything pending immediately:

sudo apt-get update && sudo apt-get -y upgrade

Kill Bill, Kaui and Tomcat are installed from upstream release artifacts rather than Ubuntu packages, so they are upgraded by replacing the deployed application. Check the running versions before and after any upgrade, and always take a database backup first, because Kill Bill applies schema migrations on start-up.