anchor.diff: -= Installation via Single AMI
  -
  -== Overview
  -
  -Single AMI deployments are a way to deploy the Kill Bill stack, that is both the Kill Bill server and the administrative UI (KAUI), from one AMI. We offer two options. The `Single-Tier` option uses only a single EC2 instance. This is suitable for testing and experiments. The `Multi-Tier` option uses two or more EC2 instances, and is designed for production deployments. Both of these deployment options rely on the same underlying AMI, but for the `Multi-Tier` option there is a list of prerequisites, such as an external database, along with a startup script to be provided when launching the instance.
  -
  -
  -== Single-Tier Deployments
  -
  -The single-tier deployment option is designed to get you started as quickly as possible. Everything you need: Kill Bill, KAUI, and the MariaDB (MySQL) database, is bundled in the AMI and can be launched on a single EC2 instance with just one click. This makes it very suitable for test environments, but we don't recommend it for production deployments.
  -
  -The AMI also comes with a running instance of the load balancer `nginx` that acts as a reverse proxy and spreads the incoming traffic to either Kill Bill or KAUI based on the incoming port. The EC2 instance will be an instance of Ubuntu Linux. The organization of the single-tier system looks like this:
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-tier-ami_deployment.png[align=center]
  -
  -In this model, the Kill Bill server 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` database.  
  -
  -=== Getting Started
  -
  -
  -To start the installation process, point your browser to +++<a href="https://aws.amazon.com/marketplace/pp/B083LYVG9H?ref=_ptnr_doc_" onclick="getOutboundLink('https://aws.amazon.com/marketplace/pp/B083LYVG9H?ref=_ptnr_doc_'); return false;">AWS Marketplace</a>+++: 
  -
  -If you are new to AWS, you will be asked to create an account and provide billing information. Once your account is validated,
  -you should see the following image at the top of your screen:
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-subscribe.png[align=center]
  -
  -Click *Continue to Subscribe*. The next page will give the AWS Terms and Conditions:
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-terms-ask.png[align=center]
  -
  -Accept the terms if asked. You will then see a new message confirming that you have subscribed. Next, click **Continue to Configuration**.
  -
  -The next page will give several configuration options. 
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-configure.png[align=center]
  -
  -In most cases you should accept the defaults. Then click **Continue to Launch**.
  -
  -The next page will give you several options for the launch method. We recommend that you choose **Launch through EC2**.
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-launch.png[align=center]
  -
  -All other options will disappear. Click **Launch**.
  -
  -The next page is titled **Choose Instance Type**. Your instance type is already chosen, so click **Review and Launch** at the bottom of the page.
  -
  -The following page is headed **Review Instance Launch**. This provides a chance to review the details of your chosen instance. Then click **Launch** at the bottom of the page.
  -
  -Next you will see a very important popup that asks you to choose or create a **key pair**.
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-keypair.png[align=center]
  -
  -The key pair provides the credentials you will need to login to your EC2 instance. For details about key pairs, see the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS documentation]. We recommend that you create a new key pair. Give the key pair a simple, easy to remember name such as `My-Key-Pair`. 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.
  -
  -When the key pair is generated, click **Launch Instances**. You should see the screen below:
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-launching.png[align=center]
  -
  -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 Instance** at the bottom right. This will take you to the `Instances` screen which is part of the EC2 Dashboard.
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-instances.png[align=center]
  -
  -
  -In a short time, the **Instance State** for your instance should indicate `Running`. You will need to scroll to the right to see all of the information available about your instance.
  -
  -You are almost set, but there is one more thing you should do, and that is to scroll down in the menu on the left side to select **Security Groups**. You should see a list of two or more groups. Select the group whose name begins with `Kill Bill on AWS`, then scroll to the bottom and select the tab for `Inbound Rules`. You should see:
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-inbound.png[align=center]
  -
  -These rules enable the ports that must be open to access KAUI and Kill Bill from a browser. To enable direct login to your instance using SSH, you need to add one more port. Click on **Edit Inbound Rules**. Then add a rule with the following elements: Type: SSH, Protocol: TCP, Port Range: 22, Source: 0.0.0.0/0. Your Inbound Rules should now look like this:  
  -
  -image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/single-ami-inbound-new.png[align=center]
  -
  -=== Initial Testing
  -
  -You can now login to KAUI from your browser using the URL https://INSTANCE_IP:443, where INSTANCE_IP is the IPV4 address for your instance, given on your dashboard as **Public IPV4 Address**. This should display the KAUI login screen. The default credentials are: *admin/password*. The first few requests might be a bit slow as Kill Bill initializes itself.
  -
  -For an introduction to KAUI, see our http://docs.killbill.io/latest/getting_started.html#_using_kill_bill_with_kaui[Getting Started] guide.
  -
  -You can also login in directly to your instance from a terminal or command window. You may have no need to do this for a while, but you should try it and make sure it works. You may need to do this for system monitoring or troubleshooting later.
  -
  -To login, use the secure shell command:
  -
  -`ssh -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP`
  -
  -Here PRIVATE_KEY is the pathname where you have stored the private key that was downloaded when you generated your key pair, and INSTANCE_IP is the IPV4 address described earlier. The private key will not work unless its access controls are set to readable by the owner only.
  -
  -On Windows versions before Windows 10, you may need to download a program called PuTTY to enable `ssh`. On Windows 10 `ssh` is available but may need to be activated through the Settings screen.
  -
  -The first time you login, you will see a warning message asking if you want to add this host to your list of hosts. You should answer `yes`.
  -
  -For more information about the organization of your instance, see the Configuration and Troubleshooting sections below. To exit from your login, type `exit`.
  -
  -
  -== Multi-Tier Deployments
  -
  -=== Overview
  -
  -For production deployments, we recommend a *multi-tier* configuration with two or more EC2 instances and a separate database instance using the `Amazon Relational Database Service (RDS)`. In place of `nginx`, this configuration relies on an AWS `Elastic Load Balancer (ELB)` to correctly spread the traffic among the various nodes, and also to route traffic to either  Kill Server or KAUI based on the incoming port. This deployment option requires a bit more setup, so we also provide an (easier) way to deploy using https://docs.killbill.io/latest//aws-cf.html[CloudFormation templates]. However, the multi-tier option provides more control over the deployment.
  -
  -The diagram below illustrates the multitier configuration. This section will explain how to setup this option.
  += Installation: Multi-Tier Option
  +
  +Single AMI deployments are a way to deploy the Kill Bill stack, that is both the Kill Bill server and the administrative UI (KAUI), from one AMI. There are two options: *single-tier* and *multi-tier*. The https://docs.killbill.io/latest//aws-singletier.html[*single-tier* option] is a good way to deploy a limited version of Kill Bill quickly for trial and experimentation. For production deployments, we recommend the *multi-tier* configuration, using two or more EC2 instances and a separate database provided by the AWS *Relational Database Service (RDS)*. This configuration also makes use of an AWS *Elastic Load Balancer (ELB)* to correctly spread the traffic among the various nodes, and to route traffic to either the Kill Bill Server or KAUI based on the incoming port.
  +
  +As a third option, we also provide an easier way to deploy a production system using https://docs.killbill.io/latest//aws-cf.html[CloudFormation templates]. The multi-tier option requires more setup, but provides more control over the deployment.
  +
  +This document describes the installation process for the multi-tier option. The diagram below shows the principal components of the multi-tier system: The ELB, the RDS, and two or more EC2 instances. Each EC2 is an instance of Ubuntu Linux, running both Kill Bill and KAUI within a Tomcat server. Clients interact only with the ELB, which routes requests to the rest of the system.
   
   image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multi-tier-ami_deployment.png[align=center]
   
  +== Multi-Tier Installation
  +
   === 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.
  
positive.code: 
  image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multitier-database-types.png[align=center]
  
  The next choice determines the instance size. We suggest the `Production` option as this will provide the most robust configuration.
  
  image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multitier-instance-sizes.png[align=center]
  
  
negative.code: 
  image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multitier-names-and-password.png[align=center]
  
  When the password is setup and confirmed, click *Create Database* in the lower right corner. You will return to the main Databases screen, which should now look like this:
  
  image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multitier-database-starting.png[align=center]
  
  This display shows that your database is starting. After a few minutes, the status will change to *Available* (You may need to reload the page to see this). At this time you can click on the database name to get more information, including the full name of the instance.
  
  On the page that appears you should see a panel named *Connectivity and Security*. The left side of this panel shows the full name of the endpoint, which you will need shortly, and the port number, which is normally 3306.
  
  image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/aws/multitier-connectivity-and-security.png[align=center]
  
  Lastly, on the *Connectivity and Security* panel, locate and click on the link for the default VPC security group. You will need to add an inbound security rule, because the database by default does not allow external access. In the panel for this group, click on *Inbound Rules* and select *Edit Inbound Rules*. Next click on *Add rule*. In the *Type* column select `MYSQL/Aurora`. The port will be set to 3306 automatically. In the *Source* column, click on the search icon and select `0.0.0.0/0`. Finally, click on *Save Rules* in the bottom right. Your database is ready to go.
  
  === Edit the Configuration Script
  
  