Introduction
This document describes the procedures for setting up Kill Bill under AWS using the single-tier option. This option has limited capabilities but is very easy to setup. It uses a minimum of resources and may be suitable for very simple use cases. Everything you need for this option is bundled in the Kill Bill Amazon Machine Image (AMI) and will be launched on a single virtual Linux system, which AWS calls an EC2 instance.
The components of this system include Kill Bill, Kaui, a database manager (DBM), and a load balancer, all running on this single EC2 instance. The instance runs Ubuntu Linux. The DBM is an instance of MariaDB, an open source version of MySQL. The load balancer is the open source package Nginx. This package serves as a front end or reverse proxy, distributing the incoming traffic to either Kill Bill or Kaui based on the incoming port.
The organization of the single-tier system looks like this:
In this configuration, Kill Bill and Kaui are deployed within the tomcat application server. Requests are handled by nginx. Requests received on port 443 are delivered to Kaui, and those received on port 8443 are delivered to Kill Bill. Both Kill Bill and Kaui communicate as needed with the mysql databases.
The setup procedure includes the following steps:
Once your instance is up and running, see Optional Post-Deployment Tasks below for logging in via SSH and replacing the default self-signed certificate.
Step 1: Login to AWS
To begin, log in to Amazon Web Services at https://aws.amazon.com. If you are new to AWS, you will be asked to create an account and provide billing information. You will need to sign in as a Root User. This should take you to the AWS Management Console, which provides links to all available services.
Check the upper right corner of your screen to be sure you are in the appropriate region. Your EC2 instance will be placed in this region, and may not be accessible from other regions.
Step 2: Subscribe to the Kill Bill AMI
To start the installation process, point your browser to the Kill Bill AMI at AWS Marketplace .
You should see the following image at the top of your screen:
Click Continue to Subscribe. The next page will give the AWS Terms and Conditions. Accept the terms if asked. You will then see a new message confirming that you have subscribed. Next, click Continue to Configuration, and select Launch through EC2 as the launch method.
You should then see the following page, which lets you pick the software version and region and start the launch:
Accept the defaults (the version dropdown always points at the latest stable release), confirm the Region matches the one you selected in Step 1, and click Launch from EC2.
Step 3: Launch the Instance
This takes you to the Launch an Instance page in the EC2 console. This page is organized into several sections that you will fill in one at a time. The first three sections normally need no changes:
Name and tags — Optionally give your instance a name, such as kill-bill-single-tier. This is only a label for your own reference in the EC2 dashboard and has no effect on the installation.
Application and OS Images (Amazon Machine Image) — Because you arrived here from the AWS Marketplace subscription, the Kill Bill AMI is already selected for you. There is nothing to change here; just confirm it shows the Kill Bill AMI as a Verified provider.
Instance type — Defaults to t2.medium, which is the minimum instance type recommended for Kill Bill. You can select a larger instance type if you expect heavier load, but t2.medium is fine to get started.
Step 4: Create a Key Pair
Scroll down to the Key Pair (login) section. Here you are asked to choose or create a key pair.
We will create a new key pair. Click Create new key pair to display a pane to be used for the creation. Give the key pair a simple, easy to remember name such as My-Key-Pair. Do not change the other options on this pane. Then click Download Key Pair. Important: You must save the private key that will be generated in this step. If you lose this key, you will not be able to login to your instance. In addition, you must set the protection for this file so it is readable by the owner only.
Step 5: Configure Network Settings
Scroll down to the Network settings section:
5.1. VPC and subnet
Select the VPC where you want to deploy the EC2 instance. Every AWS account starts with a default VPC, and that default VPC already ships with a public subnet in every availability zone, so in most cases there is nothing to create here.
A subnet is public when the route table associated with it has a route for destination 0.0.0.0/0 pointing to an Internet Gateway (target igw-xxxxxxxx) attached to the VPC, rather than to a NAT Gateway or no route at all. If you are using a custom VPC instead of the default one, use the Subnet dropdown to check the details shown for each subnet (availability zone, CIDR), or click Create new subnet if you need one. Then, in the VPC console, confirm its route table has a 0.0.0.0/0 → igw-xxxxxxxx route before continuing.
5.2. Auto-assign public IP
This defaults to Disable — you must change it to Enable. Without a public IP, you will not be able to reach the instance from the internet in Step 8, nor log in to it over SSH afterward.
5.3. Firewall (security group)
Leave Create security group selected. AWS pre-fills two inbound rules for you, for ports 443 and 8443. These are the correct ports for this AMI: 443 is handled by nginx and forwarded to Kaui, and 8443 is handled by nginx and forwarded to the Kill Bill server. Confirm both rules have Source set to Anywhere (0.0.0.0/0).
While you are here, you can also click Add security group rule to add SSH access. This is optional — it is only needed if you plan to log in to your instance directly (see Optional Post-Deployment Tasks below):
-
Type SSH, Protocol
TCP, Port range22, SourceAnywhere (0.0.0.0/0).
Your security group should now have two required inbound rules, 443 and 8443, open to 0.0.0.0/0, plus the optional 22 rule if you added it.
Step 6: Configure Storage
Scroll down to the Configure storage section:
The default of a single 8 GiB gp3 root volume is sufficient to get started, and no additional file systems (S3, EFS, FSx) are required. Leave None selected and leave the rest of this section at its defaults.
Step 7: Launch Your Instance
Review the summary panel on the right, then click Launch Instance. You should see the screen below:
Your instance is finally launching! To follow what is happening on the EC2 Dashboard, scroll all the way down to the bottom, and click View all instances at the bottom right. This will take you to the Instances screen which is part of the EC2 Dashboard.
In a short time, the Instance State for your instance should indicate Running. Select the checkbox to the left of your instance ID. An information pane should open below with details about your instance.
Step 8: Test your Installation
Congratulations! Your single-tier installation is ready to go!
You can now try to login to Kaui from your browser using the URL https://INSTANCE_IP:443 (or simply https://INSTANCE_IP), where INSTANCE_IP is the IPV4 address for your instance, given on your dashboard as Public IPV4 Address. If all goes well, this should display the Kaui login screen.
The AMI ships with a self-signed certificate, so your browser will warn you that the connection is not secure or private (for example, Chrome shows "Your connection is not private"). This is expected at this stage — it just means the certificate was not issued by a CA your browser trusts yet. You can proceed past the warning (e.g., in Chrome, click Advanced, then Proceed) to reach the login screen. See Optional Post-Deployment Tasks below for how to replace it with a certificate from a trusted CA.
For an introduction to Kaui, see our Kaui Guide. The default credentials are: admin / INSTANCE_ID, where INSTANCE_ID is the Instance ID for your EC2 instance (not the IP!). The first few requests might be a bit slow as Kill Bill initializes itself.
In addition, you can visit the Kill Bill server using the URL https://INSTANCE_IP:8443. This provides access to certain detailed reports that may be needed for maintenance, including metrics, event logs, and the Swagger API pages. The same certificate warning applies here.
If these logins do not work correctly, review your setup steps carefully, then proceed to the Single-Tier Maintenance Guide.
Optional Post-Deployment Tasks
The tasks below are not required to run Kill Bill, but you may want to perform them once your instance is up and running.
Login to Your Instance via SSH
You may want to log in to your instance directly, for example to perform configuration or maintenance tasks. This requires the optional SSH rule from Step 5, and is described in a separate document since it is common to all of our AWS deployments: see How to Log In to Your EC2 Instance via SSH.
Add a Trusted Certificate
The self-signed certificate that ships with the AMI is enough to get started, but browsers will always flag it as untrusted. To remove this warning, replace it with a valid X.509 SSL/TLS certificate from a trusted CA. The easiest way to do this is with the tool certbot, which relies on the free Certificate Authority (CA) Let’s Encrypt. This method provides a simple way to obtain and install free certificates. For instructions on installing and using certbot, see the Certbot documentation. Once your certificate is setup, you can login securely to Kaui using your CNAME as the URL (e.g., https://kaui.mydomain.com).