Run the Bank and Stock-Trading Application

3 Run the Bank and Stock-Trading Application

Learn how to use MicroTx to maintain data consistency across several microservices by deploying and running the Bank and Stock-Trading application.

Caution:

The instructions provided in this section are specific to test or development environments. Do not use these instructions to set up and use MicroTx in production environments.

The Bank and Stock-Trading application contains several microservices and it uses distributed, two-phase commit transaction (XA). Run the Bank and Stock-Trading application to purchase and sell stocks as well as transfer money from one account to another. When you run the Bank and Stock-Trading application, you will be able to see how MicroTx ensures consistency of transactions across the distributed microservices and their resource managers. You will also integrate MicroTx with the Kubernetes ecosystem by using tools, such as Kiali and Jaeger, to visualize the flow of requests between MicroTx and the microservices.

Running a sample application is the fastest way for you to get familiar with MicroTx.

Topics:

About the Bank and Stock-Trading Application
The Bank and Stock-Trading application demonstrates how you can develop microservices that participate in a distributed transaction while using MicroTx to coordinate the requests. You can use the application to withdraw or deposit an amount, as well as buy and sell stocks. Since financial applications that move funds require strong global consistency, the application uses XA transaction protocol.
Configure Minikube and Start a Tunnel
Configure Minikube and then start a tunnel between Minikube and the Kubernetes cluster.
Configure Keycloak
The Bank and Stock-Trading Application console uses Keycloak to authenticate users.
Verify that All the Resources are Ready
Redeploy the Bank and Stock-Trading application, and then ensure that are the resources are available.
Transfer Funds with the Bank and Stock-Trading Application
Run the Bank and Stock-Trading application to transfer funds and to understand how you can use Transaction Manager for Microservices (MicroTx) to coordinate XA transactions. After running the application, use distributed tracing to understand how the requests flow between MicroTx and the microservices. Running sample applications is the fastest way for you to get familiar with MicroTx.
Trade Stocks with the Bank and Stock-Trading Application
Run the Bank and Stock-Trading application to purchase and sell stocks and to understand how you can use Transaction Manager for Microservices (MicroTx) to coordinate XA transactions. After running the application, use distributed tracing to understand how the requests flow between MicroTx and the microservices. Running sample applications is the fastest way for you to get familiar with MicroTx.
Deploy Kiali and Jaeger (Optional)
Optionally, you can use Kiali and Jaeger to track and trace distributed transactions in MicroTx through visualization. Use distributed tracing to track how requests flow between MicroTx and the microservices.
View Service Mesh graph and Distributed Traces (Optional)
To visualize what happens behind the scenes and how a request processed by the distributed services and MicroTx, you can use the Kiali and Jaeger Dashboards that you started in the previous task.

3.1 About the Bank and Stock-Trading Application

The Bank and Stock-Trading application demonstrates how you can develop microservices that participate in a distributed transaction while using MicroTx to coordinate the requests. You can use the application to withdraw or deposit an amount, as well as buy and sell stocks. Since financial applications that move funds require strong global consistency, the application uses XA transaction protocol.

The following figure shows the various microservices in the Bank and Stock-Trading application. Some microservices connect to an Autonomous Transaction Processing Serverless (ATP-S) instance or resource manager. Resource managers manage stateful resources such as databases, queuing or messaging systems, and caches.

Microservices in Bank and Stock-Trading application

When a user purchases stocks using the Stock Broker service, the application withdraws money from the Core Banking Service and deposits an equivalent number of stocks by creating an XA transaction. Within the XA transaction, all actions such as purchase, sale, withdraw, and deposit either succeed, or they all are rolled back in case of a failure of any one or more actions.

Participant microservices use the MicroTx client libraries which registers callbacks and provides implementation of the callbacks for the resource manager. As shown in the image, MicroTx communicates with the resource managers to commit or roll back the transaction. MicroTx connects with each resource manager involved in the transaction to prepare, commit, or rollback the transaction. The participant service provides the credentials to the coordinator to access the resource manager. The Stock Broker, Core Banking, Branch Banking, and User Banking microservices are based on Spring Boot 3.x. The MicroTx Spring Boot starter client library files, which are available for Spring REST apps, are already integrated with all the microservices.

During a transaction, each microservice also makes updates to a resource manager to track the change in the amount and stocks. When you run the Bank and Stock-Trading application, you will be able to see how MicroTx ensures consistency of transactions across the distributed microservices and their resource managers.

The MicroTx coordinator manages transactions amongst the participant services.
The Stock Broker microservice initiates the transactions, so it is called a transaction initiator service. The user interacts with this microservice to buy and sell shares. When a new request is created, the helper method that is exposed in the MicroTx library runs the begin() method to start the transaction. This microservice also contains the business logic to issue the commit and roll back calls. After initiating the transaction, the Stock Broker service also participates in the transaction. After starting a transaction to buy or sell shares, the Stock Broker service also participates in the transaction to deposit or withdraw the shares from a user's account. It uses resources from the Stock Broker Service ATP instance.
The Core Banking, Branch Banking, and User Banking services participate in the transactions related to the trade in stocks, so they are called participant services. They do not initiate the transaction to buy or sell stocks. The MicroTx library includes headers that enable the participant services to automatically enlist in the transaction. These microservices expose REST APIs to get the account balance and to withdraw or deposit money from a specified account. Core Banking and Branch Banking services also use resources from the Banking Service and Branch Banking Service ATP instances respectively.

The service must meet ACID requirements, so withdraw amount, transfer amount, deposit stocks, sell stocks, debit amount, or credit amount are called in the context of an XA transaction.

Parent topic: Run the Bank and Stock-Trading Application

3.2 Configure Minikube and Start a Tunnel

Configure Minikube and then start a tunnel between Minikube and the Kubernetes cluster.

Before you begin, ensure that can access the Transaction Manager for Microservices instance that have created in OCI using the Transaction Manager for Microservices image for OCI. See Create an Instance.

If you have connected to your instance as an opc user through an SSH terminal using auto-generated SSH Keys, then you must switch to the oracle user before you begin.
```
sudo su - oracle
```
At the command prompt, run the following command to start Minikube.
```
minikube start
```
Run the following command in a new terminal to start a tunnel between Minikube and the Kubernetes cluster. Keep this terminal window open.
```
minikube tunnel
```
Enter the password to access your local machine if you are prompted to enter your password.
In a new terminal, run the following command to note down the external IP address of the Istio ingress gateway.
```
kubectl get svc istio-ingressgateway -n istio-system
```
From the output note down the value of EXTERNAL-IP, which is the external IP address of the Istio ingress gateway. You will provide this value in the next step. If the EXTERNAL-IP is in the pending state, ensure that the Minikube tunnel is running before proceeding with the next steps.
Example output
Let's consider that the external IP in the above example is 192.0.2.117.
Store the external IP address of the Istio ingress gateway in an environment variable named CLUSTER_IPADDR as shown in the following command.
```
export CLUSTER_IPADDR=192.0.2.117
```
Note that, if you don't do this, then you must explicitly specify the IP address in the commands when required.

When you start Minikube, all the service pods start running. When Minikube starts, it also starts the Database service.

Parent topic: Run the Bank and Stock-Trading Application

3.3 Configure Keycloak

The Bank and Stock-Trading Application console uses Keycloak to authenticate users.

Run the following command to note down the external IP address and port to access Keycloak.
```
kubectl get svc -n keycloak
```
From the output note down the value of EXTERNAL-IP and PORT(S), which is the external IP address and port of Keycloak. You will provide this value later.
Let's consider that the external IP in the above example is 198.51.100.1 and the port is 8080.
Run the following command to run the reconfigure-keycloak.sh script from the $HOME directory.
```
cd $HOME    
sh reconfigure-keycloak.sh
```
Sign in to Keycloak. In a browser, enter the IP address and port number that you have copied in a previous step. The following example provides sample values. Provide the values based on your environment.
```
http://198.51.100.1:8080
```
This command configures Keycloak and updates the settings to suit the requirements of the application.
Click Administration Console.
Sign in to Keycloak with the initial administrator user name admin and password admin.
After logging in, we strongly recommend that you reset the password for the admin user. For information about resetting the password, see the Keycloak documentation.
Select the MicroTx-BankApp realm, and then click Users to view the list of users in the MicroTx-BankApp realm. The MicroTx-BankApp realm is preconfigured with these default user names.
Set the password for each user. For information about providing credentials for users, see the Keycloak documentation.

Parent topic: Run the Bank and Stock-Trading Application

3.4 Verify that All the Resources are Ready

Redeploy the Bank and Stock-Trading application, and then ensure that are the resources are available.

Run the reconfigure-bankapp.sh script from the HOME directory to set the values by required by the application's Helm Chart.
```
$ cd $HOME
$ sh reconfigure-bankapp.sh
```
The Helm Chart is updated with the required values, and then the Bank and Stock-Trading application is redeployed using the latest values.
Verify that the Bank and Stock-Trading application has been redeployed successfully.
```
helm list -n otmm
```
Example output
In the output, verify that the STATUS of the bankapp is deployed.
Verify that all resources, such as pods and services, are ready. Run the following command to retrieve the list of resources in the namespace otmm and their status.
```
kubectl get pods -n otmm
```
Example output
Verify that the database instance is running. The database instance is available in the oracledb namespace. Run the following command to retrieve the list of resources in the oracledb namespace and their status.
```
kubectl get pods -n oracledb
```
Example output
It usually takes some time for the Database services to start running in the Minikube environment. Proceed with the remaining tasks only after ensuring that all the resources, including the database service, are ready and in the RUNNING status and the value of the READY field is 1/1.

Parent topic: Run the Bank and Stock-Trading Application

3.5 Transfer Funds with the Bank and Stock-Trading Application

Run the Bank and Stock-Trading application to transfer funds and to understand how you can use Transaction Manager for Microservices (MicroTx) to coordinate XA transactions. After running the application, use distributed tracing to understand how the requests flow between MicroTx and the microservices. Running sample applications is the fastest way for you to get familiar with MicroTx.

When you send a request to transfer funds, the Core Banking service and Branch Banking service interact with each other to perform this task. The Core Banking service in turns sends the debit amount request to the Branch Banking service. Once the amount is successfully debited from the specified bank account, it is credited to another bank account. The microservices use the XA protocol and MicroTx to manage the transactions. Within an XA transaction, all actions such as debit amount and credit amount either succeed, or all actions are rolled back in case of a failure of any one or more actions.

Fund transfer happens between the branches. In this sample application, we have only one branch (Arizona), so the Core banking and Branch banking microservices interact with each other.

To transfer funds:

Access the bank application. In a browser, type 192.0.2.117/bankapp, where 192.0.2.117 is the external IP address of the Istio ingress gateway which you have noted down earlier after starting a Minikube tunnel.
The Keycloak login page is displayed.
Enter the username and password to access the Keycloak instance. Enter the password that you had provided earlier for the preconfigured Keycloak users.
The Bank and Stock-Trading application's console is displayed as shown in the following figure.
Click the Bank tab, and then click Summary.

The account summary is displayed as shown in the following image. Note down the account balance.
Click Fund Transfer, and then click Transfer Funds.
The Transfer Funds dialog box appears.
In the Transfer Funds dialog box, enter the following details.
1. Select the name or the account to which you want to transfer the amount.
2. Enter the amount that you want to transfer.
3. (Optional.) Enter remarks, if any, regarding the transfer.
4. Click Confirmation, and then review the details of the transfer.
5. Click Confirm to transfer the amount.
  After the application withdraws the specified amount from account 10001 and deposits the amount in account 10002, the Transaction ID and Result are displayed on the screen.
6. Click Close to close the Transfer Funds dialog box.
Click Summary to view the updated balance in the account summary.

The following image shows that the amount has reduced by 500, the amount that you have transferred.
Click Statement to view the transaction statement as shown in the image below.

Parent topic: Run the Bank and Stock-Trading Application

3.6 Trade Stocks with the Bank and Stock-Trading Application

Run the Bank and Stock-Trading application to purchase and sell stocks and to understand how you can use Transaction Manager for Microservices (MicroTx) to coordinate XA transactions. After running the application, use distributed tracing to understand how the requests flow between MicroTx and the microservices. Running sample applications is the fastest way for you to get familiar with MicroTx.

When you send a request to purchase stocks, the Stock Broker service debits the required amount from the Core Banking service. The Core Banking service in turns sends the debit amount request to the Branch Banking service. Once the amount is successfully debited from your bank account, the Stock Broker service purchases the stocks and deposits the purchased stocks into your account. The microservices use the XA protocol and MicroTx to manage the transactions. Within an XA transaction, all actions such as debit amount and deposit stocks either succeed, or all actions are rolled back in case of a failure of any one or more actions.

To purchase stocks:

Access the bank application. In a browser, type 192.0.2.117/bankapp, where 192.0.2.117 is the external IP address of the Istio ingress gateway which you have noted down earlier after starting a Minikube tunnel.
The Keycloak login page is displayed.
Enter the username and password to access the Keycloak instance. Enter the password that you had provided earlier for the preconfigured Keycloak users.
The Bank and Stock-Trading application's console is displayed as shown in the following figure.
Click the Bank tab, and then click Summary.

The account summary is displayed as shown in the following image. Note down the account balance.
Click the Trading tab.

The Stock Trading page is displayed. Identify the stock that you want to purchase and the number of units of the stock that are currently available in your account. For example, let's consider that you want to purchase shares of the Blue Semiconductor. The following image shows that you have 10 shares of Blue Semiconductor.
Click Buy Stocks, and then click Buy Stocks.
In the Purchase Stocks dialog box, enter the following details.
1. Select the stock that you want to purchase.
2. Enter the number of units of the stock that you want to purchase.
3. (Optional.) Enter remarks, if any, regarding your purchase.
4. Click Confirmation, and then review the details of the purchase.
5. Click Confirm to purchase the stocks.
  After the Stock Broker service purchases the stocks and deposits it in your account, the Transaction ID and Result are displayed on the screen.
6. Click Close to close the Purchase Stocks dialog box.
Click Stocks to view the updated list of stocks.

The following image shows the number of shares of Blue Semiconductor has increased by 5, the purchased amount, in your account.
Click Statement to view the transaction statement as shown in the image below.
Click the Bank tab, and then click Summary.

The account summary is displayed as shown in the following image. Note that the account balance has reduced as the Stock Broker service debits the amount required to purchase the shares from your account.

Parent topic: Run the Bank and Stock-Trading Application

3.7 Deploy Kiali and Jaeger (Optional)

Optionally, you can use Kiali and Jaeger to track and trace distributed transactions in MicroTx through visualization. Use distributed tracing to track how requests flow between MicroTx and the microservices.

Run the following commands to deploy Kiali and Jaeger in a Minikube cluster.

Deploy Kiali.

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/kiali.yaml

Deploy Prometheus. To use Kiali, you must deploy Prometheus and Kiali in the same cluster.

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/prometheus.yaml

Deploy Jaeger.

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/jaeger.yaml

Start the Kiali Dashboard. Run the following command in a new terminal. Ensure that you leave this terminal open. If a new browser opens, close the browser.
```
istioctl dashboard kiali
```
From the output, note down the URL. This is the URL on which you can access the Kiali dashboard in a browser. For example, http://localhost:20001/kiali.
Start the Jaeger Dashboard. Run the following command in a new terminal. Ensure that you leave this terminal open. If a new browser opens, close the browser.
```
istioctl dashboard jaeger
```
From the output, note down the URL. This is the URL on which you can access the Jaeger dashboard in a browser. For example, http://localhost:16686.

Parent topic: Run the Bank and Stock-Trading Application

3.8 View Service Mesh graph and Distributed Traces (Optional)

To visualize what happens behind the scenes and how a request processed by the distributed services and MicroTx, you can use the Kiali and Jaeger Dashboards that you started in the previous task.

Perform this task only if you have deployed Kiali and Jaeger in your cluster.

Open a new browser tab and navigate to the Kiali dashboard URL. For example, http://localhost:20001/kiali.
Select Graph for the otmm namespace.
Open the Jaeger dashboard URL in a new browser. For example, http://localhost:16686.
In the Service drop-down list, select istio-ingressgateway. A list of traces is displayed where each trace represents a request.
Select a trace to view it.

Parent topic: Run the Bank and Stock-Trading Application