This blog is part of a series. For the whole series list see here
Scenario 1. Basic example using Docker
Many enterprises have IBM Integration Bus environments running 100s of integration flows in production. You have likely read about the benefits of moving to containers, perhaps even more generally of agile integration (http://ibm.biz/agile-integration), and you’d like to explore that. You’d also like to move to a more recent version of the product (now named App Connect Enterprise). However, it is likely you have no, or at least very limited background in container technology. How do you take the first steps to exploring these new platforms and product versions?
In this series we are going describe how you move to containers running App Connect Enterprise. We’ll build up to more complex examples, but for this first one we’ll take the simplest possible flow, and we’ll use a Docker container environment that can easily be run on a laptop.
It is worth noting that you are not forced to move to containers to move to IBM App Connect Enterprise, but hopefully through these articles we will give you some practical insight into the benefits you might gain if you do.
Introducing our (very) simple integration flow
We take a simple example of an HTTP based flow as shown in the figure below, that presents an echo service (we’ll call it HttpEcho) over an HTTP endpoint on port 7800. This returns the current date-stamp in response. Clearly this example flow doesn’t do much, but this article isn’t about writing integration flows, it is about moving them to containers, and we’ll come to more complex ones in future articles.
You can call this by going to http://localhost:7800/Echo or running
curl command as
curl -k http://localhost:7800/Echo">http://localhost:7800/Echo
The BAR file generated using IIB v10 Toolkit containing the above message flow is attached here.
In this scenario we will see how to deploy this BAR file into a Docker container running IBM App Connect Enterprise using simple steps.
Install Docker or Podman
Important: In August 2021, Docker announced changes to their product subscription model. While Docker Desktop for MacOS and Windows remains free for certain users under the terms of Docker’s Personal tier, those users working in larger organizations and groups may be required to subscribe to one of Docker’s paid subscription tiers. These changes will take effect starting on January 31, 2022.
To install Docker, download Docker Community Edition, version 17.06 or later, from Docker Hub. Then, follow the instructions in the installation documentation to install Docker.
Docker images are generated in an OCI standard format and are compatible with Podman, an open source, Linux-native tool. (Read more about transitioning to Podman in this Red Hat Developer blog.) If you do not want to (or cannot) subscribe to one of Docker’s paid subscription tiers, you can use Podman as an alternative to complete this tutorial.
To install Podman, follow the instructions in the Podman installation documentation.
Building or downloading a sample IBM App Connect Enterprise image using Docker
To run IBM App Connect Enterprise in a Docker container, you must first build a base image containing an installation of IBM App Connect Enterprise. Instructions are available in the IBM App Connect Enterprise GitHub repository, at https://github.com/ot4i/ace-docker. Alternatively, you can download a pre-built image of IBM App Connect Enterprise from the IBM Entitled Registry. In this example, for simplicity, we will use the pre-built image, but it would work largely the same if you build your own.
Obtain an IBM entitlement key
To obtain your required version of an IBM App Connect Enterprise server image, you require an IBM entitlement key for pulling the image from the IBM Cloud Container Registry.
Obtain an IBM entitlement key by visiting the following site:
You will need to log in with an IBM ID. It is free to register for an ID if you do not have one.
Obtaining an IBM App Connect Enterprise server image
- Log in to the IBM Cloud Container Registry by running this command, using cp as the user name, icr.io as the Docker server, and your entitlement key as the password:
docker login cp.icr.io -u cp -p myEntitlementKey
- Use Docker to pull the required version of the ACE server image,
docker pull imageLocation
where imageLocation represents one of the listed image locations in the table shown in the following link:
These are basic images based on the ace-docker github samples, and they can be used in any container environment (Docker, Podman, Kubernetes etc.). Note however, that these are different to the “operator-based” images that we will be using in later articles . Those have a dependency on the IBM App Connect Operator which can only be installed in Kubernetes environments.
In this demonstration we will use ACE server image version 188.8.131.52-r1
Here is the command we will use to pull the image from the IBM Container registry
$ docker pull cp.icr.io/cp/appc/ace:184.108.40.206-r1@sha256:f8f1baa76be21adfeefef8dcf56f432bad7840efdbe147217ee6dcc8710f478d
$ docker images
REPOSITORY TAG IMAGE ID CREATED
cp.icr.io/cp/appc/ace 220.127.116.11-r1 84ae64b988bd 3 weeks ago
After the image is pulled /downloaded, tag it so that it is easy to recall.
For example :
$ docker tag 84ae64b988bd ace:18.104.22.168-r1
$ docker images
REPOSITORY TAG IMAGE ID CREATED
ace 22.214.171.124-r1 84ae64b988bd 3 weeks ago
Note: If you are using 'podman' tool instead of 'docker' to manage your images, you may see some differences to the output shown above. For example, when you tag an image without repository name, you may see 'localhost/' being prefixed to the image name as shown below:
$ podman tag 84ae64b988bd ace:126.96.36.199-r1
$ podman images
REPOSITORY TAG IMAGE ID CREATED
localhost/ace 188.8.131.52-r1 84ae64b988bd 3 weeks ago
Customizing an ACE Server image
You may have some customization requirement on top of the base ACE server image like setting up some configuration for odbc.ini or bake in the bar files into the ACE server image or you want to add MQ Client to the ACE image to be able to deploy MQ based flows etc..
The samples provides in following GitHub repository contains Dockerfile and some additional files that show how you can build and customize an IBM App Connect Enterprise Docker image: https://github.com/ot4i/ace-docker/tree/master/samples
Running ACE Server image
You can run the image by using an example command such as:
docker run --name aceserver -p 7600:7600 -p 7800:7800 -p 7843:7843 --env LICENSE=accept --env ACE_SERVER_NAME=ACESERVER ace:184.108.40.206-r1
Let us look at the various command line options that we have passed to the docker run command.
--name : Name assigned to the Docker container
-p : This option maps the container's port(s) to the host. The Integration Server by default enables ports 7600, 7800, 7843 during start-up and they serve following purpose:
7600 – An administrative listener port. Also used by the WebUI.
7800 – To listen to http traffic
7843 – To listen to https traffic
These ports are exposed to the VM host so that external applications can invoke the services hosted by message flows over these ports.
--env : To pass on an ENV variable to the container. You must accept the license to be able to launch the ACE Integration Server. You can optionally provide a name to your Integration Server using env var ACE_SERVER_NAME
ace:220.127.116.11-r1 : The ACE image that is being launched.
Observe the console output. An example is shown as below
2022-09-22 11:55:42.546692: BIP1990I: Integration server 'ace-server' starting initialization; version '18.104.22.168' (64-bit)
2022-09-22 11:55:42.559880: BIP9905I: Initializing resource managers.
2022-09-22 11:55:46.840644: BIP9906I: Reading deployed resources.
2022-09-22 11:55:46.846004: BIP9907I: Initializing deployed resources.
2022-09-22 11:55:46.849080: BIP2155I: About to 'Initialize' the deployed resource 'AutoScaleApp' of type 'Application'.
2022-09-22 11:55:47.117040: BIP2155I: About to 'Start' the deployed resource 'AutoScaleApp' of type 'Application'.
An http endpoint was registered on port '7800', path '/testService'.
2022-09-22 11:55:47.124048: BIP3132I: The HTTP Listener has started listening on port '7800' for 'http' connections.
2022-09-22 11:55:47.124168: BIP1996I: Listening on HTTP URL '/testService'.
Started native listener for HTTP input node on port 7800 for URL /testService
2022-09-22 11:55:47.124404: BIP2269I: Deployed resource 'test_service' (uuid='test_service',type='MessageFlow') started successfully.
2022-09-22 11:55:47.798932: BIP2866I: IBM App Connect Enterprise administration security is inactive.
2022-09-22 11:55:47.815324: BIP3132I: The HTTP Listener has started listening on port '7600' for 'RestAdmin http' connections.
2022-09-22 11:55:47.816880: BIP1991I: Integration server has finished initialization.
It is worth noting that in a single step, starting from a completely generic container platform, the container started within just a few seconds with a fully installed and configured Integration Server, and the BAR file is already deployed and running. Compare this to the time (and indeed the many steps) it would take in a traditional environment to install, configure and start up an Integration Server, and then deploy a BAR file to it.
You can begin to see just how different this container-based approach is, and what opportunities this offers in terms of new ways of working. We can imagine how much easier it would be for example, to build a CI/CD pipeline, and how that pipeline could effectively include not just the code, but the full server configuration. It might also lead us to think differently about how we manage high availability and scalability.
We’ll cover more on this and the broader cloud native approach in future posts.
Execute and Test the message flow
Let’s just check that we really do have a running integration application. As seen in the console output, the HTTP listener is listening on port 7800 and service endpoint is /Echo. You can verify the message flow execution by invoking the service via a web browser or
Connecting to the WebUI of the Integration Server
In our start-up command, we chose to expose the web user interface via 7600.
However, it’s worth noting that in a true cloud native deployment we would avoid viewing and administering containers directly like this. A cloud native approach (http://ibm.biz/cloudnativedefined) encourages administrative changes to be made by creating a new container rather than administering the one that is running (“immutable deployment”), and monitoring is generally done by viewing log files or using a visualization tool on them (“observability”).
We’ll discuss these changes to the way we work as we go through the more advanced examples.
Acknowledgement and thanks to Kim Clark for providing valuable technical input to this article.