top of page

IBM App Connect Enterprise - Building & Running Integration Solutions in Docker

With IBM App Connect Enterprise v11, changes have been introduced in IIB (now referred as ACE from v11 onwards) runtime architecture for running inside containers that covers

  • Independent Integration servers w/o Integration Node runtime

  • "Unzip and go" deployment approach

As part of my trainings on IBM App Connect Enterprise, I have been asked about these changes with respect to cloud-based deployment.

In this blog I will be focusing on how to build an image of IBM App Connect Enterprise for running in a container. As per IBM, one can build an image containing one of the following combinations:

  • IBM App Connect Enterprise

  • IBM App Connect Enterprise with IBM MQ Client

  • IBM App Connect Enterprise for Developers

  • IBM App Connect Enterprise for Developers with IBM MQ Client

Reference GitHub URL:


  • Integration Solution developed and packaged as BAR file

  • Docker installed on the machine used for building the image

In my illustration for running integration solutions in docker, I have used the pre-build image of IBM App Connect Enterprise for Developer edition (link provided above). For integration solution, I have developed REST API that also consumes cloud-based third party services that is secured using API Key. The solution also implements logging using sfl4j & logback utilities using third-party external jars.

Following scenarios will be illustrated

  • Building docker image for the REST API solution using the pre-build image of IBM App Connect Enterprise for Developer Edition

  • Creating security identity alias for third-party application / service connection security

  • Packing and referencing external jars that are required for logging

  • Pushing the image to docker repository

  • Running the docker container using the image we have built

Creating required files & directory structure for docker image

For packaging our REST API integration solution as a docker image, we need to load all the requisite files & configurations in the image. Required files and their purpose listed below

  • BAR file of our REST API solution along with all dependent artifacts like libraries etc

  • setdbparms.txt: for setting parameters vis mqsisetdbparms, format of the file is given below

# Lines starting with a "#" are ignored
# Each line which starts mqsisetdbparms will be run as written 
# Alternatively each line should specify the <resource> <userId> <password>, separated by a single space
# Each line will be processed by calling...
#   mqsisetdbparms ${ACE_SERVER_NAME} -n <resource> -u <userId> -p <password>
resource1 user1 password1
resource2 user2 password2
mqsisetdbparms -w /home/aceuser/ace-server -n salesforce::SecurityIdentity -u myUsername -p myPassword -c myClientID -s myClientSecret
  • server.conf.yaml: contains the override properties for the integration server

  • logback.xml: Configuration file for logback logger class used by logging framework

  • Dockerfile: set of instruction for building docker image with our integration solution

Dynamic configuration of the ACE Integration Server is supported and for that purpose initial-config directory is used. Before the Integration Server starts, the container is checked for the folder /home/aceuser/initial-config. For each folder in /home/aceuser/initial-config a script called ace_config_{folder-name}.sh will be run to process the information in the folder. For detailed list of the folders, refer to the GitHub URL link I have provided above as reference.

In this illustration I will be using the serverconf (for overriding the integration server properties) and setdbparms (for creating security identity used by my solution) folders under initial-config

Below I have provided the image of the directory structure on the machine used for building the docker image for this illustration

Dockerfile for building IBM ACE Docker image for our Integration Solution

Dockerfile provides the set of instructions that will be used by docker engine to package our solution / application as a docker image.

Below provided is the Dockerfile content used by me for this illustration

# Building from Official IBM App Connect Enterprise for Developers image from DockerHub repos
FROM ibmcom/ace:latest
USER root
# Copying the bars directory into the docker image path /home/aceuser/bars
COPY bars /home/aceuser/bars
# Copying the logs directory into the docker image path /home/aceuser/logs
COPY logs /home/aceuser/logs
# Copying the logback.xml file into the docker image path /home/aceuser/
COPY logback.xml /home/aceuser/logback.xml
# Copying the shared-classes directory with external jar files into into the docker image path /home/aceuser/ace-server/shared-cl
COPY shared-classes /home/aceuser/ace-server/shared-classes
RUN  chmod -R ugo+rwx /home/aceuser
USER 1000
USER root
RUN  chmod -R ugo+rwx /home/aceuser
USER 1000

Building Docker Image of IBM ACE with our Integration Solution

  • Navigate to the directory containing the Dockerfile on your machine / server

  • Run the docker build command to create a docker image of IBM ACE with our integration solution, as shown below

Syntax: docker build -t <image tag> --file <docker file name> .
$ docker build -t aceleadsapi --file Dockerfile .
  • List the docker images on your machine / server using the docker image ls command as shown

Pushing Docker Image to Repository

Now that we have created a docker image of IBM ACE with our integration solution, its time to push to docker repository for sharing. For this purpose, I have created a private repository on Docker Hub into which I will now be pushing this docker image.

  • Tag the local image with the repository name using docker tag command.

Source Image: aceleadsapi

Source Image tag: latest

Target Image: reachnebula/dev (my docker private repository)

Target Image Tag: aceleadsapi_1.0.0

And then list the docker images as shown

$ docker tag aceleadsapi:latest reachnebula/dev:aceleadsapi_1.0.0 
  • Push the tagged docker image to the docker repository using the docker push command

Syntax: docker push IMAGE[:TAG]
$ docker push reachnebula/dev:aceleadsapi_1.0.0

Running the docker image as Container

Once the docker image has been downloaded from the docker repository using docker pull command on the required server, we can start the docker image as container using docker run command

Default configuration of the Integration Sever within the container

  • ACE Server name: ACESERVER (modifiable using image environment variable ACE_SERVER_NAME, as shown in below docker run command)

  • REST Admin port for the server: 7600

  • HTTP port for the server: 7800

  • Work directory for the Integration Server: /home/aceuser/ace-server

In the docker run command, following parameters are passed along with image name

  • -d : Detached mode. To run container in background and print container ID

  • --name: Container name (e.g. aceleadsapi)

  • -p <host machine port>:<container port>: Publish a container's port(s) to the host, called as port mapping --> mapping port of the integration solution running inside the container to the port on the host machine for external access (e.g. -p 7600:7600)

  • --env: Set environment variables (e.g. LICENSE=accept). Refer to GitHub reference url provided above for complete list of available environment variables

  • --mount: Attach a host filesystem mount to the container. src corresponds to filesystem on host machine and dst to the filesystem on container

  • -v <host filesystem>:<container filesystem>: Another option to bind mount a volume to container. In this case this is used to the mount the filesystem for storing the integration solution logs that will generated by logging framework (as provided by the logback.xml configuration file). Kindly note the path provided in the logback.xml configuration file corresponds to the path within the container.

To check the logs of the docker container, use the docker logs command as shown

To access the running docker container aceleadsapi and execute command within the container, we can use docker exec command. Using this we can verify all files that we have copied to our image and the file path as shown.

$ docker exec -it aceleadsapi /bin/bash

To stop the container, run docker stop <container-name> and to start again, run docker start <container-name>

Recent Posts

See All


bottom of page