Welcome to a new post from the WSO2 ESB section! In this tutorial you will learn step by step how to install the Docker container in WSO2 ESB.
Introduction
On this occasion, we are going to display the examples using a container: Docker. This is one of the most widely used by WSO2 on their servers. A way to work much smarter and cleaner, unlike installing everything in the local environment. Also with this tool, we can virtualize networks where you can deploy different WSO2 containers.
The idea is to download from WSO2 a container with the Enterprise Integrator (ESB included). To do this first of all we must install Docker Common Edition. In this example, we are going to use Ubuntu as a platform for the installation.
As for the configuration of the ESB included in the EI, we will learn how to handle errors with defined sequences in attribute onError of a sequence where the client sends a message to backend through the ESB (within EI). Three use cases are tested: when the mediation is successful, when it is not successful and there is no error managed and when the error is managed when the message is being processed.
Installing Ubuntu Docker CE
Install Docker through the repository
Before installing Docker CE for the first time on a new host machine, you must configure the repository of Docker. Afterwards, you can now install and update Docker from the repository.
-
SET THE REPOSITORY
1.Update apt index package:
2. Install packet to allow apt to use a repository over HTTPS:
3. Add the official Docker key GPG:
4. Verify that you have the key with the fingerprint 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88, looking the last 8 characters of the fingerprint:
5. You can use the following command to configure the stable repository. Always needed, even if you want to install compilations from the edge or test repositories well. To add the edge or test repository, you have to add the word edge or test (or both) after the word stable as you can see on the following screenshot.
-
INSTALL DOCKER CE
1. Update the index of the package apt.
2. Install the latest version of Docker CE.
3. Verify Docker CE has been installed correctly running the hello-world image.
This command downloads a test image and executes it in a container. At the moment the container is executed, an informational message is printed. Now Docker CE is installed and working!
To see the image that was downloaded by Docker:
To see the container that was created to execute the image:
When executing a container if its name is not specified, Docker generates a random name by default.
Now it’s time to download the Enterprise Integrator container from WSO2.
Installing the Enterprise Integrator container
Download and execution
For this, we must go to the official Docker repository of WSO2, where we found a list of containers.
We chose WSO2-EI Enterprise Integrator and click on Details.
On the next screen appears the command line to be used to download the Container and a list of tags with the different versions of the EI. We will use the latest version.
For this, we first must log in to the WSO2 Docker repository using the credentials we have on the WSO2 website. If you do not have credentials you must create an account on that website.
Now you must download the container of the EI:
$ docker pull docker.wso2.com/wso2ei-integrator:latest
If you want to see the image of the EI, type: $ docker image ls
Now we execute the image in a Container, for that you must type:
$ docker run – d -p 8280: 8280 -p 8243: 8243 -p 9443: 9443 –name wso2ei docker.wso2.com/wso2ei-integrator:latest
The format is: docker run -d <port_mapping> –name <container_name> <image_name >
-d: means detached mode.
Parameters and port mapping
Docker publishes or maps the ports as follows: port-of-host: port-of-container, in our example: -p 8280: 8280
That is, the requests that are directed to port 8280 on the Host, Docker redirects them to 8280 in the container.
Access to the EI console and important Docker commands.
Now you can go to the administration console in the browser: https: // localhost: 9443 / carbon
The details of the containers that are running appear with this command:
$ sudo docker container ls
As you can see it appears information about the identifier of the container, the image that the container executes, the command that executes WSO2 server in the container, when the container was created, its status (if it is running or is stopped), the mapping of the ports and the name of the container. If we did not used a name for the container Docker choose one at random.
To stop the container: $ docker container stop <container_name>
If you want to see the list of containers you can see that the status has now changed, it is: Existed.
$ docker container ls -a
To start the container again: $ docker container restart <container_name>
Note: If the container runs again with the command run, another container is created equal to the first one.
To connect with the container where the EI is running it is as simple as typing:
$ docker container exec -it wso2ei bash
-it: means, [i] nteractive, Assigns a pseudo-TTY,
[t] tty, keeps STDIN open even if it is not connected.
The connection to the command line of the container where the EI is running is done with this command:
$ docker container exec -it <container_name> bash
To open a shell as root: $ docker exec -u 0 -it <container_name> bash
From here you can access the EI to create the sequences through the browser or the command line to send the requests inside the container.
The configuration of the ESB
In the configuration of the ESB, a primary sequence is used to process the incoming messages from the Customer service. Depending on the value of the symbol tag of the request message, the message is sent to a different endpoint.
The first endpoint, when the symbol is IBM, works correctly. The second endpoint is not defined in the ESB, therefore an error is generated and the default error sequence called ‘fault’ is executed. The third endpoint, which is not defined either, sends the message to a sequence from which errors are handled this time through the sequence ‘sun ErrorHandler’.
How it works
The following diagram shows how the ESB configuration works:
Testing the configuration.
From the AXIS2 client, three sample requests are sent to test the behavior of Synaps error handling.
-
Use case 1: Defined endpoint.
$ ant stockquote -Daddurl = http: // localhost: 9000 / services / SimpleStockQuoteService -Dtrpurl = http: // localhost: 8280 / -Dsymbol = IBM
Request sent by the Client:
In the request, you can check that the value of the tag symbol it’s IBM. The value matches the value of the regular expression of the first case on the ESB sequence. Therefore, the message is sent to the endpoint SimpleTockQuoteService.
The answer of the backend is the following one:
And the value that the client visualizes is: 87.5990
-
Use case 2: End point and error management not defined.
$ ant stockquote -Daddurl = http: // localhost: 9000 / services / SimpleStockQuoteService -Dtrpurl = http: // localhost: 8280 / -Dsymbol = MSFT
Request sent by the Client:
In this case, the symbol by which the last quote is searched is MSFT.
The drawback is that the endpoint for that value is not correctly configured in the EI and an error occurs. The ESB is not able to find the end point!
Since there is no error sequence defined for the sequence that processes the request of the selected symbol, sequence principal, the default error sequence is executed which is closest to the sequence where the error occurred. The server EI displays the error message in its log file and destroys the message.
-
Use case 3: Undefined endpoint and error management defined.
$ ant stockquote -Daddurl = http: // localhost: 9000 / services / SimpleStockQuoteService -Dtrpurl = http: // localhost: 8280 / -Dsymbol = SUN
Request sent by the Client:
In this request, the endpoint is not defined, but it is defined as the sequence that manages the error is. In this case, it is the sunErrorHandler.
The error message displayed by the middleware is:
Conclusion
Server virtualization is something that the integration developer must learn and know very well. It is the best way to virtualize the behavior of servers in a real environment where there are different machines spread across different networks and thus have a virtual environment as close to reality.
In this way, it facilitates the resolution of problems without complications, since it gives us the possibility of replicating the use case in the environment in which an error has appeared, this time with the containers in a virtual environment. As you have been able to verify, Docker gives us that facility, being much less heavy than VirtualBox since Docker does not need a guest OS (Guest OS) where it can run, only the Docker engine.
The following diagram shows a comparison between virtual machines and Docker.
You should know that containers are only processes, limited to what resources they can access and exist when the process stops.
Before finalizing it is essential to emphasize that EI makes possible the management of errors with the option of writing sequences that manage them. In this way, it is much easier to keep track of the problems that arise in middleware or backends.
Now that you know how to handle errors and how Docker can become the best container (and ally!) there is no time to waste to implement all the tips learned in this WSO2 Tutorial. If you need a little help in your beginnings, contact our consultants will give you the best advice.
If you liked this post do not forget to take a look at the last tutorial: WSO2 ESB Tutorial: Entries in the local registry, reusable endpoints, and sequences, you will also find it as enriching as this one! See you in the following blog.
