WSO2 Products Dockerized: An Introduction

Over the past few years, there has been a real buzz in the IT industry about Docker. Now WSO2, the world’s #1 open source integration vendor, provides official Docker images for its products. This write up brings forward a simple, practical introduction to WSO2 provided product Docker images.

WSO2 products Dockerized

Before I kick start, lemme highlight what you will learn through this write up. After reading this article, you will know

• What WSO2 product Docker images are
• Available options to obtain WSO2 product Docker images
• How to use WSO2 product Docker images

And please bear in mind that I have avoided re-inventing the wheel, where possible in this write up. This means that I have directed you to already existing online resources which you can refer to, at suitable junctures.

Currently, WSO2 offers a platform of middleware products for

• Enterprise Integration
• API Management
• Identity and Access Management (IAM)
• Analytics and Stream Processing

For these products, Docker images are available which are created and maintained by WSO2.

What are WSO2 Docker images?

A WSO2 created and curated Docker image allows a user to deploy a particular WSO2 product profile on the Docker container runtime.

What is a WSO2 product profile?

A WSO2 product profile is an aggregation of WSO2 Carbon Features which are designed to perform a particular task.

Let’s consider WSO2 Enterprise Integrator (EI), which is a combination of multiple runtimes in which each runtime stands for a particular product profile. For example, Business Process profile of WSO2 EI enables developers to easily deploy long-running integration processes (business processes).

For further details on each WSO2 EI profile, please refer the official documentation.

If we consider WSO2 EI as an example, a Docker image has been made available for each runtime, which product EI is a combination of.

At the time of writing this article, the only exception to this design of WSO2 Docker images can be experienced with WSO2 API Manager (which is a combination of product profiles namely, Gateway, Key Manager, Publisher, Store and Traffic Manager). WSO2 provides a single Docker image, which is for All In One WSO2 API Manager (which starts all the aforementioned product profiles of API Manager, together).

Currently, WSO2 Docker images cover the following product profiles:

WSO2 product profiles supported by Docker images

But wait… what is Docker?

Docker is an open-source project for automating the deployment of applications as portable, self-sufficient containers that can run on the cloud or on-premises [1].

Hang on… what on earth is a container?

Before you proceed with this practical guide, I suggest you to watch the following, cracking video in order to understand the basics of containerization and of course, Docker (many thanks to Dilan Ariyaratne for pointing me to this video!!!).

What is a Container? by VMware Cloud-Native

What options do you have to obtain WSO2 product Docker images?

• Docker images created and curated by WSO2 at Docker Hub

Now, WSO2 created and curated Docker images are available for use at Docker Hub, the world’s largest library and community for container images.

But, please note that every WSO2 product profile Docker image from Docker Hub is packaged with the open source (General Availability — GA) release version of the corresponding WSO2 product. In other words, these images package WSO2 product distributions without WSO2 updates.

WSO2 organizational profile at Docker Hub

Now, you may wonder from where you could obtain Docker images which package WSO2 product distributions with WSO2 updates.

• Docker images available at WSO2’s Private Docker Registry

Enter WSO2’s Private Docker Registry… This Private Docker Registry hosted by WSO2 stores Docker images, which package WSO2 product distributions with WSO2 updates.

In order to use the Docker images available through this WSO2 hosted Docker registry, you will need an active WSO2 Subscription. You can sign up for a Free Trial Subscription from here.

WSO2 Private Docker Registry

Wait… what’s a Docker Registry?

A Docker registry acts as a storage for Docker images.

If you watched the previously recommended video, you may already have an idea of the role played by a Docker registry. To learn more about Docker registries, please refer to this informative guide.

• Docker images created manually from Docker resource source code available at GitHub for WSO2 products

The other option is to manually build the desired product profile’s Docker image, using the Docker resource source code available at GitHub.

WSO2 products and the respective GitHub repositories of Docker resources are as follows:

— Enterprise Integration: https://github.com/wso2/docker-ei

— API Management: https://github.com/wso2/docker-apim

— IAM: https://github.com/wso2/docker-is

— Analytics and Stream Processing: https://github.com/wso2/docker-sp

Instructions for building the Docker image for a desired product profile have been clearly stated using documentation provided under the relevant product profile.

For example, if you intend to create an Ubuntu based Docker image for All In One WSO2 API Manager, please refer to the appropriate documentation.

Pause… an Ubuntu based Docker image? Are there any other supported Operating System (OS) platforms too?

Yes, you read it correctly. At the time of this write up, WSO2 has provided Docker resources for each WSO2 product profile for building its Alpine, CentOS and Ubuntu based Docker image versions.

For example if you consider the WSO2 API Manager, the following Docker resources are available.

— Alpine based: https://github.com/wso2/docker-apim/tree/master/dockerfiles/alpine/apim

— CentOS based: https://github.com/wso2/docker-apim/tree/master/dockerfiles/centos/apim

— Ubuntu based: https://github.com/wso2/docker-apim/tree/master/dockerfiles/ubuntu/apim

Now, this may also raise questions on how WSO2’s product Docker image tagging works out. But I don’t intend to discuss that topic within this write up and I do expect to cover that in a future post.

For now, please consider the fact that the Docker images I have referred to in the following Try It Out section, are Ubuntu based.

Try It Out

This section brings forward a practical guide on using WSO2 product Docker images, which are available through WSO2’s Private Docker Registry and Docker Hub.

Prerequisites

• Install Docker.

You may install the Docker Community Edition (CE) since, it is ideal for developers who are getting started with the Docker platform.

Refer the official documentation to install the Docker CE choosing the desired OS platform.

Using Docker images available at WSO2’s Private Docker Registry

In this section, we’ll attempt to run WSO2 API Manager version 2.6.0 in a Docker container using the WSO2 API Manager All In One Docker image available at WSO2’s Private Docker Registry.

You can follow these steps to achieve this.

• Login to WSO2’s Private Docker Registry

docker login docker.wso2.com

Here, you will be prompted for your WSO2 Subscription credentials. If your login succeeds, you will get a Login Succeeded message.

• [Optional] Pull the WSO2 API Manager All In One Docker image from WSO2’s Private Docker Registry

docker pull docker.wso2.com/wso2am:2.6.0

This step is optional as the next step would perform the same task of checking the availability of the specified Docker image within the local image cache of the Docker host (and pulling the image if unavailable), prior to creating and running the Docker container.

Once the Docker image is successfully pulled, you can check its availability within the local image cache using,

docker images

WSO2 API Manager Docker image pull from WSO2’s Private Docker Registry

• Run a Docker container instance using the Docker image pulled in the previous step

docker run --name wso2am --rm -it \
-p 9443:9443 docker.wso2.com/wso2am:2.6.0

WSO2 API Manager container startup

• Access API Manager’s Carbon management console, Publisher and Store

Carbon management console: https://localhost:9443/carbon

Publisher: https://localhost:9443/publisher

Store: https://localhost:9443/store

So… what really happened?

The following is a concise diagram which depicts the underlying tasks which were carried out by the involved parties, when you executed the above steps.

Flow of events when running a WSO2 API Manager Docker container using the Docker image available at WSO2’s Private Docker Registry

Event 1 — Attempt to login to WSO2’s Private Docker Registry.

The user attempts to login to WSO2’s Private Docker Registry using the Docker client.

docker login docker.wso2.com

Event 2 — The registry client (Docker daemon, in this case) makes a request to the authorization service for a Bearer Token.

Event 3 — The authorization service returns an opaque Bearer Token representing the client’s authorized access.

Event 4 — Pull the WSO2 API Manager Docker image from WSO2’s Private Docker Registry.

docker pull docker.wso2.com/wso2am:2.6.0

This command will initially check if the specified Docker image is available within the local image cache of the Docker host (the specified image will not be available within your local image cache unless you had pulled the image prior to following this write up!!!).

If unavailable in the local cache, the registry client proceeds with events 5, 6 and 7.

Event 5 — The registry client attempts the Docker image pull action with the Bearer Token embedded in the request’s Authorization header.

Event 6 — The registry authorizes the client by validating the Bearer Token and the claim set embedded within it and begins the pull session.

For detailed analysis of the authorization process for WSO2’s Private Docker Registry, please check out this awesome article [2].

Event 7 — The pulled Docker image layers will be stored in the local Docker image cache of the Docker host.

Event 8 — Run a Docker container instance using the pulled Docker image.

The user attempts to run a Docker container instance using the Docker image pulled in event 4, by issuing the following command using the Docker client.

docker run --name wso2am --rm -it \
-p 9443:9443 docker.wso2.com/wso2am:2.6.0

This Docker daemon will initially check if the specified Docker image docker.wso2.com/wso2am:2.6.0 is available within the local image cache of the Docker host.

If unavailable (especially, if you had avoided the optional event 4 as suggested in the Using Docker images available at WSO2’s Private Docker Registry section), the registry client proceeds with events 5, 6 and 7.

Once the image is pulled, the Docker daemon will create and startup a Docker container named wso2am (--name argument) using the pulled image, available within the local image cache.

But what do the other command arguments truly mean?

• Publishing container ports

The Dockerfile of a WSO2 product profile exposes a set of ports which are the ports used by that particular product profile (using the EXPOSE command). For example, the set of ports exposed for All In One WSO2 API Manager can be found from here.

But an exposed port in the Dockerfile will not map to any port of the Docker host. You will need to know the container’s private IP address to access the exposed services.

You can capture the private IP address using the following command:

docker inspect --format '{{ .NetworkSettings.IPAddress }}' wso2am

Once you capture the private IP address of the container, you can access the API Manager’s management console from within the Docker host as follows:

https://<PRIVATE_CONTAINER_IP>:9443/carbon

In order to map a particular container port to a desired port of the Docker host, you need to publish the container port to the desired port in the Docker host.

In the discussed example, it is requested to map port 9443 (HTTPS servlet transport) of the API Manager container instance to Docker host port 9443, using --publish or -p argument.

Once you execute the discussed command, you can access the API Manager’s management console using https://localhost:9443/carbon.

In order to map the another product profile port to a desired Docker host port, you may add a --publish argument entry to the Docker run command in the following form:

-p <HOST_PORT>:<CONTAINER_PORT>

If needed to publish, all the ports exposed within the Dockerfile to random Docker host ports, you may use --publish-all or -P argument.

• Running interactive containers

Here, Docker has bound the output of the main process running within the container- WSO2 Carbon server, to the terminal. Thus, the process can interact with the users, as if WSO2 Carbon server process runs in foreground mode. This has been achieved through a combination of following arguments,

— --interactive or -i : requests Docker to keep the standard input stream (stdin) open for the container even if no terminal is attached

— --tty or -t : requests Docker to attach a virtual terminal for the container, allowing users to pass signals to the container

If you intend to run the Docker container in background, you can use the --detach or -d argument as follows:

docker run --name wso2am --rm -d \
-p 9443:9443 docker.wso2.com/wso2am:2.6.0

This will print out the Docker container ID as depicted below:

Docker container run in background

Further, the --rm argument has been used in the above command to instruct the Docker daemon to automatically remove the container, when it exits.

Event 9 — The Docker daemon performs the Docker container (life-cycle) management role.

Using Docker images available at Docker Hub

In this section, we’ll attempt to run WSO2 API Manager version 2.6.0 in a Docker container using the WSO2 API Manager All In One Docker image available at Docker Hub.

You can follow these steps to achieve this.

• [Optional] Pull the WSO2 API Manager All In One Docker image from Docker Hub

docker pull wso2/wso2am:2.6.0

As described earlier under Using Docker images available at WSO2’s Private Docker Registry section, this step is optional.

• Run a Docker container instance using the Docker image pulled in the previous step

docker run --name wso2am --rm -it -p 9443:9443 wso2/wso2am:2.6.0

• Access API Manager’s Carbon management console, Publisher and Store

Carbon management console: https://localhost:9443/carbon

Publisher: https://localhost:9443/publisher

Store: https://localhost:9443/store

What happened?

The following is a concise diagram which depicts the underlying tasks which were carried out by the involved parties, when you executed the above steps.

Flow of events when running a WSO2 API Manager Docker container using the Docker image available at Docker Hub

Event 1— Pull the WSO2 API Manager Docker image from Docker Hub.

docker pull wso2/wso2am:2.6.0

This command will initially check if the specified Docker image is available within the local image cache of the Docker host. If unavailable, the registry client proceeds with events 2, 3 and 4.

Events 2 and 3—The registry client (Docker daemon, in this case) executes the Docker image pull action from the Docker Hub.

Event 4 — The pulled Docker image layers will be stored in the local Docker image cache of the Docker host.

Event 5 — Run a Docker container instance using the pulled Docker image.

The same underlying procedures are carried out when executing this step as described in under Using Docker images available at WSO2’s Private Docker Registry section, when running the same step.

Here, only the fully qualified image name has changed compared to the image pulled from the Private Registry (in this case, image named wso2am has been pulled from the wso2 organizational profile at Docker Hub).

Event 6— The Docker daemon performs the Docker container (life-cycle) management role.

In this write up, I have managed to provide you with a simple introduction and a practical guide on using WSO2 product Docker images.

Please bear in mind that this article is by no means a comprehensive guide of WSO2 Docker images. A guide which provides a complete insight will span across multiple write ups, which I expect to bring forward in the near future.

So until then… Happy Dockering!!!

References

[1] What is Docker? — https://docs.microsoft.com/en-us/dotnet/standard/microservices-architecture/container-docker-introduction/docker-defined

[2] Authorization for Private Docker Registry — https://medium.com/@maanadev/authorization-for-private-docker-registry-d1f6bf74552f