Merge branch 'killbill:v3' into v3

userguide/aws/how-to-set-up-a-multi-tier-system.adoc

@@ -160,7 +160,7 @@ db_user="<DB username>"
 db_password="<DB passwordd>"
 kb_admin_password="<Kaui admin login password>"
 
-cat << EOF > /etc/environment
+cat << EOF >> /etc/environment
 KB_org_killbill_dao_url=jdbc:mysql://$db_host:$db_port/killbill
 KB_org_killbill_dao_user=$db_user
 KB_org_killbill_dao_password=$db_password

userguide/getting-started/includes/docker.adoc

@@ -52,7 +52,7 @@ volumes:
   db:
 services:
   killbill:
-    image: killbill/killbill:0.24.9
+    image: killbill/killbill:0.24.10
     ports:
       - "8080:8080"
     environment:
@@ -61,7 +61,7 @@ services:
       - KILLBILL_DAO_PASSWORD=killbill
       - KILLBILL_CATALOG_URI=SpyCarAdvanced.xml
   kaui:
-    image: killbill/kaui:3.0.6
+    image: killbill/kaui:3.0.9
     ports:
       - "9090:8080"
     environment:

userguide/getting-started/includes/tomcat.adoc

@@ -126,7 +126,7 @@ As mentioned above, you need to configure the Kill Bill database manually. For t
 
 The next step is to configure Kill Bill. For this, you need to follow the steps given below:
 
-. Download the current stable version of the Kill Bill war  from https://search.maven.org/search?q=a:killbill-profiles-killbill[Maven Central] (Ensure that you download the `killbill-profiles-killbill-X.Y.Z.war` file and not the `jetty-console.war`, `jar-with-dependencies.war` or `jar-with-dependencies-sources.war`) 
+. Download the current stable version of the Kill Bill war  from https://central.sonatype.com/artifact/org.kill-bill.billing/killbill-profiles-killbill/versions[Maven Central] (Ensure that you download the `killbill-profiles-killbill-X.Y.Z.war` file and not the `jetty-console.war`, `jar-with-dependencies.war` or `jar-with-dependencies-sources.war`)
 
 . Rename the `killbill-profiles-killbill-X.Y.Z.war` to `ROOT.war` (Ensure that *ROOT* is in uppercase)
 
@@ -195,7 +195,7 @@ You should have a database called *kaui* (Or whatever name you have specified in
 
 Finally, Kaui needs to be configured. For this, you need to follow the steps given below:
 
-. Download the current stable version ( V 2.0.11 ) of the Kaui war from https://search.maven.org/search?q=a:kaui-standalone[Maven Central]. 
+. Download the current stable version ( V 3.0.9 ) of the Kaui war from https://central.sonatype.com/artifact/org.kill-bill.billing.kaui/kaui-standalone/versions[Maven Central].
 
 . Rename the downloaded `war` to `ROOT.war` (Ensure that *ROOT* is in uppercase)
 

userguide/tutorials/debugging.adoc

@@ -90,7 +90,7 @@ volumes:
   db:
 services:
   killbill:
-    image: killbill/killbill:0.24.0
+    image: killbill/killbill:0.24.10
     ports:
       - "8080:8080"
       - 12345:12345
@@ -102,7 +102,7 @@ services:
       - KILLBILL_CATALOG_URI=SpyCarAdvanced.xml
       - KB_org_killbill_server_test_mode=true
   kaui:
-    image: killbill/kaui:2.0.11
+    image: killbill/kaui:3.0.9
     ports:
       - "9090:8080"
     environment:

userguide/tutorials/email-notification-plugin.adoc

@@ -1,13 +1,15 @@
 = Email Notification Plugin 
 
-As the name implies, the https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin.
+As the name implies, the https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin, with support for both SMTP and AWS SES for sending email notifications.
 
 == Prerequisites
 
 * Ensure that you have Kill Bill, Kaui, and the database set up as explained in the https://docs.killbill.io/latest/getting_started.html[__Getting Started Guide__].
 
 * Ensure that you have https://curl.haxx.se/[_cURL_] installed. If you are on Windows, we recommend that you use https://git-scm.com/download/win[_Git Bash_] to run the `cURL` commands.
 
+* If you plan to use AWS SES, obtain your AWS SES credentials (access key and secret key) and ensure that the IAM user has the `ses:SendEmail` permission.
+
 == Overview 
 
 The https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a https://docs.killbill.io/latest/notification_plugin.html[notification plugin]. It listens to https://docs.killbill.io/latest/kill_bill_events.html[Kill Bill Events] and sends emails accordingly.
@@ -61,12 +63,36 @@ The email-notification-plugin requires some additional database tables. To creat
 [[plugin_configuration]]
 == Plugin Configuration
 
-In order to use the email notification plugin, a tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.
+In order to use the email notification plugin, you need to configure either SMTP or AWS SES settings. Below are the steps to configure both:
+
+=== AWS SES Configuration
+To enable AWS SES for email notifications, add the following properties into `killbill.properties`. The default sender's email must be verified in AWS SES.
+
+[source,bash]
+org.killbill.email.notification.via.ses=true
+org.killbill.mail.from=<Default sender's email>
+org.killbill.aws.region=<AWS region, default region is us-east-1>
+
+AWS SES requires authentication for sending emails. System-wide environment variables can be configured for all users by appending them to the `/etc/environment` file. Open the `/etc/environment` file in a text editor with root privileges, set the following variables:
+
+[source,bash]
+AWS_ACCESS_KEY_ID=<AWS access key ID>
+AWS_SECRET_ACCESS_KEY=<AWS access secret>
+
 
-The tenant/account configuration can be done by executing the required API endpoints via *cURL* as explained below:
+Reboot the system to apply the changes.
+
+
+[NOTE]
+*Note:* Ensure that the credentials used have the necessary permissions, specifically `ses:SendEmail`, on the resource arn:aws:ses:<region>:<account>:identity/<sender's email>.
+
+=== SMTP Configuration
+A tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.
+
+The tenant configuration can be done by executing the required API endpoints via *cURL* as explained below:
 
 [[tenant-config]]
-. *Configure the tenant* using the following cURL command (Replace `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS`):
+*Configure the tenant* using the following cURL command (Replace `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS`):
 [source,bash]
 curl -v \
      -X POST \
@@ -85,29 +111,24 @@ org.killbill.billing.plugin.email-notifications.smtp.useSSL=false
 org.killbill.billing.plugin.email-notifications.smtp.sendHTMLEmail=true
 org.killbill.billing.plugin.email-notifications.smtp.defaultSender=xxx@yyy.com' \
 http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
-+
+
 [NOTE]
 *Note:* On Windows systems, multiline `cURL` commands like the one above do not run property when `cURL` is used on the standard windows command prompt. So, we recommend using either https://git-scm.com/download/win[_Git Bash_] or https://www.postman.com/[_Postman_] as explained https://docs.killbill.io/latest/postman.html[_here_].
-+
-. *Configure the account* using the following `cURL` command (Replace `{accountId}` with the id of the account for which emails need to be sent and `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `"INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"`):
-[source,bash]
-curl -v \
-     -X POST \
-     -u admin:password \
-     -H 'X-Killbill-ApiKey: bob' \
-     -H 'X-Killbill-ApiSecret: lazar' \
-     -H 'X-Killbill-CreatedBy: admin' \
-     -H 'Content-Type: application/json' \
-     -d '[<events>]' \
-    http://127.0.0.1:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
-   
-. Note that either the *tenant* or the *account* should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:
 
-.. If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.
+[[smtp_server_notes]]
+=== SMTP Server Notes
+
+In order to be able to use the email notification plugin to send emails, a local SMTP server is required.
 
-.. If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.
 
-.. If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.
+
+We typically use the `namshi/smtp` docker image as follows to start a local SMTP server on port 25:
+
+[source, bash]
+docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp
+
+Alternatively, if you would like to use a non-docker based SMTP server, you can use https://www.mailslurper.com/[_MailSlurper_]. MailSlurper is a small handy SMTP server that can be useful for development and testing. It can be downloaded and configured as explained in its https://github.com/mailslurper/mailslurper/wiki/Getting-Started[_documentation_].
+
 
 [[account_configuration]]
 == Account Configuration
@@ -129,27 +150,32 @@ curl -v \
     -d '{ "name": "John Doe", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
 "http://127.0.0.1:8080/1.0/kb/accounts"
 
+=== Configure Events
+*Configure the account* using the following `cURL` command (Replace `{accountId}` with the id of the account for which emails need to be sent and `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `"INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"`):
+[source,bash]
+curl -v \
+     -X POST \
+     -u admin:password \
+     -H 'X-Killbill-ApiKey: bob' \
+     -H 'X-Killbill-ApiSecret: lazar' \
+     -H 'X-Killbill-CreatedBy: admin' \
+     -H 'Content-Type: application/json' \
+     -d '[<events>]' \
+    http://127.0.0.1:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
 
-[[smtp_server_notes]]
-== SMTP Server Notes
-
-In order to be able to use the email notification plugin to send emails, a local SMTP server is required. 
-
-
-
-We typically use the `namshi/smtp` docker image as follows to start a local SMTP server on port 25:
+Note that either the *tenant* or the *account* should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:
 
-[source, bash]
-docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp
+.. If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.
 
-Alternatively, if you would like to use a non-docker based SMTP server, you can use https://www.mailslurper.com/[_MailSlurper_]. MailSlurper is a small handy SMTP server that can be useful for development and testing. It can be downloaded and configured as explained in its https://github.com/mailslurper/mailslurper/wiki/Getting-Started[_documentation_].
+.. If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.
 
+.. If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.
 
 == Testing the Plugin
 
 Once the plugin is installed and configured as explained above, it can be used for sending emails. You can verify that the plugin is working correctly by following the steps given below:
 
-. Start a local SMTP server as explained in the <<smtp_server_notes, "SMTP Server Notes">> section.
+. If you're using SMTP, start a local SMTP server as explained in the <<smtp_server_notes, "SMTP Server Notes">> section. Otherwise, if you're using AWS SES, make sure it's configured as explained in the <<plugin_configuration, "Plugin Configuration">> section.
 
 . Ensure that Kill Bill is running either in https://docs.killbill.io/latest/development.html#_running_the_application[_standalone_] mode or in https://docs.killbill.io/latest/getting_started.html[_Tomcat_].
 
@@ -166,8 +192,6 @@ curl -v \
     -d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
     "http://127.0.0.1:8080/1.0/kb/tenants"
 
-. Configure the tenant as specified in the <<tenant-config, "Plugin Configuration">> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.
-
 . Create an account as follows (Replace `<email_id>` with the email id where you would like to receive the email and change values for the other fields as required):
 [source, bash]
 curl -v \
@@ -185,6 +209,8 @@ curl -v \
 
 . If successful, the command above returns a `Location` header like \http://127.0.0.1:8080/1.0/kb/accounts/eda3e357-20a1-456d-a9b3-b39ca3db8020. Copy the `account_id` in the header (`eda3e357-20a1-456d-a9b3-b39ca3db8020` in this case) and save it for future use.
 
+. If you're using SMTP, configure the tenant as specified in the <<tenant-config, "Plugin Configuration">> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.
+
 . Add a payment method as follows (replace `<account_id>` with the account id obtained above):
 [source, bash]
 curl -v \

userguide/tutorials/events-to-aws-sqs.adoc

@@ -0,0 +1,120 @@
+= Configuring Kill Bill to Send Events to AWS SQS
+
+== Overview
+
+This document outlines the steps to configure the Kill Bill application to send events to an Amazon Simple Queue Service (SQS) queue.
+
+Kill Bill generates different events when various actions occur within the system. For more details, refer to the link:kill_bill_events.adoc[Kill Bill events] documentation.
+
+
+== Prerequisites
+
+* Access to AWS Management Console.
+* IAM permissions to create and manage SQS and IAM roles.
+* SSH access to the EC2 instance running Kill Bill.
+
+== Configuration Steps
+
+=== Step 1: Create an SQS Queue
+
+1. In the AWS Management Console, search for `SQS` (Simple Queue Service).
+
+2. Under the *Get started* section, click on *Create queue*.
+
+3. Choose the type of queue:
+   * **Standard**: At-least-once delivery, message ordering isn't preserved.
+   * **FIFO**: First-in-first-out delivery, message ordering is preserved.
+
+4. Enter a name for the queue.
+
+5. Adjust any configurations as per your requirements.
+
+6. Click on *Create queue*.
+
+=== Step 2: Create an IAM Role
+
+1. In the AWS Management Console, navigate to the `IAM` (Identity and Access Management) service.
+
+2. Click on *Roles* in the sidebar.
+
+3. Click on *Create role*.
+
+4. Choose the *AWS service* type and select *EC2* as the service that will use this role.
+
+5. Click on *Next: Permissions*.
+
+6. Attach the following policy to allow sending messages to SQS:
+
+[source]
+----
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": "sqs:SendMessage",
+        "Resource": "arn:aws:sqs:{REGION}:{ACCOUNT_ID}:{QUEUE_NAME}"
+      }
+    ]
+  }
+----
+
+7. Click on *Next: Tags*, add any tags if needed, and then click on *Next: Review*.
+
+8. Enter a name for the role and click on *Create role*.
+
+=== Step 3: Attach the IAM Role to the EC2 Instance
+
+1. Navigate to the EC2 Dashboard in the AWS Management Console.
+
+2. Select the EC2 instance where Kill Bill is running.
+
+3. Click on *Actions*, then *Security*, and choose *Modify IAM role*.
+
+4. Select the IAM role created in Step 2 from the dropdown menu.
+
+5. Click on *Update IAM role*.
+
+=== Step 4: Configure Kill Bill to Use SQS
+
+1. SSH to the EC2 instance running Kill Bill.
+
+2. Edit the `/var/lib/tomcat/bin/setenv2.sh` file to include the following properties. Be sure to replace `queueName` with the name of your SQS queue and adjust `maxRetries` if necessary:
+
+[source]
+----
+-Dcom.killbill.aws.enableSqsEvents=true
+-Dcom.killbill.aws.sqs.queueName=<queue-name>
+-Dcom.killbill.aws.sqs.maxRetries=5
+----
+
+=== Step 5: Restart the Kill Bill EC2 Instance
+
+Restart the EC2 instance to apply the changes:
+
+[source]
+----
+sudo reboot
+----
+
+=== Step 6: Test the Configuration
+
+1. To test the setup, install any plugin, add a user, or make tenant configuration changes in Kill Bill. These actions should generate events that will be sent to the SQS queue.
+
+2. Check the SQS dashboard to see if the events are received. Here is a sample event that might be sent to SQS:
+
+[source]
+----
+  {
+    "objectId": "af64be18-a334-4f42-8f07-b2cdc93861a6",
+    "objectType": "TENANT_KVS",
+    "eventType": "TENANT_CONFIG_CHANGE",
+    "accountId": null,
+    "tenantId": "4effbb8c-1c40-4051-871a-613ff6e954cb",
+    "metaData": "{\"key\":\"CATALOG\"}"
+  }
+----
+
+== Conclusion
+
+By following these steps, you can configure Kill Bill to send events to an AWS SQS queue, enabling better event-driven integrations and workflows.

userguide/tutorials/faq.adoc

@@ -49,4 +49,6 @@ Specifying definite environment requirements is tricky because it depends on the
 
 == How can I listen to Kill Bill events?
 
-You can either write a custom plugin (all Kill Bill events are visible to plugins) or register an endpoint that Kill Bill will send events to via HTTP POST (check our https://docs.killbill.io/latest/push_notifications.html[push notifications] documentation).
+You can either write a custom plugin (all Kill Bill events are visible to plugins) or register an endpoint that Kill Bill will send events to via HTTP POST (check our https://docs.killbill.io/latest/push_notifications.html[push notifications] documentation).
+
+Kill Bill now supports sending events to Amazon SQS. To configure Kill Bill to use Amazon SQS for receiving events, refer to link:events-to-aws-sqs.adoc[this] guide.

userguide/tutorials/metrics-cloudwatch.adoc

@@ -53,18 +53,6 @@ After editing the file, go to your AWS EC2 dashboard and *reboot the
 instance* so the new configuration file will be read. If you have more
 than one instance, follow the same procedure for each one.
 
-== Install the X-Ray daemon
-
-AWS X-Ray is a service that collects and analyzes data from your applications. A daemon is a process that runs in the background to do a job whenever it is needed. The X-Ray daemon uploads application metrics to X-Ray in batches to be processed. X-Ray then forwards this data to CloudWatch for display.
-
-To setup the daemon, log in to your EC2 instance and run the following commands:
-
-```
-curl https://s3.dualstack.us-east-1.amazonaws.com/aws-xray-assets.us-east-1/xray-daemon/aws-xray-daemon-3.x.deb -o /home/ubuntu/xray.deb
-sudo dpkg -i /home/ubuntu/xray.deb
-```
-
-If you have more than one instance, repeat these commands on each one.
 
 == Create an IAM Policy