Improve AWS single-tier documentation#689
Merged
Merged
Conversation
Reorganize how-to-set-up-a-single-tier-system.adoc to mirror the actual EC2 launch wizard flow, and fix several discrepancies between the doc and the real deployment: - Remove the architecture diagram and nginx/443/8443 references, which no longer match the deployment (Kaui listens directly on 3000, Kill Bill on 8000, no reverse proxy). - Drop the hardcoded AMI version requirement, which goes stale as new versions ship. - Explain what a public subnet is (route table with a 0.0.0.0/0 route to an Internet Gateway) and how to create one. - Fix the security group instructions: correct ports are 3000/8000, not 443/8443, and the SSH/22 rule is now added during network settings instead of as a separate post-launch step. - Add a Storage step and explicit Name/tags, AMI, and Instance type guidance, matching the sections actually shown in the EC2 console. - Update screenshots to match the current AWS Marketplace/EC2 UI. Also remove tutorial-single-tier.adoc, an orphaned draft that duplicated this guide with the same stale content and wasn't linked from anywhere. Fixes killbill/technical-support#285
Deploying docs-killbill-io with
|
| Latest commit: |
f70b0eb
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://e073c029.docs-killbill-io.pages.dev |
| Branch Preview URL: | https://improve-single-tier-aws-doc.docs-killbill-io.pages.dev |
The single-tier AMI does run nginx as a reverse proxy in front of Kaui and Kill Bill (ports 443/8443), not direct 3000/8000 access as previously documented. Re-add the architecture diagram and fix the security group and test-installation sections to reference the correct ports.
- Move the SSH login instructions out of the single-tier setup steps into a new standalone doc (how-to-login-to-your-ec2-instance.adoc), since logging in is not required to run Kill Bill and the same instructions apply across single-tier, multi-tier, and CloudFormation deployments. - Demote certificate setup from a required numbered step to an optional post-deployment task, and fix the dead certbot doc link to point to certbot's own site. - Explain in the test-installation step that browsers (e.g. Chrome) will show a not-secure warning against the AMI's default self-signed cert, and that this is expected until a trusted CA certificate is installed. - Update how-to-maintain-a-single-tier-system.adoc's stale cross-reference to point to the new SSH doc.
vnandwana
approved these changes
Jul 19, 2026
| * Select the VPC where you want to deploy the EC2 instance. | ||
| * Choose a *public subnet* within that VPC. | ||
| * Ensure *Auto-assign public IP* is *enabled*. | ||
| image::../assets/aws/single-ami-network-settings.png[align=center] |
Contributor
There was a problem hiding this comment.
We can break this screenshot into two parts (VPC and Subnet, and security group).
Also, the screenshot should have "Auto-assign public IP" enabled.
| image::../assets/aws/single-ami-instances.png[align=center] | ||
| === 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 incorrect for this AMI* and must be changed to match the ports Kaui and Kill Bill actually listen on: |
Contributor
There was a problem hiding this comment.
These ports are correct.
| 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. | ||
|
|
||
| [[step8]] | ||
| == Step 8: Login to Your Instance |
Contributor
There was a problem hiding this comment.
After EC2 launch, we don't need to SSH to an instance. We can move step 9 here and add this step as optional (needed for troubleshooting or updating config files).
| 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. The EC2 instance runs Ubuntu Linux. The DBM is an instance of https://mariadb.org[MariaDB], an open source version of MySQL. The load balancer is the open source package https://www.nginx.com[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. | ||
| Kill Bill, Kaui, and the database all run on this single EC2 instance. The instance runs Ubuntu Linux, and the database is an instance of https://mariadb.org[MariaDB], an open source version of MySQL. Kaui, the administrative user interface, listens on port `3000`, and the Kill Bill server listens on port `8000`. |
Contributor
There was a problem hiding this comment.
We should use the SSL ports 443 for Kaui, and 8443 for KB.
| 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. The EC2 instance runs Ubuntu Linux. The DBM is an instance of https://mariadb.org[MariaDB], an open source version of MySQL. The load balancer is the open source package https://www.nginx.com[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. | ||
| Kill Bill, Kaui, and the database all run on this single EC2 instance. The instance runs Ubuntu Linux, and the database is an instance of https://mariadb.org[MariaDB], an open source version of MySQL. Kaui, the administrative user interface, listens on port `3000`, and the Kill Bill server listens on port `8000`. |
Contributor
There was a problem hiding this comment.
AMIs are configured to install MySQL 8.4 LTS
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
how-to-set-up-a-single-tier-system.adocto mirror the actual EC2 launch-wizard flow (Name/tags, AMI, instance type, key pair, network settings, storage, launch) instead of the older, out-of-sync step sequence.443/8443references, which no longer match the deployment — Kaui now listens directly on3000and Kill Bill on8000, with no reverse proxy.0.0.0.0/0route to an Internet Gateway) and how to create/verify one, since every default VPC ships with one already.443/8443, which must be corrected to3000/8000; the SSH/22rule is now added inline during network settings instead of as a separate post-launch step.tutorial-single-tier.adoc, an orphaned draft (not linked fromindex.adocor any nav, superseded by this guide back in 2023) that duplicated the same stale content.Fixes killbill/technical-support#285
Test plan
bundle exec asciidoctorbuild of the changed file completes with zero warnings/errors (--failure-level WARN)image::references resolve to existing files underuserguide/assets/aws/🤖 Generated with Claude Code