diff --git a/userguide/tutorials/aws-container.adoc b/userguide/aws/aws-container.adoc similarity index 100% rename from userguide/tutorials/aws-container.adoc rename to userguide/aws/aws-container.adoc diff --git a/userguide/tutorials/aws-tools.adoc b/userguide/aws/aws-tools.adoc similarity index 95% rename from userguide/tutorials/aws-tools.adoc rename to userguide/aws/aws-tools.adoc index f93677f68..bd391e286 100644 --- a/userguide/tutorials/aws-tools.adoc +++ b/userguide/aws/aws-tools.adoc @@ -10,8 +10,8 @@ Several of these tools have been integrated with the AWS implementations of Kill To proceed, you should have a working Kill Bill implementation running on AWS, using either the -https://docs.killbill.io/latest/aws-singletier.html[single-tier] or -https://docs.killbill.io/latest/aws-multitier.html[multi-tier] +https://docs.killbill.io/latest/how-to-set-up-a-single-tier-system.html[single-tier] or +https://docs.killbill.io/latest/how-to-set-up-a-multi-tier-system.html[multi-tier] installation options. The single-tier option runs Kill Bill, Kaui, the MariaDB database, and the nginx load balancer on a single AWS EC2 instance. This is suitable for quick deployment and for testing and diff --git a/userguide/tutorials/aws.adoc b/userguide/aws/aws.adoc similarity index 100% rename from userguide/tutorials/aws.adoc rename to userguide/aws/aws.adoc diff --git a/userguide/tutorials/errors-rollbar.adoc b/userguide/aws/errors-rollbar.adoc similarity index 100% rename from userguide/tutorials/errors-rollbar.adoc rename to userguide/aws/errors-rollbar.adoc diff --git a/userguide/tutorials/errors-sentry.adoc b/userguide/aws/errors-sentry.adoc similarity index 100% rename from userguide/tutorials/errors-sentry.adoc rename to userguide/aws/errors-sentry.adoc diff --git a/userguide/tutorials/events-to-aws-sqs.adoc b/userguide/aws/events-to-aws-sqs.adoc similarity index 100% rename from userguide/tutorials/events-to-aws-sqs.adoc rename to userguide/aws/events-to-aws-sqs.adoc diff --git a/userguide/aws/how-to-maintain-a-cloud-formation-system.adoc b/userguide/aws/how-to-maintain-a-cloud-formation-system.adoc index 8764bf7de..cfb41916e 100644 --- a/userguide/aws/how-to-maintain-a-cloud-formation-system.adoc +++ b/userguide/aws/how-to-maintain-a-cloud-formation-system.adoc @@ -111,6 +111,27 @@ If you update any configuration file, you will need to restart the service. To d > sudo service killbill restart ---- +== Update Configuration +To update the Kill Bill configuration parameters, select the CloudFormation stack and click on *Update*. The update stack consists of the following 4 steps: + +* Step 1 - Update stack: select *Use current template* and click Next + +image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step1.JPG[align=center] + +* Step 2 - Specify stack details: update any of the parameters and click Next + +image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step2.JPG[align=center] + +* Step 3 - Configure stack options: no changes are needed at this step + +image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step3.JPG[align=center] + +* Step 4 - Review: review all the changes made to the parameters, scroll down and check *I acknowledge that AWS CloudFormation might create IAM resources* and click on *Submit*. + +image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step4b.JPG[align=center] + +CloudFormation stack will start updating all these configurations, and upon completion, its status will change to *UPDATE_COMPLETE*. + == Maintenance If your installation has been running well but shows signs of slowing down or other problems, there are several commands you can use to assess its overall health. These commands can be used when you are logged in to any instance. Some should be run on all instances from time to time. diff --git a/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc b/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc index 08da66f5b..82f590072 100644 --- a/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc +++ b/userguide/aws/how-to-set-up-a-cloud-formation-system.adoc @@ -190,7 +190,7 @@ This provides access to certain detailed resources that may be needed for mainte Congratulations! Your CloudFormation installation is ready to go! -For information on troubleshooting, maintaining and upgrading your installation see https://../how-to-maintain-a-cloudformation-system.adoc[How to Maintain a CloudFormation System]. +For information on troubleshooting, maintaining and upgrading your installation see https://docs.killbill.io/latest/how-to-maintain-a-cloud-formation-system[How to Maintain a CloudFormation System]. diff --git a/userguide/tutorials/metrics-cloudwatch.adoc b/userguide/aws/metrics-cloudwatch.adoc similarity index 98% rename from userguide/tutorials/metrics-cloudwatch.adoc rename to userguide/aws/metrics-cloudwatch.adoc index cae862039..f64151e94 100644 --- a/userguide/tutorials/metrics-cloudwatch.adoc +++ b/userguide/aws/metrics-cloudwatch.adoc @@ -133,6 +133,8 @@ If you have multiple instances, repeat these steps for each one. You may use the To test your installation, Go to the Cloudwatch console. After a short delay, you should see a set of available metrics. There should be well over 1,000 in your list. +image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aws/cloudwatch.png[align=center] + Congratulations. Your CloudWatch integration is complete! == Using CloudWatch diff --git a/userguide/tutorials/metrics-datadog.adoc b/userguide/aws/metrics-datadog.adoc similarity index 100% rename from userguide/tutorials/metrics-datadog.adoc rename to userguide/aws/metrics-datadog.adoc diff --git a/userguide/tutorials/metrics-newrelic.adoc b/userguide/aws/metrics-newrelic.adoc similarity index 100% rename from userguide/tutorials/metrics-newrelic.adoc rename to userguide/aws/metrics-newrelic.adoc diff --git a/userguide/tutorials/using-ses-with-aws.adoc b/userguide/aws/using-ses-with-aws.adoc similarity index 100% rename from userguide/tutorials/using-ses-with-aws.adoc rename to userguide/aws/using-ses-with-aws.adoc diff --git a/userguide/tutorials/aws-cf.adoc b/userguide/tutorials/aws-cf.adoc deleted file mode 100644 index 07fd867bc..000000000 --- a/userguide/tutorials/aws-cf.adoc +++ /dev/null @@ -1,467 +0,0 @@ -= Installation via CloudFormation - -There are at least three different ways to setup a working Kill Bill system on AWS. Two options are based on a single *Amazon Machine Image (AMI)* containing the complete Kill Bill stack, that is both the Kill Bill server and the administrative UI (KAUI). These options are *single-tier* and *multi-tier*. The https://docs.killbill.io/latest//aws-singletier.html[*single-tier* option] is designed to deploy a limited version of Kill Bill quickly for trial and experimentation. The https://docs.killbill.io/latest//aws-multitier.html[*multi-tier* option] is designed for production deployments; this requires more setup than other options, but provides the most control over the deployment. - -A third alternative available for deploying a production system, discussed here, is *CloudFormation*. This deployment method leverages the capabilites 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: - -* Both Kill Bill and KAUI instances can be scaled up or down using AWS autoscaling groups -* AWS CloudWatch provides metrics to follow what is happening -* The RDS database based on AWS Aurora comes automatically configured and ready for use - -== Overview - -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: - -image::../assets/aws/cf_stack.png[align=center] - -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. - -Multiple instances of KAUI and the Kill Bill server are deployed in the VPC, each running on its own Ubuntu Linux server. AWS autoscaling is used to increase and decrease the number of instances for each package as needed. - -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 using HTTP by default, but we recommend upgrading to HTTPS for higher security (see below). Using HTTP, the ELB will listen on port 80 for routing traffic to the Kill Bill instances, and on port 9090 for accessing KAUI. - -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. - -Finally, the complete CloudFormation system makes use of AWS scalable and reliable *S3* storage technology, and incorporates AWS *CloudWatch* for monitoring and reports. - -== 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. - -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. - - -=== 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. - -=== Setup 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. For details about key pairs, see the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[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. - - -=== Configure and Launch - -The setup process starts at the AWS Marketplace using our +++official CloudFormation template.+++ Go to this page, then click *Continue to Subscribe*. - -image::../assets/aws/cf-subscribe.png[align=center] - -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*: - -image::../assets/aws/cf-configure.png[align=center] - -There is nothing to change on this page. Click *Continue to Launch*. THe next page is titled *Launch this Software*. There is nothing to do here either. Click *Launch*. - -The next page is designated *Step 1: Specify Template* and titled *Create stack*: - -image::../assets/aws/cf-step1.png[align=center] - -Once again everything is filled in for you. Click *Next*. This brings up the *Stack Details* page (your complete configuration is called a stack): - -image::../assets/aws/cf-details.png[align=center] - -*Now* you have some work to do! This page requires that a number of configuration parameters be filled in. All of these are important, and many are critical. - -First, you need to provide a name for your stack. Any name will do, as long as it meets the stated rules. Then you will need to carefully set a series of parameters: - -* *DBClass:* the database instance type to use for RDS. This normally should not be changed. -* *DBName:* the database name for Kill Bill. This is preset to *killbill*. Do not change it. -* *DBUser:* database admin username. The username you choose for the database administrator. -* *DBPassword:* database admin password. The password you choose for the database administrator. This must include at least one letter, at least one digit, and no other character types. -* *EnableCloudWatchMetrics:* whether to enable metrics in CloudWatch. This is strongly recommended for production. -* *EnvType:* the purpose of this configuration: test, dev (development), or prod (production). There is no difference in the stack being created but this value will be sent to CloudWatch as a dimension. -* *HTTPLocation:* the IP address range allowed to access the load balancer, in the form of a CIDR block. You can use 0.0.0.0/0 initially and adjust access later on. -* *InstanceType:* the EC2 instance type to use for Kill Bill. This normally should not be changed. -* *KBAdminPassword:* the password to be used for the default `root` user which has all permissions. By default this is set to `password`. Please change it! The requirements are the same as for *DBPassword*. -* *KauiDBName:* database name for Kaui. This is preset to *Kaui*. Do not change it. -* *KauiServerCapacity:* the initial number of Kaui instances in the Auto Scaling group. We recommend using the default value, `2`. -* *KeyName:* name of an existing EC2 KeyPair to enable SSH access to the instances. If you don't have one, see the https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html[AWS documentation]. -* *KillBillServerCapacity:* the initial number of Kill Bill instances in the Auto Scaling group. Again we recommend the default value of `2`. -* *RDSSubnets:* the subnets to use for the RDS instance. Select two or more from your subnets, which must be in two or more availability zones. -* *SetEnvironmentVariables:* a comma-delimited list of environment variables to set. -* *Subnets:* the subnets to use for the KB and KAUi instances. Also two or more from your subnets in two or more availability zones. May or may not be the same as the RDS subnets. -* *VpcId:* the VPC to use for the installation, which you identified earlier. - -When all of these are set, click *Next* to go to *Configure Stack Options*. Now take a break. There is nothing to do here. Then click *Next*. - -The final page gives you a chance to review. If everything seems OK, read and check any warnings at the bottom, then click *Create Stack*. you are off! - -image::../assets/aws/cf-creating.png[align=center] - -If there are any errors, you will see a message and the Create will not begin. You will need to go back and fix the errors. Common errors may include using an invalid password form (which may give a misleading message), or not choosing subnets in at least two availability zones. - -Otherwise, you will see that your stack is being created, and its status (shown in blue) will be *CREATE_IN_PROGRESS*. You may also check the *Resources* tab to see the many resources that are being created to make up the complete stack. - -If the create succeeds, the status will eventually change to CREATE_COMPLETE (shown in green). This may take a fairly long time. - -== Update Configuration -To update the Kill Bill configuration parameters, select the CloudFormation stack and click on *Update*. The update stack consists of the following 4 steps: - -* Step 1 - Update stack: select *Use current template* and click Next - -image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step1.JPG[align=center] - -* Step 2 - Specify stack details: update any of the parameters and click Next - -image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step2.JPG[align=center] - -* Step 3 - Configure stack options: no changes are needed at this step - -image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step3.JPG[align=center] - -* Step 4 - Review: review all the changes made to the parameters, scroll down and check *I acknowledge that AWS CloudFormation might create IAM resources* and click on *Submit*. - -image::https://github.com/vnandwana/killbill-docs/raw/v3/userguide/assets/aws/cf-update-config-step4b.JPG[align=center] - -CloudFormation stack will start updating all these configurations, and upon completion, its status will change to *UPDATE_COMPLETE*. - -== Enabling HTTPS - -Your deployment is initially accepting external communications, such as KAUI interaction, using HTTP. For secure and private communication we recommend the use of HTTPS. For information about HTTPS and how to create a certificate see https://docs.killbill.io/latest/using-https.html[Using HTTPS]. If you don't already have a certificate we recommend creating one using the Amazon Certificate Manager (ACM). - -To configure the load balancer to accept SSL connections, proceed as follows: - -First, find the load balancer in the EC2 console: - -image::../assets/aws/find-lb.png[align=center] - -Two HTTP listeners are configured by default, on ports 9090 (Kaui) and 80 (Kill Bill). You need to add two additional HTTPS listeners. - -For example, to expose Kaui behind port 443, the configuration would look like this (note the Forward To section): - -image::../assets/aws/add-lb-listener.png[align=center] - -When requested, follow the instructions to import your certificate. - -You will also need to allow HTTPS traffic in your security group: - -image::../assets/aws/lb-security-group.png[align=center] - -The load balancer is now configured to redirect SSL traffic on port 443 to Kaui. You can do the same for Kill Bill (using port 8443) and disable the HTTP rules in your Security Group. - -== CloudWatch - -Our AMIs come pre-configured with CloudWatch integration to allow for better diagnostics. Below is a screenshot of the metrics that come for free: - - -image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aws/cloudwatch.png[align=center] - - -To support business metrics, we also support the use of additional plugins suchs as our free https://github.com/killbill/killbill-analytics-plugin[Analytics plugin]. This provides a subscription billing management solution as feature-rich as popular SaaS platforms, but that you can control. Below is a screenshot of these business metrics: - - -image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/aws/analytics.png[align=center] - - -For installation support along the way, reach out to `support@killbill.io`. - - -== Testing - -If you are using HTTP, go to your browser and type `http://DNS_NAME`, where DNS_NAME is the *DNS name* for your load balancer as given on the Load Balancer dashboard. You should see: - -image::../assets/aws/cf-success.png[align=center] - - -If you are using HTTPS you should be able to login to KAUI from your browser using the URL https://kaui.DOMAIN, where DOMAIN is *your* domain that you have used for your certificate. If you are using HTTP you will need to use the URL http://DNS_NAME where DNS_NAME is the *DNS name* for the KAUI load balancer as given on the Load Balancer dashboard. - -The KAUI login screen should appear. For an introduction to KAUI, see our https://docs.killbill.io/latest/getting_started.html#_using_kill_bill_with_kaui[Getting Started] guide. The default credentials are: `admin` / `password`. The first few requests might be a bit slow as Kill Bill initializes itself. - - -Similarly, you should be able to login directly to the Kill Bill server using the URL https://kaui.domain:8443 or the URL http://DNS_NAME:8443. - -Congratulations! Your CloudFormation installation is ready to go! - - -== TroubleShooting - -=== Stack Creation - -There are several possible issues that could arise when starting the stack from CloudFormation (CFN). The goal of this section -is to provide some tips debugging the issues, and knowledge about where to find various logs. Also keep in mind -that starting the CFN stack will typically take in the order of 15-20 minutes, mostly because of the time it takes to setup the -RDS cluster, so be patient... - - -Let's start with the https://console.aws.amazon.com/cloudformation[CloudFormation console]: The stack will have a status which will be `CREATE_IN_PROGRESS` for the duration of the initialization, and will then either transition to `CREATE_COMPLETE` or `CREATE_FAILED`. In case of `CREATE_FAILED`, try to locate from the `Resources` tab which resource failed to initialize properly. - -=== Possible Issues - -The main possible issues can be summarized as: - -**Issues with the template** - -If you think there is an issue with the CFN template itself, please report any issue to `support@killbill.io` - -**AWS Errors** - -Typical Issues are: - - * Insufficient IAM Permissions - * Limit Exceeded - * Security Group Does Not Exist in VPC - * RDS Cluster failed to come up - * ... - -Make sure to check the discussion above to ensure you have setup a valid VPC with valid subnets. Fow AWS specific issues, please refer to the https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html[AWS troubleshooting documentation] - -**Service Unavailable** - -We suggest to check the following: - -1. Are there any issues reported in the CFN logs? -2. Is the database up and running and accessible from the Kill Bill/Kaui EC2 instances? -3. Is the database schema correctly installed? -4. Is the Kill Bill/Kaui server correctly started and listening on the correct ports? -5. Are the Kill Bill/Kaui servers accessible from the LB, respectively on the correct ports? -6. Are there any errors or stack traces in our logs? - -=== Practical Tips - -**SSH to EC2 Instances** - -In order to answer these questions, you will first need to be able to SSH to the EC2 instances: - -From the EC2 dashboard, you can locate the instances by filtering on a prefix in the stack's name, in my case `my-stack`, and as indicated below you will see the instances for Kill Bill server and KAUI. In the example below we see one of each: - - -image::../assets/aws/ec2-instances.png[align=center] - -You can select one instance and then from the description tag, you will have access to: - -1. Public DNS -2. The security group - -image::../assets/aws/ec2-description.png[align=center] - -You will need to first click on the security group link to open the inbound port 22 required for SSH, as shown below: - -image::../assets/aws/security-group.png[align=center] - -Then, you can issue the SSH command, by copying the Public DNS from the description tab: - -``` -# SSH as ubuntu user -> ssh -i /.pem ubuntu@ -# Move to tomcat user -> sudo su - tomcat -``` - -=== CloudFormation Logs - - -If there are any issue with CFN, it should be available from `/var/log/cfn-init-cmd.log` or `/var/log/cfn-init.log` - -Other logs of interest may include: -``` -/var/log/cfn-wire.log -/var/log/cloud-init-output.log -/var/log/awslogs.logs -/var/log/xray/xray.log -``` - -**Kill Bill/KAUI Server Logs** - -The Kill Bill/KAUI server logs are located under `/var/lib/tomcat/logs/`, with the main 2 interesting logs being: - -* `killbill.out`: All Kill Bill server logs, configured as `INFO` by default -* `kaui.out`: All KAUI server logs, configured as `INFO` by default -* `localhost_access_log...`: Access requests to the servers - -The configuration of the logging (log rotation, log level, ...) can be found in `/var/lib/killbill/config/logback.xml` - -If you update the `logback.xml` (or any configuration file) you will need to restart the service. In order to restart the service, you can run as `root` the following command: - -``` -# Restart killbill server instance -> service killbill restart -# Restart kaui server instance -> service kaui restart -``` - -=== Access to the Database - -From any Kill Bill EC2 instance, it is possible to access the RDS database. On each node, there is a `mysql` client installed -allowing database access. The database hostname can be obtained from the CFN Resources screen, or one can also -extract this information from the `killbill.properties` file: - -``` -> grep 'org.killbill.dao' /var/lib/killbill/config/killbill.properties -org.killbill.dao.password=killbill -org.killbill.dao.url=jdbc:mysql:aurora://mystack-test-rdscluster-1qwiqitatcb9m.cluster-cah16olm8gkg.us-east-1.rds.amazonaws.com:3306/killbill -org.killbill.dao.user=killbill -``` - -Based on such info, the following command would allow you to get a mysql prompt: - -``` -> mysql -h mystack-test-rdscluster-1qwiqitatcb9m.cluster-cah16olm8gkg.us-east-1.rds.amazonaws.com -u killbill -pkillbill killbill -> show tables -> ... -``` - -=== Service Health - -Since both Kill Bill/KAUI server listen on port 8080, you can check if the service is running by issuing the following command: - -``` -telnet 127.0.0.1 8080 -Trying 127.0.0.1... -Connected to 127.0.0.1. -Escape character is '^]'. -``` - -For the Kill Bill server specifically some useful commands are: - - -``` -# Healthcheck -> curl http://127.0.0.1:8080/1.0/healthcheck -``` - -``` -# Check which Kill Bill & plugin versions -> curl -u admin: http://127.0.0.1:8080/1.0/kb/nodesInfo | jq -[ - { - "nodeName": "ip-192-168-65-236.ec2.internal", - "bootTime": "2020-02-02T21:26:44.000Z", - "lastUpdatedDate": "2020-02-02T21:26:44.000Z", - "kbVersion": "0.22.1", - "apiVersion": "0.53.17", - "pluginApiVersion": "0.26.3", - "commonVersion": "0.23.7", - "platformVersion": "0.39.12", - "pluginsInfo": [ - { - "bundleSymbolicName": "org.kill-bill.billing.killbill-platform-osgi-bundles-kpm", - "pluginKey": null, - "pluginName": "org.kill-bill.billing.killbill-platform-osgi-bundles-kpm", - "version": null, - "state": "RUNNING", - "isSelectedForStart": true, - "services": [] - }, - { - "bundleSymbolicName": "org.kill-bill.billing.killbill-platform-osgi-bundles-logger", - "pluginKey": null, - "pluginName": "org.kill-bill.billing.killbill-platform-osgi-bundles-logger", - "version": null, - "state": "RUNNING", - "isSelectedForStart": true, - "services": [] - } - ] - } -] -``` - -=== Diagnostic Command - -The `diagnostic` option of the `kpm` command creates an extensive report for a given tenant that may be useful for troubleshooting. To run this command: - -``` -# Login as 'tomcat' -> sudo su - tomcat -# -# Details about DB host can be extracted from '/var/lib/killbill/config/killbill.properties' -# -# Run the command with your access credentials: -# -> kpm diagnostic \ - --killbill-credentials=ADMIN PASSWORD \ - --bundles-dir=/var/lib/killbill/bundles \ - --database-name=killbill \ - --database-credentials=DBUSER DBPASS \ - --killbill-api-credentials=KEY SECRET \ - --killbill-web-path=/var/lib/tomcat/webapps \ - --database-host=DBHOST -``` - -You will need to edit this command to include: - -1. Your KAUI username and password (ADMIN PASSWORD) -2. Your database credentials (DBUSER DBPASS) -3. The key and secret key for your tenant (KEY SECRET) -4. Your database host (see '/var/lib/killbill/config/killbill.properties' ) - -The last line of the response should look like: - -``` -Diagnostic data exported under /tmp/killbill-diagnostics-20200212-26849-c0rrz3/killbill-diagnostics-02-12-20.zip -``` - -Note that there is also a `--account-export=` flag to export the data associated with a specific Kill Bill `account_id`. - - -== Upgrade Steps - -=== Newer AMIs - - -The Kill Bill core team will provide new AMIs whenever necessary. - -Because the CloudFormation from AWS Marketplace will always reflect the latest AMI ids, you can simply update the stack with the latest CloudFormation template and the instances in the AutoScaling groups will be updated automatically. -We strongly recommend that you always test the upgrade in a test environment first. - -We recommend that you rely on the CloudFormation `ChangeSet` functionality to get a sense of what would be updated if the change was submitted. For more information about the CloudFormation `ChangeSet` functionality see this https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks.html[documentation]. Below is a summary of the steps: - -[1]. Download the new CloudFormation template - -Each AMI is defined by a CloudFormation template. To access the template for the latest AMI, go to the Marketplace page as described under *Configure and Launch* above. Check that the page lists the desired version, then scroll down to the *Usage Information* section. Expand the link *View Cloudformation Template*. Below the diagram that appears, click *Download Cloudformation Template*. Save the template file. This will be a long text (JSON) file with a name ending in `template`. - -image::../assets/aws/change-set-usage-information.png[align=center] - - -[2]. Create a new ChangeSet - -Go to the CloudFormation dashboard and select you current stack. Then select *Stack Details* from the left menu. You should see the following page: - -image::../assets/aws/create-change-set.png[align=center] - -Select *Create Change Set.* On the page that appears, Select *Replace Current Template*, then select *Upload a Template File*. Finally, upload the file you downloaded in Step 1. - -You will now revisit several pages that you saw when the stack was created. First, you will see the page *Specify Stack Details*. At this time there should be no changes required. Click *Next*. - -The next page will be the *Configure Stack Options*. Again, no changes required. - -THe last page is the *Review* page. If everything looks good, scroll to the bottom. You will see the following message, that you will need to acknowledge: - -image::../assets/aws/change-set-capabilities.png[align=center] - -Finally click *Create Change Set*. You can provide an optional description in the popup that appears, then select *Create Change Set* again. Your change set will be created. You will initially see the status *CREATE_PENDING*. Wait until the status message changes to *CREATE_COMPLETE*. - - -[3]. Apply the ChangeSet - -It is important to remember that at this point your Kill Bill installation has not changed. Your change set is ready and waiting when you do want to use it. When that time comes, return to the cloudformation dashboard, select your stack and select the *change sets* tab. Select your change set, then click *Execute*. - -image::../assets/aws/change-set-execute.png[align=center] - -Your new resources will be created and any old ones no longer needed will be deleted. The status of the stack will show as *UPDATE_IN_PROGRESS*. For a short time the stack may be in an unusable state. When the status changes to *UPDATE_COMPLETE*, the stack has been fully updated to the new version. diff --git a/userguide/tutorials/aws-multitier.adoc b/userguide/tutorials/aws-multitier.adoc deleted file mode 100644 index 3d85ae142..000000000 --- a/userguide/tutorials/aws-multitier.adoc +++ /dev/null @@ -1,448 +0,0 @@ -= Multi-Tier Option - - -There are three different ways to setup a working Kill Bill system on AWS, using software preconfigured by Kill Bill. Two options are based on a single *Amazon Machine Image (AMI)* containing the complete Kill Bill stack, that is both the Kill Bill server and the administrative UI (KAUI). These options are *single-tier* and *multi-tier*. The https://docs.killbill.io/latest//aws-singletier.html[*single-tier* option] is designed to deploy a limited version of Kill Bill quickly for trial and experimentation. For production deployments, we offer the multi-tier option. A third alternative available for deploying a production system is https://docs.killbill.io/latest//aws-cf.html[CloudFormation templates]. The multi-tier option requires more setup than CloudFormation, but provides more control over the deployment. - -== Overview - -This document describes the multi-tier option. This configuration uses two or more EC2 instances and a separate database provided by the AWS *Relational Database Service (RDS)*. It also includes 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. - -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::../assets/aws/multi-tier-ami_deployment.svg[width=750,align=center] - -== 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. - -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. - -=== Setup the Database Manager - -Once you are logged in, the first step is to setup the RDS instance. This process begins with the RDS dashboard, which should be available from the Services menu. When the dashboard appears, select *Databases* from the left menu, and click the red button at the top right that reads *Create Database*: - -image::../assets/aws/multitier-create-database.png[align=center] - -==== 1. Set the Configuration - -You will be taken to the *Create Database* page. The first choice you will have is between *Standard Create*, which allows you to set a full range of configuration parameters, or *Easy Create*, which sets most of these parameters to defaults. We recommend *Easy Create* in most cases. - -image::../assets/aws/multitier-standard-or-easy.png[align=center] - -The next section offers you a choice of several database types. Kill Bill can work with any database type that is `mysql` or `postgres` compatible. For robust production use, Amazon Aurora is probably a good choice. Here we will illustrate the simpler steps setting up a MariaDB database. - -image::../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::../assets/aws/multitier-instance-sizes.png[align=center] - -The last section asks you to: - -1. Specify a name for your database -2. Give a username for the administrative account (we suggest that you do *not* use the default name) -3. Provide a password for the administrative acount (we suggest you let AWS generate one for you) - -image::../assets/aws/multitier-names-and-password.png[align=center] - -==== 2. Create the DBM - -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::../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::../assets/aws/multitier-connectivity-and-security.png[align=center] - -==== 3. Setup the Security Rules - -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 - -To set up the EC2 instances you will need to provide them with information needed to connect to the databases. We provide a brief configuration script to simplify this process. The template for this script is as follows: - - -``` -#!/bin/bash - -DB_PROPS="/var/tmp/db.props.$$" -KB_PROPS="/var/tmp/kb.props.$$" - -cat <<_EOF > $DB_PROPS -# -# EDIT THE FOLLOWING DB PROPERTIES AS NEEDED: -# -DB_SERVER=DB-INSTANCE-NAME:3306 -DB_USER=ADMIN-NAME -DB_PASSWORD=PASSWORD -KILLBILL_DB_NAME=killbill -KAUI_DB_NAME=kaui -_EOF - -cat <<_EOF > $KB_PROPS -# -# EDIT THE FOLLOWING KB PROPERTIES AS NEEDED: -# -org.killbill.dontexist=foo -_EOF - -su -l -c "cd /var/lib/tomcat/bin && /var/lib/tomcat/bin/updateProperties.sh $DB_PROPS $KB_PROPS" tomcat -``` -First, you need to edit the database properties. DB_SERVER should be set to the full name of the DB instance, as given in the *Connectivity and Security* panel (see above). The port number 3306 is required. DB_USER and DB_PASSWORD should be set to the administrator credentials you have chosen for the RDS instance. - -Second, you may optionally edit any Kill Bill properties that you need to change from the standard defaults. For more information see the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide]. - -Save this script in a text file. You will need it in the next step. - -=== Launch EC2 Instances - -The next step is to launch the number of EC2 instances you want, all based on the Kill Bill single AMI. - - -==== 1. Subscribe to the 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: - -image::../assets/aws/multitier-subscribe.png[align=center] - -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*. - -==== 2. Configure the Instances - -The next page will give several configuration options: - -image::../assets/aws/multitier-configure.png[align=center] - -Be sure to select the region you plan to operate in. In most cases you should accept the other 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::../assets/aws/multitier-launch.png[align=center] - -All other options will disappear. Click *Launch*. - -The next page is headed *Launch an Instance*. There ar several things you will need to do here. - -First, at the top right, select the number of instances you will use. We recommend 2. You can add more later. - -Next, scroll down to the middle of this page, to the box titled *Key Pair (login)* Here you are asked to choose or create a *key pair*. - -image::../assets/aws/single-tier-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. Click *Create 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. - -Finally, scroll to the bottom and open the section labeled *Advanced Details*. You will see a long list of settings. At to the very bottom of this list is a box headed *User Settings*. Copy your configuration file into this box. - -==== 3. Launch your Instances - -When the key pair is generated, click *Launch Instances*. You should see the screen below: - -image::../assets/aws/multitier-launching.png[align=center] - -Your instances are 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::../assets/aws/multitier-instances.png[align=center] - - -In a short time, the *Instance State* for each instance should indicate *Running*. You will need to scroll to the right to see all of the information available about your instances. In particular, make a note of the *Availability Zone* (such as `us-east-1a`) assigned to each instance. You will need this information later. - -==== 4. Setup Security Rules - -The next step 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::../assets/aws/multitier-inbound-original.png[align=center] - -These rules enable the ports that must be open to access KAUI and Kill Bill from a browser. However, for access through the ELB these ports will be different. In addition, to enable direct login to your instance using SSH, you need to add one more port. - -Click on *Edit Inbound Rules*. then do the following: - -1. For the rule that specifies Type: HTTPS, Port Range: 443, change the type to CUSTOM TCP and the Port Range to 3000. -2. For the rule that specifies Type: CUStOM TCP, Port Range: 8443, change the Port Range to 8080. -3. Finally, 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::../assets/aws/multitier-inbound-new.png[align=center] - - -==== 5. Login to an Instance - -Now that your instances are set up, you need to ensure that you can login to them for configuration and maintenance when needed. 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 for any one of your instances as 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`. - -You will now be able to explore your instance and perform various configuration and maintenance tasks. To exit from your login, type `exit`. - - -=== Create the Databases - -Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases. - -To create the databases, you will need to login to one of your instances as described above. Once you are logged in, you can use the `mysql` command to create the two databases `killbill` and `kaui`. The credentials for this command are the same ones you set up for the database and copied to the configuration file. Note that the DB-INSTANCE-NAME should *not* include the port number. - -The password will not be echoed when it is typed. - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p -Enter Password: -mysql> create database killbill; -mysql> create database kaui; -mysql> exit -``` -The next step is to install the schemas. These can be found at: - -* killbill schema: `https://docs.killbill.io/latest/ddl.sql` -* kaui schema: `https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql` - -One easy way to do this is to return to your local computer (type `exit`) and download the schemas (give them distinct names), then use the `sftp` command to upload them to your EC2 instance home directory with the commands: - -``` -sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP -put killbill.ddl -put kaui.ddl -exit -``` - -Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas: - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p killbill < killbill.ddl -Enter Password: -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p kaui < kaui.ddl -Enter Password: -``` -To ensure that the databases are setup correctly, login to `mysql` again, then try the SHOW TABLES command: - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p -Enter Password: -use killbill -show tables; -use kaui -show tables; -exit -``` - -Each `show tables` command should display a list of table names for the database. - -=== Initial Testing - -You can now login to KAUI from your browser using the URL http://INSTANCE_IP:3000, 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. For an introduction to KAUI, see our https://docs.killbill.io/latest/getting_started.html#_using_kill_bill_with_kaui[Getting Started] guide. The default credentials are: `admin` / `password`. The first few requests might be a bit slow as Kill Bill initializes itself. - -In addition, you can login to the Kill Bill server using the URL http://INSTANCE_IP:8080. This provides access to certain detailed reports that may be needed for maintenance, including metrics, event logs, and the Swagger API pages. - -If these logins succeed, your EC2 instances and your RDS databases are setup properly. - - -=== Add the ELB - -The last major task is to setup the Elastic Load Balancer in front of the EC2 instances. - -==== 1. Select the ELB type - -To begin, from the EC2 dashboard scroll down the left-hand menu and select *Load Balancing / Load Balancers*. Then click the *Create Load Balancer* button at the upper left. - -You will be given a choice of several load balancer types. The type we will use is *Application Load Balancer*. Click on the *Create* button in the Application Load Balancer box. This will bring up the page titled *Create Application Load Balancer*. This is your master page for the load balancer creation. - -==== 2. Basic Configuration - -In the section headed *Basic Configuration*, give your load balancer a name. Do not change the other settings. - -In the *Network Mappings* section, select *at least two* availability zones. These *must* include the avail ability zones assigned to each of your EC2 instances (which you took note of earlier). - -==== 3. Setup a Security Group - -The next section is headed *Security Groups*. Click on *create new security group*. This will open a page headed *Create security group*. - -Art this time you should decide whether you want to use the secure protocol `HTTPS` (based on TLS) or the unsecure protocol `HTTP` for users to access your system. The secure protocol is strongly recommended. However, this will require you to provide or create a certificate in a later step. - -Enter a name and a brief description for your security group. The description cannot be empty. Then setup the Inboud Rules as follows: - -image::../assets/aws/multitier-inbound-original.png[align=center] - -These rules assume you are using HTTPS. If you are using HTTP, the port for the second rule should be 80 instead of 443. - -When your security group is set, return to the master page and select this group from the dropdown list. You may need to use the refresh icon to make your mew group appear in the list. Delete any other group that remains selected. - -==== 4. Create Listeners - -The next section is titled *Listeners and Routing*. This is the last section you will have to deal with, but it is very important. This is where you will setup the Listeners that will receive requests for Kaui or Kill Bill and pass them on to the appropriate modules in your EC2 instances. - -Initially you will see one listener, set with protocol HTTP and Port 80. If you are using HTTP this is correct. If you are using HTTPS, change the protocol to HTTPS and the port to 443. If you choose HTTPS, a new section will open up, headed *Secure listener settings*: - -image::../assets/aws/ELB-secure-listener.png[align=center] - -Here you will be required to create or provide an X.509 SSL Certificate. If you already have a certificate you can identify it or upload it here. Otherwise we recommend you click on *Request a New Certificate from ACM.* This will enable you to create a certificate using the *Amazon Certificate Manager*. Follow the steps described for the ACM in https://docs.killbill.io/latest/using-https.html[Using HTTPS], then return to this page and proceed to the next step. In any case the Security Policy should not be changed. - -Next you will need to click on *Add Listener* to create a second Listener. No matter whether you are using HTTP or HTTPS, this listener witt use port 8443. - - -==== 5. Setup Target Groups - -The next step is to identify the *target* instances for your load balancer, which are collected into a *target group*. Each listener will have a separate target group. Note that the display for each listener contain a link labeled *Create target group*. Click on this link for the first listener. This will setup the routing for messages directed to Kaui. - -Your group will consist of all of the instances you have launched. First, create the group, give it a simple name, and set the port to 3000: - -image::../assets/aws/ELB-configure-routing.png[align=center] - -Now click on *Next*, to open a page titled *Register Targets*. The purpose of this step is to identify the target instances that will be part of your target group. Initially, all your instances will be listed at the top. To register them, select them all and click *Include as pending below*. The instances will now be listed in the bottom section Then proceed to *Next: Review*. If all looks well, click on *Create Target Group*. This will bring you to the *Target groups* page, and your new group should appear. - -Now return to the master page where you created the listeners. Click on the refresh icon for the first listener, then select your new target group from the dropdown list. - -image::../assets/aws/ELB-listener-with-TG.png[align=center] - - -Next, you need to perform the same steps for the second listener. This listener will handle messages directed to the Kill Bill server. Click the link on the second listener labeled *Create target group*. Follow the same steps, setting the port this time to 8080. - -When both target groups are setup, you will have a chance to review your settings, then proceed to the next section. - - -==== 6. Create the Load Balancer - -Check all settings, then click *Create*. Your load balancer will be created. Close the final page to see the Load Balancer list. The initial status for your new ELB will be *provisioning*. After a few minutes this will change to *active*. - -== Final Testing - -When your ELB is complete you can proceed to testing. If you are using HTTPS you should be able to login to KAUI from your browser using the URL https://kaui.DOMAIN, where DOMAIN is *your* domain that you have used for your certificate. If you are using HTTP you will need to use the URL http://DNS_NAME where DNS_NAME is the *DNS name* for the KAUI load balancer as given on the Load Balancer dashboard. - -The KAUI login screen should appear. For an introduction to KAUI, see our https://docs.killbill.io/latest/userguide_kaui.html[Kaui Guide]. The default credentials are: `admin` / `password`. The first few requests might be a bit slow as Kill Bill initializes itself. - - -Similarly, you should be able to login directly to the Kill Bill server using the URL https://kaui.domain:8443 or the URL http://DNS_NAME:8443. - -Congratulations! Your multi-tier installation is ready to go! - -== Configuration - -Kill Bill defines a number of global properties and per-tenant properties that can be varied. These properties are explained in the https://docs.killbill.io/latest/userguide_configuration.html[configuration guide]. Default values for these properties are built into the Kill Bill code; these values can be overridden by values defined in the file `/var/lib/killbill/config/killbill.properties`. For example, this is where you can change the database URL and credentials. - -This file also defines the location of the `shiro.ini` file, which by default is in the same directory. This file defines the Kill Bill admin credentials, along with any other users and their roles. See the https://docs.killbill.io/latest/user_management.html[RBAC guide] for details about this file. - -If you make changes to these configuration files, remember to make the same changes to *all* your EC2 instances! - -== Upgrading - -From time to time new versions of Kill Bill and KAUI may be released. This section explains how to upgrade to these new versions. You will need to follow these procedures for *each* of your instances. - -First, login to your instance using `ssh`, then switch to the `tomcat` user: - -`sudo su - tomcat` - -The configuration file `/var/lib/killbill/kpm.yml` specifies the Kill Bill version (and its plugins) to be run on the instance. Once you edit this file to specify the new version number, it will be used automatically. Perform the following steps: - -1. Edit the configuration file to update the version number -2. Run the command `$KPM_INSTALL_KB_CMD` -3. Delete the cached directory `/var/lib/tomcat/webapps/ROOT` -4. Restart the instance. - -A similar process can be used for KAUI: update `/var/lib/kaui/kpm.yml`, run `$KPM_INSTALL_KAUI_CMD`, delete the cached directory `/var/lib/tomcat/webapps2/ROOT` and restart the instance. - -== Troubleshooting - -If your installation does not seem to work correctly, the first step is to review your installation process carefully, to be sure that everything has been done and checked as described in this document. If problems persist, we will be glad to work with you to identify the problem. To help us to do this, there are several information reports that you may need to gather. These reports are somewhat technical but can be analyzed by Kill Bill personnel. This section explains how to obtain the reports that may be needed. - -The procedures described here focus on obtaining detailed reports for a single EC2 instance. They should be used independently for each instance you have deployed. - -=== System Health Check - -The healthcheck report checks the health of various software components, and determines if any queues are growing improperly over time. To create this report, login to your EC2 instance and issue the following command: - -`curl http://127.0.0.1:8080/1.0/healthcheck` - -This will return a series of messages giving the health status of each component. - -=== System Information - -For a detailed system information report, use the following command: - -`curl -u ADMIN:PASSWORD http://127.0.0.1:8080/1.0/kb/nodesInfo` - -Here ADMIN and PASSWORD are your KAUI administrator access credentials. - -=== Service Statuses - -This procedure does not produce a report, but does provide important information about the status of each service. - -The Kill Bill multi-tier option runs two services on each instance. The status of each service can be checked by the following commands: - -* Kill Bill service: `sudo service killbill status` -* KAUI service: `sudo service kaui status` - -For each report there should be a line near the top with the following form: - -`Active: active (running) since Sat 2020-10-24 20:13:43 UTC; 1 day 1h ago` - - -Similarly you can `start` or `stop` the services using similar commands, such as `sudo service kaui stop` to stop KAUI. - - -=== Log Files - -The system maintains a series of logfiles that should be helpful when troubleshooting is needed. - -Tomcat logs are under `/var/lib/tomcat/logs/`: - -* KAUI logs: `/var/lib/tomcat/logs/kaui.out` -* Kill Bill server logs: `/var/lib/tomcat/logs/catalina.out` - -It is not necessary to download these logs separately, though, as they will be included in the output from the diagnostic command to be discussed next. - -=== Diagnostic Command - -The `diagnostic` option of the `kpm` command creates an extensive report for a given tenant that may be useful for troubleshooting. To run this command: - -``` -# Login as 'tomcat' -> sudo su - tomcat -# -# Run the command with your access credentials: -# -> kpm diagnostic \ - --killbill-credentials=ADMIN PASSWORD \ - --bundles-dir=/var/lib/killbill/bundles \ - --database-name=killbill \ - --database-credentials=DBUSER DBPASS \ - --killbill-api-credentials=KEY SECRET \ - --kaui-web-path=/var/lib/tomcat/webapps2 \ - --killbill-url=http://127.0.0.1:8080 \ - --database-host=DBURL:3306 -``` - -You will need to edit this command to include: - -1. Your KAUI username and password (ADMIN PASSWORD) -2. Your database credentials (DBUSER DBPASS) -3. The key and secret key for your tenant (KEY SECRET) -4. Your database URL (DBURL) - -The last line of the response should look like: - -`Diagnostic data is exported under /tmp/killbill-diagnostics-20200213-23204-u93ah5/killbill-diagnostics-02-13-20.zip` - -The specified zip file contains several reports of various sizes. This report can be downloaded to your computer using `sftp` and forwarded to Kill Bill for analysis. diff --git a/userguide/tutorials/aws-single-ami.adoc b/userguide/tutorials/aws-single-ami.adoc deleted file mode 100644 index c45602f8a..000000000 --- a/userguide/tutorials/aws-single-ami.adoc +++ /dev/null @@ -1,680 +0,0 @@ -= 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::../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 +++AWS Marketplace+++: - -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::../assets/aws/single-ami-subscribe.png[align=center] - -Click *Continue to Subscribe*. The next page will give the AWS Terms and Conditions: - -image::../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::../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::../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::../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::../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::../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::../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::../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/{EC2 instance ID}*. The first few requests might be a bit slow as Kill Bill initializes itself. - -For an introduction to KAUI, see our https://docs.killbill.io/latest/userguide_kaui.html[_Kaui 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 multi-tier configuration. This section will explain how to setup this option. - -image::../assets/aws/multi-tier-ami_deployment.png[align=center] - -=== 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 Network (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. - -=== Setup the Database - -Once you are logged in, the first step is to setup the RDS instance. This process begins with the RDS dashboard, which should be available from the Services menu. When the dashboard appears, select `Databases` from the left menu, and click the red button at the top right that reads `Create Database`: - -image::../assets/aws/multitier-create-database.png[align=center] - -You will be taken to the `Create Database` page. The first choice you will have is between `Standard Create`, which allows you to set a full range of configuration parameters, or `Easy Create`, which sets most of these parameters to defaults. We recommend `Easy Create` in most cases. - -image::../assets/aws/multitier-standard-or-easy.png[align=center] - -The next section offers you a choice of several database types. Kill Bill can work with any database type that is `mysql` or `postgres` compatible. For robust production use, Amazon Aurora is probably a good choice. Here we will illustrate the simpler steps setting up a MariaDB database. - -image::../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::../assets/aws/multitier-instance-sizes.png[align=center] - -The last section asks you to: - -1. Specify a name for your database -2. Give a username for the administrative account (we suggest that you do *not* use the default name) -3. Provide a password for the administrative acount (we suggest you let AWS generate one for you) - -image::../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::../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::../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 - -To set up the EC2 instances you will need to provide them with information needed to connect to the databases. We provide a brief configuration script to simplify this process. The template for this script is as follows: - - -``` -#!/bin/bash - -DB_PROPS="/var/tmp/db.props.$$" -KB_PROPS="/var/tmp/kb.props.$$" - -cat <<_EOF > $DB_PROPS -# -# EDIT THE FOLLOWING DB PROPERTIES AS NEEDED: -# -DB_SERVER=DB-INSTANCE-NAME:3306 -DB_USER=ADMIN-NAME -DB_PASSWORD=PASSWORD -KILLBILL_DB_NAME=killbill -KAUI_DB_NAME=kaui -_EOF - -cat <<_EOF > $KB_PROPS -# -# EDIT THE FOLLOWING KB PROPERTIES AS NEEDED: -# -org.killbill.dontexist=foo -_EOF - -su -l -c "cd /var/lib/tomcat/bin && /var/lib/tomcat/bin/updateProperties.sh $DB_PROPS $KB_PROPS" tomcat -``` -First, you need to edit the database properties. DB_SERVER should be set to the full name of the DB instance, as given in the `Connectivity and Security` panel (see above). The port number 3306 is required. DB_USER and DB_PASSWORD should be set to the administrator credentials you have chosen for the RDS instance. - -Second, you may optionally edit any https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill properties] that you need to change from the standard defaults. - -=== Launch the EC2 Instances - -The next step is to launch the number of EC2 instances you want, all based on the Kill Bill single AMI. - - -To start the installation process, point your browser to +++AWS Marketplace+++: - -You should see the following image at the top of your screen: - -image::../assets/aws/multitier-subscribe.png[align=center] - -Click *Continue to Subscribe*. The next page will give the AWS Terms and Conditions: - -image::../assets/aws/multitier-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::../assets/aws/multitier-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::../assets/aws/multitier-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 **Configure Instance Details** at the bottom of the page. - -The next page will provide you with a long list of options. The first option is **Number of Instances**. Set the number of instances you wish to launch. Each instance will have essentially the same configuration, including the same image, the same subnet and availability zone, and the same security group. - -After setting the number of instances, scroll down to the bottom of the page. The last section is titled **Advanced Settings**. In this section you should set the configuration file you produced above. The setting panel should look like this: - -image::../assets/aws/multitier-userdata.png[align=center] - -Now 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 instances. 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::../assets/aws/multitier-keypair.png[align=center] - -The key pair provides the credentials you will need to login to your EC2 instances. 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. All your instances can use the same one. 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 instances. - -When the key pair is generated, click **Launch Instances**. You should see the screen below: - -image::../assets/aws/multitier-launching.png[align=center] - -Your instances are 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::../assets/aws/multitier-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 instances. - -=== Setup Security Rules - -You are almost set, but there is one more thing you need to 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::../assets/aws/multitier-inbound-original.png[align=center] - -These rules enable the ports that must be open to access KAUI and Kill Bill from a browser. However, for access through the ELB these ports will be different. In addition, to enable direct login to your instance using SSH, you need to add one more port. - -Click on **Edit Inbound Rules**. then do the following: - -1. For the rule that specifies Type: HTTPS, Port Range: 443, change the type to CUSTOM TCP and the Port Range to 3000. -2. For the rule that specifies Type: CUStOM TCP, Port Range: 8443, change the Port Range to 8080. -3. Finally, 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::../assets/aws/multitier-inbound-new.png[align=center] - - -=== Create the Databases - -Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases. - -To create the databases, you will need to login to *one* of your instances. 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*. The `ssh` command relies on the security rule providing access to Port 22, which you added in the previous step. - -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`. - - -Once you are logged in, you can use the `mysql` command to create the two databases `killbill` and `kaui`. The credentials for this command are the same ones you set up for the database and copied to the configuration file. Note that the DB-INSTANCE-NAME should *not* include the port number. - -The password will not be echoed when it is typed. - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p -Enter Password: -mysql> create database killbill; -mysql> create database kaui; -mysql> exit -``` -The next step is to install the schemas. These can be found at: - -* killbill schema: `https://docs.killbill.io/latest/ddl.sql` -* kaui schema: `https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql` - -One easy way to do this is to return to your local computer (type `exit`) and use the `sftp` command. Then upload them to your EC2 instance home directory with the commands: - -``` -sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP -put killbill.ddl -put kaui.ddl -exit -``` - -Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas: - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p killbill < killbill.ddl -Enter Password: -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p kaui < kaui.ddl -Enter Password: -``` -To ensure that the databases are setup correctly, login to `mysql` again, then try the SHOW TABLES command: - -``` -> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p -Enter Password: -use killbill -show tables; -use kaui -show tables; -exit -``` - -Each `show tables` command should display a list of table names for the database. - -You should now be able to login to KAUI from your browser using the URL http://INSTANCE_IP:3000, where INSTANCE_IP is the IPV4 address for any one of your instances, given on your dashboard as **Public IPV4 Address**. This should display the KAUI login screen. The default credentials are: *admin/{EC2 instance ID}*. The first few requests might be a bit slow as Kill Bill initializes itself. For an introduction to KAUI, see the https://docs.killbill.io/latest/quick_start_with_kaui.html[_Quick Start with Kaui_] guide. - -In addition, the URL http://INSTANCE_IP:8080 should display a page confirming that the Kill Bill server is accessible. - - -=== Add the ELB in front of the EC2 instances - -The last major task is to setup the Elastic Load Balancer in front of the EC2 instances. To begin, from the EC2 dashboard scroll down the left-hand menu and select *Load Balancing / Load Balancers*. Then click the *Create Load Balancer* button at the upper left. - -You will be given a choice of several load balancer types. The type we will use is *Application Load Balancer*. - -image::../assets/aws/ELB-select-type.png[align=center] - -Click on the *Create* button in the Application Load Balancer box. This will bring up the page titled *Step 1: Configure Load Balancer*: - -image::../assets/aws/ELB-basic-configuration.png[align=center] - -On this page you need to do the following: - -1. Assign a name to your load balancer -2. Select a protocol for the listener. We recommend using HTTPS as discussed below. -3. Set the listener port to 443 (if using HTTPS) or 80 (if using HTTP). -4. Click *Add Listener* to add a second listener using the same protocol and set its port to 8443. -5. Scroll to the bottom and select at least *two* availability zones. *IMPORTANT: You must select all of the zones that your EC2 instances are contained in. Otherwise, the load balancer will be unable to connect to these instances.* - -Now choose *Next: Configure Security Settings*. You will now see a page titled *Step 2: Configure Security Settings*. - -image::../assets/aws/ELB-configure-security.png[align=center] - -If you have selected the HTTPS protocol, you will be required to create or provide an X.509 SSL Certificate. If you already have a certificate you can identify it or upload it here. Otherwise we recommend you click on *Request a New Certificate from ACM.* This will enable you to create a certificate using the *Amazon Certificate Manager* as discussed below. When your certificate is created, return to this page and proceed to the next step. - -If you are using HTTP, you will see a warning message, which can be ignored. - -In either case, your next step is to choose *Next: Configure Security Groups*. This will take you to a page titled *Step 3: Configure Security Groups.* This page will show you the existing security groups and offer the choice to choose an existing group or create a new one. We advise you to create a new group. The new security group should have inbound rules enabling inputs for KAUI and Kill Bill as shown here: - -image::../assets/aws/ELB-configure-security-groups.png[align=center] - -These rules assume you are using HTTPS. If you are using HTTP, the port for the first rule should be 80. - -The next step is to identify the *target* instances for your load balancer, which are collected into a *target group*. Each listener will have a separate target group, but you can only setup one right now. The other group will be added later. - -Your group will consist of all of the instances you have launched. First, create the group, give it a simple name, and set the port to 3000: - -image::../assets/aws/ELB-configure-routing.png[align=center] - -Now click on *Next: Register Targets*. The purpose of this step is to identify the target instances that will be part of your target group. Initially, all your instances will be listed in the bottom section. To register them, select them all and click *Add to Registered*. Then proceed to *Next: Review*. - -image::../assets/aws/ELB-register-targets.png[align=center] - -Check all settings, then click *Create*. Your load balancer will be created. Close the final page to see the Load Balancer list. The initial status for your new ELB will be *provisioning*. After a few minutes this will change to *active*. - -You are almost done. Your final step is to modify the second listener to use a different port number to access the Kill Bill server. From the left side menu select *Target Groups*. Click *Create Target Group*. In the page that appears, set the protocol to HTTP and set the port to 8080. Then click *Next*. - -image::../assets/aws/ELB-register-targets-2.png[align=center] - - -The next page is provided to register the targets for this group. Once again you will register all your instances as targets, but this works just a little differently than before. The list of available targets is at the top. Select all of them, then click *Include as Pending Below* to make these targets pending as members of the group. Finally, click *Create Target Group* to create the group. - -Now you will need to associate this group with your load balancer's second listener. Return to the Load Balancer console, select your load balancer, and choose the *Listeners* tab in the bottom information panel. Then in the second entry, click *View/Edit Rules*. - -image::../assets/aws/ELB-edit-rules.png[align=center] - -Your object now is to change the rule for this listener to point to your new target group. To do this: - -1. Click on the pencil icon at the top -2. Click on the pencil icon to the left of the rule -3. Click on the pencil icon under the heading *THEN* -4. Select your new target group in the dropdown list -5. At the top of the page, click *UPDATE* - -Go back to the listener tab and confirm that the second listener points to the new target group. Your load balancer is now ready. - -image::../assets/aws/ELB-check-listeners.png[align=center] - -=== Creating a Certificate - -We recommend for security that you choose the HTTPS protocol to access KAUI. This protocol uses SSL/TLS encryption and authentication to verify and protect all communication with the KAUI server. To use this protocol you must create or provide an X.509 certificate. This section describes how to create a certificate using the *Amazon Certificate Manager (ACM).* - -When you click on *Request a new Certificate from ACM*, as described above, you will be taken to the main page of the ACM. Initially this will probably show that you have no certificates. Click *Request a Certificate*. - -the next page will give you the option to import a certificate, or to request a public or private certificate. Choose *private*, then click again on *Request a Certificate*. This will take you to the *Request a Certificate* page. You are initially at *Step 1: Add Domain Names*. - -image::../assets/aws/ELB-request-certificate.png[align=center] - -To validate your certificate, you must first setup a *CNAME*, or Canonical Name, based on a verified domain that you own (this is *not* an AWS domain). If you do not have a domain, you can obtain one for free, or very low cost, from an online source such as GoDaddy. The CNAME is part of your domain's DNS profile, and your domain provider should have instructions for creating it. The values to use for the CNAME will be seen shortly. You will first setup a *temporary* CNAME just to enable validation of your certificate. You will then create the CNAME that you will actually use to access the system. - -Enter your domain name and click *Next*. On the following page, select *DNS Validation*. The next page gives you the chance to assign one or more tags to your certificate. These are optional and can be skipped. Finally, you are given a chance to review your request. Check everything, then click *Confirm and Request*. The *Validation* page will appear. - -image::../assets/aws/ELB-cert-validation-1.png[align=center] - -At the bottom you will see your domain name with a status of *Pending Validation*. Click the triangle next to your domain name. The display will expand to show the values that you must use to create your validation CNAME. - -image::../assets/aws/ELB-cert-validation-2.png[align=center] - -The two strings labeled *Name* and *Value* should be copied to the two required entries for your CNAME. Copy these long strings carefully. Do not include any trailing periods. There is an option to save these strings in a file so they may be copied more easily, or stored for a later time. - -Your second CNAME is much simpler. The first entry will be *kaui*. The second entry will be simply your domain name, e.g., *killbill.com*. - -When your CNAMEs are set, return to ACM and click *Continue*. The display changes to show that your certificate is *Pending Validation*. The certificate should now appear also on the main ACM page. When (and if) it is validated, the status will change to *Success*. *This may take several hours or more.* A short time later it will change again to *Issued*. - -When your certificate is successfully created, you may delete the temporary (validation) CNAME. Then proceed as described above. - - -=== Testing - -When your ELB is complete you can proceed to testing. If you are using HTTPS you should be able to login to KAUI from your browser using the URL https://kaui.DOMAIN, where DOMAIN is *your* domain that you have used for your certificate. If you are using HTTP you will need to use the URL http://DNS_NAME where DNS_NAME is the *DNS name* for the KAUI load balancer as given on the Load Balancer dashboard. This should display the KAUI login screen. The default credentials are: *admin/{EC2 instance ID}*. The first few requests might be a bit slow as Kill Bill initializes itself. - -For an introduction to KAUI, see the https://docs.killbill.io/latest/quick_start_with_kaui.html[_Quick Start with Kaui_] guide. - -Similarly, you should be able to login directly to the Kill Bill server using the URL http://DNS_NAME:8443. Creating a CNAME for this login is optional. - - - -== Configuration - -=== SSL Certificates - -`nginx` is configured to listen on port 443 for messages to be forwarded to KAUI. Port 443 is the standard port for HTTPS. By default, accessing the service from a web browser will show a `Not Secure` site. In order to make the site secure, you will need to add a valid certificate. The easiest option to add the certificate is to make use of the tool `certbot`, which relies on the free Certificate Authority (CA) `Let’s Encrypt` This method provides an easy way to obtain and install free TLS/SSL certificates. - -`Certbot` is pre-installed in the latest Kill Bill AMI, but if you need a different version of `certbot`, this is also available through the new package manager `snap`. This package manager is also preinstalled in the Kill Bill AMI. - -To validate your certificate, you must first setup a CNAME, or Canonical Name, based on a verified domain that you own. If you do not have a domain, you can obtain one for free, or very low cost, from an online source such as GoDaddy. The CNAME is part of your domain's DNS profile, and your domain provider should have instructions for creating it. - -The CNAME should link your domain to your AWS instance. If your domain is `domain.com` your CNAME might look like `killbill.domain.com`. - - -To setup your certificate, perform the following steps: - -[1]. Create a CNAME linking your domain to your AWS instance. - -[2]. Add your CNAME to the server block in the `nginx` configuration file. - -Using a text editor of your choosing, edit the file `/etc/nginx/sites-enabled/killbill.conf`. You will need to use sudo to edit this file. - -This file contains two server blocks. The second block contains the lines: - -``` -server { - listen 443; - server_name _; -``` -Replace the underscore after `server_name` with your CNAME: - -``` -server { - listen 443; - server_name killbill.domain.com; -``` - -Save the modified file. - -[3]. Reload the configuration file with the command: - -``` -sudo nginx -s reload -``` - -[4]. Enable HTTP traffic on port 80. This is just to allow `certbot` to create your certificate. To do this, go to your EC2 dashboard and add a new inbound rule as follows: Type: HTTP, Protocol: TCP, Port Range: 80, Source: 0.0.0.0/0. Your inbound rules should now look like this: - -image::../assets/aws/single-ami-inbound-port-80.png[align=center] - - -[5]. Remove the existing `certbot` package: - -Type the command - -``` -sudo apt-get remove certbot -``` -When asked if you want to proceed, type `Y` for yes. - -[6]. Install `certbot` using `snap`: - -The following commands will install `certbot` and link it to the `/usr/bin` directory: - -``` -sudo snap install --classic certbot -sudo ln -s /snap/bin/certbot /usr/bin/certbot -``` -[7]. Run `certbot` to create and install the certificate: - -``` -sudo certbot --nginx -``` -If you are asked, confirm the server name to be used. If all goes well, you will see a message like: - -``` -IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/deployment.killbill.io/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/deployment.killbill.io/privkey.pem - Your cert will expire on 2020-05-11. To obtain a new or tweaked - version of this certificate in the future, simply run certbot again - with the "certonly" option. To non-interactively renew *all* of - your certificates, run "certbot renew" - - If you like Certbot, please consider supporting our work by: - - Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate - Donating to EFF: https://eff.org/donate-le -``` - -Of course, there are a few things that could go wrong: - -[1]. `certbot` will attempt to validate your CNAME through your domain provider. If the CNAME does not link correctly to the public DNS name for your AWS instance, the certificate will not be created. - -[2]. You could get a message like: - -`Error creating new order : Cannot issue for ec2-18-234-168-57.compute-1.amazonaws.com: The ACME server refuses to issue a certificate for this domain name, because it is forbidden by policy` - -This could happen if you have tried to use your public DNS name directly as your CNAME, which is not allowed. - - -[3]. You could get a message like `certificate cannot be installed`. - -For help with these and other problems, try the `certbot` https://certbot.eff.org/help/[help page]. - - -When your certificate is installed, you should be able to access KAUI from you browser using `https://` followed by your CNAME as the address. The browser should indicate that the site is secure. - -When your certificate is successfully installed, you can edit your security groups again to remove the access through port 80. - -The `Let's Encrypt` certifcates are only valid 90 days and will therefore neeed to be renewed. `certbot` will create a cron entry under `/etc/cron.d/certbot` to make this process automatic. - -=== Kill Bill Properties - -Kill Bill global properties are defined in `/var/lib/killbill/config/killbill.properties`. For example, this is where you can change the MySQL credentials. Take a look at our https://docs.killbill.io/latest/userguide_configuration.html[configuration guide] for more details. - -This is also where you can change the default Kill Bill admin credentials: specify `org.killbill.security.shiroResourcePath=/var/lib/killbill/config/shiro.ini` and create the `shiro.ini` file accordingly (see our https://docs.killbill.io/latest/user_management.html[RBAC guide] for more details). - -== TroubleShooting - - -After launching the EC2 instance, the full stack should come up, with all services enabled and running, that is: - -* An nginx instance receiving traffic on port `443` and `8443` -* A instance of Kill Bill server listening on `127.0.0.1:8080` (and receiving external traffic through nginx on port `8443`) -* A instance of Kaui listening on `127.0.0.1:3000` (and receiving external traffic through nginx on port `443`) -* A local `mysql` server running on port `3306` - - -In this section, we will provide some tips to verify the operation of the system, and what to do when things are not working. - -=== System Health - - -To verify the overall health of the Kill Bill server instance, you can issue the following command: - -``` -curl http://127.0.0.1:8080/1.0/healthcheck -``` - -This will return a series of messages giving the health of various system components. - -A detailed system information report is available using the following command: - -``` -curl -u :<{EC2 instance ID}> http://127.0.0.1:8080/1.0/kb/nodesInfo -``` -Here and <{EC2 instance ID}> are your administrator access credentials. - -The Kill Bill single-tier option is composed of four services. The status of each service can be checked by the following commands: - -* Kill Bill service: `sudo service killbill status` -* KAUI service: `sudo service kaui status` -* Nginx service: `sudo service nginx status` -* Mysql service: `sudo service mysql status` - -For each report there should be a line near the top with the following form: - -``` -Active: active (running) since Sat 2020-10-24 20:13:43 UTC; 1 day 1h ago -``` - - -Similarly you can `start` or `stop` the services using similar commands, such as `sudo service kaui stop` to stop KAUI. - - -=== Log Files - -The system maintains a series of logfiles that should be helpful when troubleshooting is needed. - -Tomcat logs are under `/var/lib/tomcat/logs/`: - -* KAUI logs: `/var/lib/tomcat/logs/kaui.out` -* Kill Bill server logs: `/var/lib/tomcat/logs/catalina.out` - -Nginx logs can be found under `/var/log/nginx/` - -* Access logs: `/var/log/nginx/access.log` -* Error logs: `/var/log/nginx/error.log` - -=== System Diagnostics - -If support is needed, we may require some additional detailed information about your deployment. We have created a `diagnostic` command for this purpose. to run this command: - -``` -# Login as 'tomcat' -> sudo su - tomcat -# -# Set your access credentials. This example -# assumes the default credentials are used: -# -> kpm diagnostic \ - --killbill-credentials=admin {EC2 instance ID} \ - --bundles-dir=/var/lib/killbill/bundles \ - --database-name=killbill \ - --database-credentials=root root \ - --killbill-api-credentials=bob lazar \ - --kaui-web-path=/var/lib/tomcat/webapps2 \ - --killbill-url=http://127.0.0.1:8080 \ - --database-host=127.0.0.1:3306 - -... -The diagnostic data is exported under /tmp/killbill-diagnostics-20200213-23204-u93ah5/killbill-diagnostics-02-13-20.zip -``` - -=== Databases - -To access the mysql (MariaDB) databases, you can use the following command: - -``` -mysql -u root -proot -``` - -This enables interactive access to the database manager. There is one `killbill` and one `kaui` database created and used by the respective applications. To verify the tables in each database, you can type: - -``` -use killbill; -show tables; -``` -or - -``` -use kaui; -show tables; -``` - -Standard SQL commands can be used to explore or manipulate the tables. Be sure you know what you are doing, or the databases may become corrupted! - -To exit the mysql interactive mode, type `exit`. - - -=== Nginx - -The load balancer `nginx` should normally require little attention. The configuration files are located under `/etc/nginx/. The configuration file for `nginx itself is `/etc/nginx/nginx.conf`. Additional configuration files are located under `/etc/nginx/sites-enabled/`. The only file normally present in this directory is `/etc/nginx/sites-enabled/killbill.conf`. This file may need to be edited to enable SSL, as explained above. - -== Upgrades - -From time to time new versions of Kill Bill and KAUI may be released. This section explains how to install these new versions. - -Note: you must switch to the `tomcat` user first in order to upgrade Kill Bill or Kaui (`sudo su - tomcat`). - -The configuration file `/var/lib/killbill/kpm.yml` specifies the Kill Bill version (and its plugins) running on the instance. Once you edit this file to specify the new version number, it will be used automatically. After editing this file, simply run the command `$KPM_INSTALL_KB_CMD`, delete the cached directory `/var/lib/tomcat/webapps/ROOT`, and restart the instance. - -A similar process can be used for KAUI: update `/var/lib/kaui/kpm.yml`, run `$KPM_INSTALL_KAUI_CMD`, delete the cached directory `/var/lib/tomcat/webapps2/ROOT` and restart the instance. diff --git a/userguide/tutorials/aws-singletier.adoc b/userguide/tutorials/aws-singletier.adoc deleted file mode 100644 index c15bf264f..000000000 --- a/userguide/tutorials/aws-singletier.adoc +++ /dev/null @@ -1,271 +0,0 @@ -= Single-Tier Option - - -There are at least three different ways to setup a working Kill Bill system on AWS. Two options are based on a single *Amazon Machine Image (AMI)* containing the complete Kill Bill stack, that is both the Kill Bill server and the administrative UI (KAUI). These options are *single-tier* and *multi-tier*. The single-tier option is designed to deploy a limited version of Kill Bill quickly for trial and experimentation. For production deployments, we recommend the https://docs.killbill.io/latest//aws-multitier.html[multi-tier option.] A third alternative we offer for deploying a production system is https://docs.killbill.io/latest//aws-cf.html[CloudFormation templates]. The multi-tier option requires more setup than CloudFormation, but provides more control over the deployment. - -== Overview - -This document describes the single-tier option. Everything you need for this option is bundled in the AMI and can be launched on a single 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. - -The organization of the single-tier system looks like this: - -image::../assets/aws/single-tier-ami_deployment.svg[width=750,align=center] - -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. - -== 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. - -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. - -=== Setup your EC2 Instance - -==== 1. Subscription - -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: - -image::../assets/aws/single-ami-subscribe.png[align=center] - -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*. - -==== 2. EC2 Configuration - -The next page will give several configuration options. - -image::../assets/aws/single-ami-configure.png[align=center] - -Be sure to select the region you plan to operate in. In most cases you should accept the other 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::../assets/aws/single-ami-launch.png[align=center] - -All other options will disappear. Click *Launch*. - -The next page is headed *Launch an Instance*. Scroll down to the middle of this page, to the box titled *Key Pair (login)* Here you are asked to choose or create a *key pair*. - -image::../assets/aws/single-tier-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. Click *Create 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. - -==== 3. Launch - -When the key pair is generated, click *Launch Instances*. You should see the screen below: - -image::../assets/aws/single-tier-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::../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. - -==== 4. Security Group Setup - -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::../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::../assets/aws/single-ami-inbound-new.png[align=center] - -Your Kill Bill installation is ready to go! - -== Login - -You have setup access to port 22 in your security group. This will allow you to login directly to your instance from a terminal or command window. You may need to do this to perform some configuration and maintenance tasks that will be described below. - -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`. - -You will now be able to explore your instance and perform various configuration and maintenance tasks. To exit from your login, type `exit`. - -== Testing - -You can now try to 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*. If all goes well, this should display the KAUI login screen. The browser may complain that your connection is not secure, but it should offer you a way to bypass the problem. - -For an introduction to KAUI, see our https://docs.killbill.io/latest/userguide_kaui.html[Kaui Guide]. The default credentials are: `admin` / `{EC2 instance ID}`. The first few requests might be a bit slow as Kill Bill initializes itself. - -In addition, you can login to 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. - -Even though access may work as described here, it is not secure. You will probably notice a lock symbol that is crossed out in your URL address bar, and yourr access may be subject to eavesdropping. To fix this, proceed to the next section. - - - -== Adding a Certificate - -In order to make your site secure, you will need to add a valid X.509 SSL/TLS certificate. The easiest way to add this certificate is to make use of 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 creating a certificate using `certbot`, see https://docs.killbill.io/latest/using-https.html[Using HTTPS]. Once your certificate is setup, you can login securely to KAUI using your CNAME as the URL (e.g., https://kaui.mydomain.com). - - -== Configuration - -Kill Bill defines a number of global properties and per-tenant properties that can be varied. These properties are explained in the https://docs.killbill.io/latest/userguide_configuration.html[configuration guide]. Default values for these properties are built into the Kill Bill code; these values can be overridden by values defined in the file `/var/lib/killbill/config/killbill.properties`. For example, this is where you can change the database URL and credentials. - -This file also defines the location of the `shiro.ini` file, which by default is in the same directory. This file defines the Kill Bill admin credentials, along with any other users and their roles. See the https://docs.killbill.io/latest/user_management.html[RBAC guide] for details about this file. - -== Upgrades - -From time to time new versions of Kill Bill and KAUI may be released. This section explains how to upgrade to these new versions. - -First, login to your instance using `ssh`, then switch to the `tomcat` user: - -`sudo su - tomcat` - -The configuration file `/var/lib/killbill/kpm.yml` specifies the Kill Bill version (and its plugins) to be run on the instance. Once you edit this file to specify the new version number, it will be used automatically. Perform the following steps: - -1. Edit the configuration file to update the version number -2. Run the command `$KPM_INSTALL_KB_CMD` -3. Delete the cached directory `/var/lib/tomcat/webapps/ROOT` -4. Restart the instance. - -A similar process can be used for KAUI: update `/var/lib/kaui/kpm.yml`, run `$KPM_INSTALL_KAUI_CMD`, delete the cached directory `/var/lib/tomcat/webapps2/ROOT` and restart the instance. - - - -== Troubleshooting - - - -After launching the EC2 instance, the full stack should come up, with all services enabled and running, including: - -* An `nginx` instance receiving traffic on port `443` and `8443` -* A instance of Kill Bill server listening on `127.0.0.1:8080` (and receiving external traffic through nginx on port `8443`) -* A instance of Kaui listening on `127.0.0.1:3000` (and receiving external traffic through nginx on port `443`) -* A local `mysql` server running on port `3306` - - -In this section, we will provide some tips to verify the operation of the system, and what to do when things are not working. - -If your installation does not seem to work correctly, the first step is to review your installation process carefully, to be sure that everything has been done and checked as described in this document. If problems persist, we will be glad to work with you to identify the problem. To help us to do this, there are several information reports that you may need to gather. These reports are somewhat technical but can be analyzed by Kill Bill personnel. This section explains how to obtain the reports that may be needed. - -=== System Health Check - -The healthcheck report checks the health of various software components, and determines if any queues are growing improperly over time. To create this report, login to your EC2 instance and issue the following command: - -`curl http://127.0.0.1:8080/1.0/healthcheck` - -This will return a series of messages giving the health status of each component. - -=== System Information - -For a detailed system information report, use the following command: - -`curl -u ADMIN:{EC2 instance ID} http://127.0.0.1:8080/1.0/kb/nodesInfo` - -Here ADMIN and {EC2 instance ID} are your KAUI administrator access credentials. - -=== Service Statuses - -This procedure does not produce a report, but does provide important information about the status of each service. - - -The Kill Bill single-tier option is composed of four services. The status of each service can be checked by the following commands: - -* Kill Bill service: `sudo service killbill status` -* KAUI service: `sudo service kaui status` -* Nginx service: `sudo service nginx status` -* Mysql service: `sudo service mysql status` - -For each report there should be a line near the top with the following form: - -`Active: active (running) since Sat 2020-10-24 20:13:43 UTC; 1 day 1h ago` - - -Similarly you can `start` or `stop` the services using similar commands, such as `sudo service kaui stop` to stop KAUI. - - -=== Log Files - -The system maintains a series of logfiles that should be helpful when troubleshooting is needed. - -Tomcat logs are under `/var/lib/tomcat/logs/`: - -* KAUI logs: `/var/lib/tomcat/logs/kaui.out` -* Kill Bill server logs: `/var/lib/tomcat/logs/catalina.out` - -Nginx logs can be found under `/var/log/nginx/` - -* Access logs: `/var/log/nginx/access.log` -* Error logs: `/var/log/nginx/error.log` - -=== Diagnostic Command - -The `diagnostic` option of the `kpm` command creates an extensive report for a given tenant that may be useful for troubleshooting. To run this command: - -``` -# Login as 'tomcat' -> sudo su - tomcat -# -# Run the command with your access credentials: -# -> kpm diagnostic \ - --killbill-credentials=ADMIN {EC2 instance ID} \ - --bundles-dir=/var/lib/killbill/bundles \ - --database-name=killbill \ - --database-credentials=DBUSER DBPASS \ - --killbill-api-credentials=KEY SECRET \ - --kaui-web-path=/var/lib/tomcat/webapps2 \ - --killbill-url=http://127.0.0.1:8080 \ - --database-host=127.0.0.1:3306 -``` - -You will need to edit this command to include: - -1. Your KAUI username and password (ADMIN {EC2 instance ID}) -2. Your database credentials (DBUSER DBPASS) -3. The key and secret key for your tenant (KEY SECRET) - -The last line of the response should look like: - -`Diagnostic data is exported under /tmp/killbill-diagnostics-20200213-23204-u93ah5/killbill-diagnostics-02-13-20.zip` - -The specified zip file contains several reports of various sizes. This report can be downloaded to your computer using `sftp` and forwarded to Kill Bill for analysis. - -=== Databases - -To access the mysql (MariaDB) databases, you can use the following command: - -`mysql -u root -proot` - -This enables interactive access to the database manager. There is one `killbill` and one `kaui` database created and used by the respective applications. To verify the tables in each database, you can type: - -``` -use killbill -show tables; -``` -or - -``` -use kaui -show tables; -``` - -Standard SQL commands can be used to explore or manipulate the tables. Be sure you know what you are doing, or the databases may become corrupted! - -To exit the mysql interactive mode, type `exit`. - - -=== Load Balancer - -The load balancer `nginx` should normally require little attention. The configuration files are located under `/etc/nginx/`. The configuration file for `nginx` itself is `/etc/nginx/nginx.conf`. Additional configuration files are located under `/etc/nginx/sites-enabled/`. The only file normally present in this directory is `/etc/nginx/sites-enabled/killbill.conf`. This file may need to be edited to enable SSL, as explained above. diff --git a/userguide/tutorials/using-https.adoc b/userguide/tutorials/using-https.adoc deleted file mode 100644 index c304a3a11..000000000 --- a/userguide/tutorials/using-https.adoc +++ /dev/null @@ -1,198 +0,0 @@ -= Using HTTPS - -include::{sourcedir}/aws/includes/aws-card.adoc[] - -== Overview - -The HTTP protocol, commonly used for message exchange over the internet, does not provide encryption or authentication. As a result messages exchanged with this protocol may be insecure and subject to eavesdropping, and their source may be uncertain. To avoid this problem, HTTP is frequently combined with an encryption scheme known as SSL, or more recently TLS, that can be used to keep messages safe from unauthorized access, and verify that the sender is who they claim to be. This secure protocol is called HTTPS. - -This document provides information about HTTPS and its setup that applies to all of the AWS Kill Bill architectures. - -HTTPS is based on the use of a verification document called a *certificate*. the certificate serves two purposes: - -1. It provides the keys necessary for a highly secure encryption. -2. It provides the electronic signature of a *certificate authority (CA)* who guarantees the identity of the sender. - -Increasingly, modern browsers require valid certificates when accessing sites using the HTTPS protocol. It may be difficult or impossible to access these sites if a valid certificate is not found. - -The structural details of certificates are defined by international standards and are well beyond the scope of this discussion. For more details see the https://en.wikipedia.org/wiki/X.509[Wikipedia article]. One thing you need to understand, though, is the certificate authority. Normally this is either an organization that is intrinsically well-known and trusted, such as DigiCert or GlobalSign (called a *root* CA), or an organization in the *trust hierarchy* derived from a root. A CA in a trust hierarchy must be itself certified by another CA in a chain which eventually leads to the root CA. Your CA, in turn, must be able to certify that *you* are who you say you are! - -For temporary use, you can sometimes create a *self-signed* certificate, in which you are your own CA. Most browsers will frown on this, since you are simply vouching for yourself, but it may allow you to get started with security. - -If you own a domain, your domain provider can serve as your CA. If you don't have a domain, you can purchase one for very low cost from a domain provider such as Godaddy. When you obtain a domain you need to prove your identity, so your domain provider can trust you. To demonstrate this trust you will need a CNAME. - -== Preliminary concepts - -=== CNAMEs - -A CNAME, or *Canonical Name*, is an identifier that links your CA to the resources that you are protecting with your certificate. You will be protecting public access to your instances of KAUI and Kill Bill through your load balancer, identified by its DNS name. The CNAME will link your domain to the load balancer. If your domain is `mydomain.com` your CNAME might look like `kaui.mydomain.com`. This will direct browsers to your verified domain, and then, through your CNAME, to your AWS resources. - -The CNAME is part of your domain's DNS profile, and your domain provider should have instructions for setting it up. - -=== Protocol and Port Setup - -Your AWS security group by default provides rules giving access to KAUI and Kill Bill using the HTTP protocol and a specified port number. For HTTPS you will need additional rules with the new protocol and a new port number. - -=== Validation - -When you create a new certificate, unless you are acting as your own CA, you will need to validate your certificate. This identifies the trust hierarchy for the certificate. You may need to setup a temporary CNAME for this purpose, and you may need to provide temporary access via an extra port in your security group. - -== Obtaining a Certificate - -There are many ways to obtain a certificate that you can use to protect a particular resource. Here we will describe three that may be of use in particular Kill Bill scenarios running on AWS. These are: - -1. Creating a self-signed certificate -2. Using the AWS Certificate Manager -3. Using the free CA *Let's Encrypt* - -=== Self-Signed Certificates - -The quickest and easiest way to create a certificate is to sign it yourself. In this way you become your own CA. A self-signed certificate should be considered temporary. It will provide encryption, but it cannot prove the identity of your service because you are vouching for yourself. Most browsers will complain or require extra steps to use your system, and some may not allow its use at all. - -Since you are acting as your own CA, a self-signed certificate does not require a CNAME. One simple way to create a self-signed certificate is to use the free command line program `openssl`. This program is usually preloaded in Linux and Macintosh environments, and can be downloaded for Windows. - -First, open your terminal or command application, if necessary, and type `openssl version` to be sure the program is available. If not, you will need to download it first. - -Next, type the following command: - -``` -openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privateKey.key -out certificate.crt -``` -This will bring up a series of questions about your identity, such as name, address, phone, etc. This information becomes a part of your certificate. You can ignore most of these by typing `enter`. Then type: - -``` -openssl rsa -in privateKey.key -text > private.pem -openssl x509 -inform PEM -in certificate.crt > public.pem -``` -This will create two files that are necessary for encryption. - -Finally, follow the instructions for your Kill Bill system type to copy these files to your certificate. When copying private.pem, remove all text prior to "-----BEGIN RSA PRIVATE KEY-----". Then install your certificate in your system. - -== Using the AWS Certificate Manager (ACM) - -The AWS Certificate Manager (ACM) offers a straightforward way to provide SSL/TLS protection for AWS resources such as load balancers. This is most appropriate when using the multi-tier or cloud formation installation options. There is no extra cost for using ACM certificates. - -=== 1. Request a Certificate - -If you are on a page that is asking for your certificate, click on *Request a new Certificate from ACM*. Otherwise, select ACM from the Services menu. You will be taken to the main page of the ACM. Initially this will probably show that you have no certificates. Click *Request a Certificate*. - -The next page will give you the option to import a certificate, or to request a public or private certificate. Choose *private*, then click again on *Request a Certificate*. This will take you to the *Request a Certificate* page. You are initially at *Step 1: Add Domain Names*. - -image::../assets/aws/ELB-request-certificate.png[align=center] - -=== 2. Setup a CNAME - -To validate your certificate, you must first setup a *temporary* CNAME. The values to use for the CNAME will be seen shortly. You will then create the CNAME that you will actually use to access the system. - -Enter your domain name, using the wildcard format. Then click *Next*. On the following page, select *DNS Validation*. The next page gives you the chance to assign one or more tags to your certificate. These are optional and can be skipped. Finally, you are given a chance to review your request. Check everything, then click *Confirm and Request*. The *Validation* page will appear. - -image::../assets/aws/ELB-cert-validation-1.png[align=center] - -At the bottom you will see your domain name with a status of *Pending Validation*. Click the triangle next to your domain name. The display will expand to show the values that you must use to create your validation CNAME. - -image::../assets/aws/ELB-cert-validation-2.png[align=center] - -The two strings labeled *Name* and *Value* should be copied to the two required entries for your CNAME. Copy these long strings carefully. Do not include any trailing periods. There is an option to save these strings in a file so they may be copied more easily, or stored for a later time. - -Your second CNAME is much simpler. The first entry will be `kaui`. The second entry will be simply your domain name, e.g., `mydomain.com`. - -=== 3. Create and Validate your Certificate - -When your CNAMEs are set, return to ACM and click *Continue*. The display changes to show that your certificate is *Pending Validation*. The certificate should now appear also on the main ACM page. When (and if) it is validated, the status will change to *Success*. *This may take several hours or more.* A short time later it will change again to *Issued*. - -When your certificate is successfully created, you may delete the temporary (validation) CNAME. - - -== Using Let's Encrypt (with Certbot) - -`Let's Encrypt` is a root CA that is free to use. Certificates based on `Let's Encrypt` can be created using the application `certbot`. This approach is useful when using a third-party load balancer like `nginx`, which cannot be protected with ACM certificates. `Let's Encrypt` can be used free of charge. - -`Certbot` is pre-installed in the latest Kill Bill AMI, but if you need a different version of `certbot`, this is also available through the new package manager `snap`. This package manager is also preinstalled in the Kill Bill AMI. - -To setup a certificate using `certbot`, perform the following steps. This discussion assumes you are using `nginx`: - -=== 1. Create a CNAME - -Create a CNAME, following instructions from your domain provider. You will be asked to provide two items of information. The first is simply `kaui`. The second is the *Public IPV4 DNS* name for your EC2 instance, for example, `ec2-3-238-230-120.compute-1.amazonaws.com`. Note that the IPV4 address alone will *not* work. - -=== 2. Add your CNAME to the `nginx` configuration file - -This step tells `nginx` to forward HTTPS traffic via your CNAME. - -First, login to your EC2 instance. - -Next, using a text editor of your choosing, edit the file `/etc/nginx/sites-enabled/killbill.conf`. You will need to use `sudo` to edit this file. - -This file contains two server blocks. The second block contains the lines: - -``` -server { - listen 443; - server_name _; -``` -Replace the underscore after `server_name` with your CNAME: - -``` -server { - listen 443; - server_name kaui.mydomain.com; -``` - -Save the modified file, then reload it with the following command: - -`sudo nginx -s reload` - -=== 3. Enable HTTP on port 80 (temporarily) - -Go to your EC2 dashboard and add a new inbound rule to your security group as follows: Type: HTTP, Protocol: TCP, Port Range: 80, Source: 0.0.0.0/0. Your inbound rules should now look like this: - -image::../assets/aws/single-ami-inbound-port-80.png[align=center] - -This is just to allow `certbot` to create your certificate. After the certificate is created, we recommend that you remove this rule to maintain security. - -=== 4. (Optional) Update the `certbot` package - -First, remove the existing `certbot` package by typing the command: - -`sudo apt-get remove certbot` - -When asked if you want to proceed, type `Y` for yes. - -Next, install the latest version of `certbot` using `snap`, and link it to the `/usr/bin` directory: - -``` -sudo snap install --classic certbot -sudo ln -s /snap/bin/certbot /usr/bin/certbot -``` - -=== 5. Create and Install the Certificate - -Run `certbot` using the following command: - -`sudo certbot --nginx` - -Respond to any questions that are asked. If all goes well, you will see a message like: - -``` -IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/deployment.killbill.io/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/deployment.killbill.io/privkey.pem - Your cert will expire on 2021-07-11. To obtain a new or tweaked - version of this certificate in the future, simply run certbot again - with the "certonly" option. To non-interactively renew *all* of - your certificates, run "certbot renew" -``` - -If the message does not appear, review the above steps carefully. If needed you can also try the `certbot` https://certbot.eff.org/help/[help page]. - -== Testing and Renewal - -When your certificate is installed, you should be able to access KAUI from you browser using `https://` followed by your CNAME as the address. The browser should indicate that the site is secure. - -When your certificate is successfully installed, you can edit your security groups again to remove the access through port 80. - -The `Let's Encrypt` certifcates are only valid 90 days and will therefore neeed to be renewed. `certbot` will create a cron entry under `/etc/cron.d/certbot` to make this process automatic. - -The ACM certificates will renew automatically.