A Hands-on Guide: Building and Deploying Containerized web application with ZK and AWS Lightsail

{{Template:Smalltalk_Author|
|author=Hawk Chen, Engineer, Potix Corporation
|date= May. 31, 2023
|version=ZK 10FL}}

__TOC__

= Overview =
In this article, I will delve into the process of building and deploying a cloud-based web application using the ZK 10 and AWS Lightsail. ZK 10, currently under development, introduces an exciting feature, stateless components, designed to aid developers in creating efficient, cloud-based web applications. This makes enhancing scalability, high availability, resource management, and auto-provisioning much easier.

This article will cover stateless components' basics, configuration, and usage. We will also guide you through the steps of deploying your application using Docker containers on AWS Lightsail.

= Basic Concept of Stateless Components =
== The Differences Between Stateless and Stateful Components ==
ZK is a server-centric framework, and the standard UI components we have been offering are stateful(ZK 9 and before). Every UI component produces a Java object and a JavaScript widget that maintain their state in synchrony. The desktop and its component tree are stored in an HTTP session. This model, while powerful, required memory on the server to maintain the state of each Java object.

However, with the advent of ZK 10, a new type of component is introduced: the stateless component. In contrast to standard components, stateless components do not have a corresponding Java object keeping their state and no persistent desktop. Instead, only JavaScript widgets maintain the state of the UI. This means ZK no longer requires requests in the same session to be sent to the same server. They can be processed from any clustered node so that you can fully leverage cloud resources in a more dynamic and resilient manner and achieve autoscaling and high availability much easier. Another significant advantage of this architecture is that stateless components do not consume server memory, as no Java objects hold their state. 

The screenshot below demonstrates that no component (Java) objects are created when using stateless components:

'''Heap dump in VisualVM'''
[[File:noComponentObject.png | center]]

= Configure Dispatcher Richlet Filter =
To start working with stateless components, you'll need to configure the <code>DispatcherRichletFilter</code> in your <code>web.xml</code> file. The DispatcherRichletFilter is a core role in handling requests in ZK 10. It maps incoming HTTP requests to methods in a <code>StatelessRichlet</code> that are annotated with the <code>@RichletMapping</code>, based on the URL pattern defined in the annotation.

Here is a basic configuration of the DispatcherRichletFilter:

<source lang="xml">
<filter>
		<filter-name>DispatcherRichletFilter</filter-name>
		<filter-class>org.zkoss.stateless.ui.http.DispatcherRichletFilter</filter-class>
		<init-param>
			<param-name>basePackages</param-name>
			<param-value>org.zkoss.stateless.demo</param-value>
		</init-param>
		<init-param>
			<param-name>cloudMode</param-name>
			<param-value>true</param-value>
		</init-param>
</filter>
<filter-mapping>
		<filter-name>DispatcherRichletFilter</filter-name>
		<url-pattern>/*</url-pattern>
</filter-mapping>
</source>
* The <code>basePackages</code> parameter in the configuration specifies the packages that the filter should scan for <code>@RichletMapping</code>. This is a required parameter that you should specify according to your conditions.


= Building UI with Stateless Components=
In ZK 10, to build a UI with stateless components, one needs to create a class that implements the <code>StatelessRichlet</code> interface and designates its access URL. This can be done using the <code>@RichletMapping</code> on both the class and method to define the access URL by concatenating class and method annotation values:
 [CLASS_VALUE][METHOD_VALUE]

<source lang="java">
@RichletMapping("/shoppingCart")
public class ShoppingCartRichlet implements StatelessRichlet {

	@RichletMapping("")
	public List<IComponent> index() {
		//... your code here
	}
</source>
Based on the code above, the access URL is <code>/shoppingcart</code>

The new stateless component API introduces a fluent API style, where each class begins with an uppercase "I", indicating "Immutable". Below is an example of how to build a UI with this new API.


<source lang="java">
	@RichletMapping("")
	public List<IComponent> index() {
		return asList(
			IStyle.ofSrc(DEMO_CSS),
			IVlayout.of(
				renderShoppingBag(),
				Boilerplate.ORDER_TEMPLATE
			)
		);
	}
	private IVlayout renderShoppingBag() {
		final String orderId = Helper.nextUuid();
		return IVlayout.of(
			ILabel.of("Shopping Cart").withSclass("title"),
			renderOrderButtons(orderId),
			IGrid.ofId("shoppingBag").withHflex("1")
				.withEmptyMessage("please add items.")
				.withColumns(Boilerplate.SHOPPING_BAG_COLUMN_TEMPLATE)
				.withRows(renderShoppingBagItems(orderId))
				)
		.withSclass("shoppingBag");
	}
</source>
* <code>of()</code> is used to append child components 
* <code>withAttr()</code> is used to set a component's attributes. For example, withId() is used to set the ID of the component.

= Action Handling =
In the new ZK 10's stateless component model, the traditional "event listeners" from ZK 9 are replaced with "action handlers". You can set an action handler with the <code>withAction()</code> , such as <code>IButton.of("add item +").withAction(this::addItem)</code>.

To make a method an action handler, you apply the <code>@Action</code> with an event type to listen to. An example is shown below:

<source lang="java">
	@Action(type = Events.ON_CLICK)
	public void addItem() {
		//... your code here
	}
</source>
In the code snippet above, the <code>@Action(type = Events.ON_CLICK)</code>  denotes that the method addItem() is an action handler for the ON_CLICK event type. When a click event occurs, this addItem() method will be invoked to handle the action.


= Obtain Component State =

Given the stateless nature of ZK 10's components, obtaining the component's state from the server using a getter is no longer possible. Instead, you need to obtain the states from a browser. ZK 10 provides the <code>@ActionVariable</code> to access component states sent from a browser.

<source lang="java">
@Action(type = Events.ON_CLICK)
public void addItem(@ActionVariable(targetId = ActionTarget.SELF, field = "id") String id) {
		// your code here
}
</source>

* <code>ActionTarget.SELF</code> refers to the event target, which in this case is the “add item” button. This could also be <code>ActionTarget.PARENT</code>, <code>ActionTarget.FIRST_CHILD</code>, <code>ActionTarget.LAST_CHILD</code>, and so forth.

Here is another example:
<source lang="java">
@Action(type = Events.ON_CHANGE)
public void changeQuantity(Self self,
			   InputData quantityData,
			   @ActionVariable(targetId = ActionTarget.NEXT_SIBLING) Integer price,
			   @ActionVariable(targetId = ActionTarget.PARENT, field = "id") String id) {
	// your code here
}
</source>

* <code>self</code> refers to the locator of the component itself 
* <code>quantityData</code> represents input data caused by a user's input something at the client.

= Update Component State =

Since the server no longer holds components in ZK 10, a <code>UiAgent</code> is used to control the client-side widgets and allow them to update themselves.

<source lang="java">
	@Action(type = Events.ON_CLICK)
	public void deleteItem(Self self, @ActionVariable(targetId = ActionTarget.PARENT, field = "id") String id) {
		orderService.delete(parseItemId(id));
		UiAgent.getCurrent().remove(Locator.ofId(id));
		// your code here
	}
</source>

* The <code>Locator.ofId()</code> function returns a locator to the given ID of an `IComponent`. This is used to specify the component to be removed by the `UiAgent`.

= Deploying the App =
Now that we have a simple web application created using ZK 10 stateless components, we can either deploy it to a standalone web server just like we used to do or deploy it to a cloud environment so that we can fully leverage the flexible scaling and auto-provisioning features.

You are free to choose the cloud platform you wish to deploy your app to. In this article, we will take AWS Lightsail as an example to demonstrate how the process is done. 

= AWS Lightsail Getting Started =

Amazon Web Services Lightsail is a simple yet powerful platform that allows you to build, deploy, and manage your web applications effortlessly. It's designed to be easy to use, and it's ideal for beginners who want to quickly get a project off the ground. For a more detailed introduction and guide to using Lightsail, I recommend referencing the official AWS tutorial: "[https://aws.amazon.com/getting-started/hands-on/deploy-docker-containers/|Deploy a Container Web App on Amazon Lightsail]".

Common uses for Lightsail include:

* Web Application Hosting
* Dev/Test Environments
* Microservices
* Content Delivery and Media Serving


== Install the AWS CLI ==

To interact with AWS services, you'll need the AWS Command Line Interface (CLI) installed on your local machine. Follow the official [https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html|installation instructions] provided to get started.

== Configure AWS CLI Credentials ==

After installing the AWS CLI, the next step is to configure your credentials. This will allow the CLI to authenticate your requests to AWS. Again, follow the official [https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds-create|AWS guide] to set up your credentials. Details will not be covered here as the AWS guide provides comprehensive instructions.

== Prepare Docker Image ==
To get your web application running on Lightsail, you'll need to package it as a Docker image. We assume you have Docker Desktop installed on your machine and are familiar with basic Docker commands. In this guide, our Dockerfile will be based on <code>openjdk:8-jdk</code>, and we'll also install <code>postgresql-12</code> and Tomcat 8 to run the war file.

== Steps to run a container service ==
# Create a Container Service
# Push a Local Image
# Deploy That Image to the Container Service

== Create a Container Service ==

An Amazon Lightsail container service is a compute resource where you can deploy your Docker images. Think of your Lightsail container service as a computing environment that allows you to run containers on AWS infrastructure using images that you create.

To get started with Lightsail container services, you will need to install the AWS CLI Lightsail Extension. Follow the official [https://lightsail.aws.amazon.com/ls/docs/en_us/articles/amazon-lightsail-install-software|installation instructions] provided by Amazon. 

A container service is comprised of compute nodes, a TLS certificate, a DNS domain name, and an optional load balancer. For simplicity, a shell script named <code>create-container.sh</code> is provided to create a container service. After executing the script, wait for a while until the container service's status changes to READY.

[[File:Container.png|center]]

== Push a Local Image ==

Amazon Lightsail supports the deployment of containers from various public container image repositories, such as Docker Hub, Amazon ECR Public Gallery, and even your local machine.

To begin, build a Docker image using <code>docker-build.sh</code>. You can then test the Docker image locally by running <code>docker-up.sh</code>. To push the image from your local machine to Lightsail, execute <code>push-container.sh</code>. The pushed image, in this case, named 'shoppingcart', will be stored on Amazon Lightsail and can be verified under the "Image" tab in your container service.

[[File:ContainerImages.png|center]]

== Deploy That Image to the Container Service ==

After the image is pushed, it needs to be deployed to the container service to run. This can be achieved by executing the script <code>deploy-container.sh</code> or through the Lightsail console.

Once the deployment process is complete and the container service's status changes to RUNNING, you can visit the public domain assigned to your service to access the application.

[[File:Deployment.png|center]]

== Change Capacity to Serve More Requests==
After deploying to a container service, we can easily add running nodes to serve more users(requests). Lightsail does not natively support auto-scaling features like other AWS services, such as EC2 or Fargate. But you can change capacity manually:
[[File:ChangeCapacity.png|center]]

You can change 
* The power of each node
* The number of each node

(surely that increasing power costs more money)

I send 100 requests in 5 seconds with Jmeter to the application running in 1 node and 3 nodes, you can see the response time is obviously shorter for 3 nodes:
{| class="wikitable"
! # of Nodes
! # of HTTP Requests
! Average Response Time
! Min
! Max
! Std. Dev.

|-
| 1
| 100
| 3632
| 517
| 6417
| 1737.77
|-
| 3
| 100
| 1407
| 219
| 3138
| 724.16
|}


=== Identifying Individual Nodes with a Unique Application ID ===
After creating 3 nodes, each time you visit the public URL, you might be directed to one of the nodes. Normally, you can't differentiate these 3 nodes. If I generate an application ID and show it on a page, you can find that each page reloading might take you to a different node.

[[File:3nodes.png|center]]

== Troubleshooting ==

===Deployment failed for exec format error ===

==== ⁉️ Error in the server log ====

<code>exec /docker-entrypoint.sh: exec format error</code>

This error usually indicates that the file you're trying to execute is not in the correct format. In this case, it could mean that the entry point script you're trying to run in the Docker image (/docker-entrypoint.sh) is not in the correct format for the underlying system architecture.

==== Solution ====

Make sure the Docker image you're using is compatible with the system architecture of the Fargate cluster. If you're using a 64-bit Ubuntu 18.04 image, for example, the architecture should be x86_64.

Modify Dockerfile:

<code>
FROM amd64/nginx:1.23.3
</code>

=== ⁉️ Exec format error ===

==== Error in the server log ====

<syntaxhighlight lang='text'>
[16/May/2023:08:37:49] [deployment:1] Creating your deployment
[16/May/2023:08:38:18] exec /start.sh: exec format error
[16/May/2023:08:39:28] [deployment:1] Started 1 new node
…
[16/May/2023:10:36:54] [deployment:2] Took too long
</syntaxhighlight>

==== Root Cause ====

PostgreSQL is also architecture dependent.

==== Solution ====

Specify PostgreSQL with amd64 architecture:

<code>RUN echo "deb [arch=amd64] http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" > /etc/apt/sources.list.d/pgdg.list</code>

=== ⁉️ Health checks failed: port 8080 is unhealthy ===

==== Error in the server log ====

<code>
[17/May/2023:07:51:30] [deployment:7] Health checks failed: port 8080 is unhealthy
</code>

==== Root cause ====

The default health check timeout of 2s is too short for my application.

==== Solution ====

Increase the timeout and interval and redeploy. Change the setting to 10s via the Lightsail console.

= Source Code=
[https://github.com/zkoss-demo/zk10-shopping-cart-demo/tree/aws check the source code]

{{Template:CommentedSmalltalk_Footer_new|
|name=Potix Corporation
}}

[[Category:Small Talk]]