Skip to content

Commit

Permalink
Merge pull request #501 from vnandwana/patch-7
Browse files Browse the repository at this point in the history 
Update how-to-set-up-a-multi-tier-system.adoc
  • Loading branch information
@sbrossie
sbrossie authored Aug 11, 2023
2 parents 7c65e0a + f80be35 commit ff2f1bf
Showing 1 changed file with 119 additions and 106 deletions.
225 changes: 119 additions & 106 deletions userguide/aws/how-to-set-up-a-multi-tier-system.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,55 +78,125 @@ image::../assets/aws/multitier-connectivity-and-security.png[align=center]

=== 2.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.
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.

[NOTE]
====
The current security configuration allows open access to the database from any IP address, which can pose significant security risks. Exposing a database to the public internet without proper restrictions is generally not recommended as it may lead to potential vulnerabilities and make your data susceptible to attacks.
To ensure robust protection, it is essential to promptly update the database security settings after completing the Multi-Tier setup. We recommend restricting access so that only EC2 instances running Kill Bill and Kaui are permitted to connect to the database.
====

[[step3]]
== Step 3: Edit the Configuration Script
== Step 3: Create the Databases

Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases.

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:
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 required for this command are the same ones you set up for the database in step 2.1 above.

Note that the host <DB-Endpoint-Writer-Instance> should *not* include the port number and there is no space after `-h` and `-u` options.

The password will not be echoed when it is typed.

[source,bash]
----
#!/bin/bash
> mysql -h<DB-Endpoint-Writer-Instance> -u<DB-Username> -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`

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
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:

[source,bash]
----
sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP
put killbill.ddl
put kaui.ddl
exit
----

First, you need to edit the database properties. <DB-INSTANCE-NAME> should be replaced by the full name of the DB endpoint, as given in the *Connectivity and Security* panel (see above). The port number 3306 is required. <ADMIN-NAME> and <PASSWORD> should be set to the administrator credentials you have chosen for the RDS instance.
Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas:

[source,bash]
----
> mysql -h<DB-Endpoint-Writer-Instance> -u<DB-Username> -p<DB-Password> < killbill.ddl
> mysql -h<DB-Endpoint-Writer-Instance> -u<DB-Username> -p<DB-Password> < kaui.ddl
----
To ensure that the databases are setup correctly, login to `mysql` again, then try the SHOW TABLES command:

[source,bash]
----
> mysql -h<DB-Endpoint-Writer-Instance> -u<DB-Username> -p<DB-Password>
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].
use killbill;
show tables;
use kaui;
show tables;
exit
----

Save this script in a text file. You will need it in the next step.
Each `show tables` command should display a list of table names for the database.

[[step4]]
== Step 4: Launch EC2 Instances
== Step 4: Edit the Configuration Script

To configure the EC2 instances and establish their connection to the databases, you'll need to provide essential information. Fortunately, Kill Bill and Kaui are equipped to read environment variables, making the setup more straightforward. For your convenience, we have a concise configuration script available to streamline this process. Below is the template for the script:


[source,bash]
----
#!/bin/bash
db_host="<DB endpoint writer instance>"
db_port="<DB port>"
db_user="<DB username>"
db_password="<DB passwordd>"
kb_admin_password="<Kaui admin login password>"
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
KB_org_killbill_billing_osgi_dao_url=jdbc:mysql://$db_host:$db_port/killbill
KB_org_killbill_billing_osgi_dao_user=$db_user
KB_org_killbill_billing_osgi_dao_password=$db_password
KB_ADMIN_PASSWORD=$kb_admin_password
KAUI_DB_ADAPTER=mysql2
KAUI_DB_URL=jdbc:mysql://$db_host:$db_port/kaui
KAUI_DB_USERNAME=$db_user
KAUI_DB_PASSWORD=$db_password
KAUI_KILLBILL_URL=http://127.0.0.1:8080
EOF
----

In the above script, replace the value of `db_host` with the full name of the DB writer endpoint obtained from the Connectivity and Security panel, as indicated earlier. Be sure to specify the appropriate database port number (`3306` for MySQL or `5432` for PostgreSQL) by setting `db_port`. The `kb_admin_password` value will be utilized as the admin password for Kaui login.

Optionally, you may choose to customize other Kill Bill properties based on your specific needs. For more detailed information on available configuration options, please refer to the documentation provided at: https://docs.killbill.io/latest/userguide_configuration.html.

[NOTE]
====
The Kaui properties present in the provided template are required for proper functioning. Missing any of these properties may prevent the Kill Bill service from starting successfully. Ensure to set all the necessary properties correctly to ensure a smooth setup process.
====

Save this script to a file as it will be necessary during the launch of EC2 instances.

[[step5]]
== Step 5: Launch EC2 Instances

The next step is to launch the number of EC2 instances you want, all based on the Kill Bill single AMI.


=== 4.1. Subscribe to the AMI
=== 5.1. Subscribe to the AMI

To start the installation process, point your browser to the
+++
Expand All @@ -145,7 +215,7 @@ Click *Continue to Subscribe*. The next page will give the AWS Terms and Conditi
Accept the terms if asked. You will then see a new message confirming that you have subscribed. Next, click *Continue to Configuration*.
=== 4.2. Configure the Instances
=== 5.2. Configure the Instances
The next page will give several configuration options:
Expand All @@ -169,22 +239,7 @@ 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 the very bottom of this list is a box headed *User Settings*. Copy your configuration file into this box.
=== 4.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 all instances* 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.4. Setup Security Rules
=== 5.3. 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:
Expand All @@ -203,79 +258,37 @@ Your Inbound Rules should now look like this:
image::../assets/aws/multitier-inbound-new.png[align=center]
=== 5.4. Add user data script
Finally, scroll to the bottom and open the section labeled *Advanced Details*. You will see a long list of settings. At the very bottom of this list is a box headed *User data*. Paste the script created in Step 4 here.
=== 4.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`.
=== 5.5. Launch your Instances
NOTE: We recommend that you *remove* the SSH rule from your security group when you are *not* doing configuration or maintenance.
When the key pair is generated, click *Launch Instances*. You should see the screen below:
image::../assets/aws/multitier-launching.png[align=center]
[[step5]]
== Step 5: Create the Databases
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 all instances* at the bottom right. This will take you to the *Instances* screen which is part of the EC2 Dashboard.
Kill Bill requires two databases, with the names `killbill` and `kaui`. We provide predefined schemas for these databases.
image::../assets/aws/multitier-instances.png[align=center]
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.
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.
[source,bash]
----
> 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:
=== 5.6. Login to an Instance
* killbill schema: `https://docs.killbill.io/latest/ddl.sql`
* kaui schema: `https://github.com/killbill/killbill-admin-ui/blob/master/db/ddl.sql`
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:
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:
`ssh -i <PRIVATE_KEY>.pem ubuntu@<INSTANCE_IP>`
[source,bash]
----
sftp -i PRIVATE_KEY.pem ubuntu@INSTANCE_IP
put killbill.ddl
put kaui.ddl
exit
----
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.
Once the files are successfully uploaded, login again to your instance using the `ssh` command. You can now install the schemas:
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.
[source,bash]
----
> 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:
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`.
[source,bash]
----
> mysql -h DB-INSTANCE-NAME -u ADMIN-NAME -p
Enter Password:
use killbill
show tables;
use kaui
show tables;
exit
----
You will now be able to explore your instance and perform various configuration and maintenance tasks. To exit from your login, type `exit`.
Each `show tables` command should display a list of table names for the database.
NOTE: We recommend that you *remove* the SSH rule from your security group when you are *not* doing configuration or maintenance.
[[step6]]
== Step 6: Perform Initial Testing
Expand Down

0 comments on commit ff2f1bf

Please sign in to comment.