This is an AWS Marketplace only feature.

Overview

This document describes the procedures for setting up Kill Bill under AWS using the CloudFormation option. This is one of two recommended alternatives for production use. The multi-tier option requires more setup than CloudFormation, but provides more control over the deployment. The procedures in this document are based on the options recommended by Kill Bill.

Deployment via CloudFormation leverages the capabilities of the AWS infrastructure to provide a robust production ready deployment with a single click. The entire CloudFormation configuration, or stack, is defined by a CloudFormation Template.

The features of the CloudFormation system include:

  • The instance with Kill Bill and Kaui installed can be scaled up or down using an AWS Auto Scaling Group.

  • AWS CloudWatch provides metrics to follow what is happening.

  • The RDS database based on AWS Aurora comes automatically configured and ready for use.

Running Kill Bill on AWS using our CloudFormation Template is the easiest and fastest way to get started with a production cluster. It is also the only method of installation that is certified by the core developers for a highly available, horizontally scalable and production-ready installation.

With the click of a button, the template will install and configure:

  • Kill Bill and Kaui on a custom AMI optimized for AWS workloads (integrated with CloudWatch, SQS, SES, X-Ray and more)

  • Auto Scaling Groups, to automatically scale up and down the number of EC2 instances as needed (such as when batches of invoices are generated)

  • A load balancer, integrated with our internal healthchecks to promptly take unhealthy instances out of rotation

  • An RDS Aurora Cluster with automatic failover

The following diagram shows the various AWS entities that will be created by CloudFormation:

cf stack

All resources for this system run within a single AWS Virtual Private Cloud (VPC), providing a dedicated block of IP addresses which must be located in a single region. The cloud is partitioned into availability zones, which are accessed by subnets. The resources must be distributed over at least two availability zones.

A single EC2 instance hosts both Kill Bill and Kaui servers in the VPC, running on an Ubuntu Linux server. AWS autoscaling is utilized to dynamically adjust the number of instances for each package based on demand, allowing for efficient scaling.

Access to these instances is managed by an AWS Elastic Load Balancer (ELB). The ELB routes each request to the correct package and distributes the requests across the available instances. The ELB accepts traffic securely using HTTPS by default.

The back end of the system is an Aurora database manager provided through the AWS Relational Database System (RDS). Aurora is a robust database system developed by AWS, compatible with MySQL and Postgres. There are separate databases maintained for Kill Bill and Kaui.

In addition, the complete CloudFormation system makes use of AWS scalable and reliable S3 storage technology.

The procedures described here are based on the Kill Bill CloudFormation Template version 2022.10 or later. This system provides the framework for incorporating a variety of analytic tools, including Datadog, New Relic, Rollbar, Sentry, and AWS CloudWatch. In this How-To we will enable CloudWatch, which is easily integrated with our CloudFormation installation. We will not make use of the other analytic tools.

The setup procedure includes seven steps:

  1. Login to AWS

  2. Setup the VPC and Subnets

  3. Create a Certificate

  4. Create a Key Pair

  5. Configure and Launch

  6. Setup a CNAME

  7. Test your Stack

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. All resources you create will be placed in this region, and may not be accessible from other regions.

In addition, AWS places all resources within a Virtual Private Cloud (VPC). A default VPC will be created and used automatically in the following steps. However, if you have access to other VPCs, you will need to ensure that all Kill Bill resources are deployed in the same one.

Step 2: Setup the VPC and Subnets

All resources for your CloudFormation deployment must be placed within a single VPC. To prepare for CloudFormation deployment you will first need to setup and identify your VPC and subnets.

1. Setup your VPC

From the Services menu item at the top of the main AWS page, under Networking and Content Delivery, select VPC. This will open the VPC Dashboard. Then select Your VPCs from the left menu.

Normally you will see one VPC, which AWS provides by default. This VPC will automatically be used for all your resources. If you have more than one, you need to select the one you want to use and be sure to set its ID as a parameter for your CloudFormation configuration. If there is no VPC listed, you must create one. The only parameter you need to set is the ipv4 CIDR block, which designates a range of (private) IP addresses. A suggested value is 192.168.0.0/16.

2. Setup your Subnets

From the left menu of the VPC Dashboard select Subnets. This shows a list of your subnets. By default AWS creates one subnet for each Availability Zone in your region. You may create your own subnets, as long as you give each a CIDR block representing a unique subset of your VPC, and assign each to a specific availability zone. If you don’t know what this means, just accept the defaults.

Step3: Create a Certificate

The CloudFormation implementation uses the HTTPS protocol for strong security. This requires the use of an X.509 certificate.

If you do not have a certificate, select Security, Identity, and Compliance, then Certificate Manager from the Services menu. Then follow the instructions in How to Add a Certificate Using ACM.

If you have a certificate created by ACM, you are all set. If you have a certificate not created by ACM, set the bottom left dropdown to Import and follow the instructions. Import the certificate to ACM.

Now select your certificate from the ACM list and copy its AWS Resource Name (ARN). Save this value as it will be needed in a later step.

Step 4: Create a Key Pair

The Kill Bill CloudFormation stack requires a key pair. The key pair provides the credentials you will need to login to your EC2 instances. If you already have a key pair, you are all set. Otherwise you will need to create one.

To create a key pair, from the EC2 console scroll down to Networks & Security / Key Pairs. Select Create Key Pair and follow the instructions. Give the key pair a simple, easy to remember name such as My-Key-Pair.For details about key pairs, see the AWS documentation. 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 instances.

Step 5: Configure and Launch

The setup process starts with the Kill Bill CloudFormation Template at AWS Marketplace. Go to this page, then click Continue to Subscribe.

cf subscribe

THe next page gives the AWS Terms and Conditions. You must accept these conditions if asked, then click Continue to Configuration. This will take you to the page titled Configure This Software: