Configuring Dockerized WSO2 APIM product

You may already realized that at some point, there can be a requirement of changing the default WSO2 product configuration as well as dockerized ones. And also there are couple of options to achieve this requirement. From this blog post I will guide on configuring default dockerized APIM product referring to some sample configurations.

Hereafter, I will be using the Ubuntu based WSO2 API Manager All In One Docker image available at WSO2’s Private Docker Registry [1].

At first, the most basic commands related with WSO2 APIM docker image will be:

docker login docker.wso2.com
docker pull docker.wso2.com/wso2am
docker run -it -p 8280:8280 -p 8243:8243 -p 9443:9443 --name api-manager docker.wso2.com/wso2am:2.6.0

SSH into running docker container:

docker exec -it <docker-process-id> /bin/bash
docker exec -it api-manager /bin/bash

Method 1: Using ‘docker cp’

• Copy the carbon.xml file from the container to the host machine.

sudo docker cp <Container name>:<carbon.xml file full path in the container> <carbon.xml file local path in the host machine> 
Ex: sudo docker cp api-manager:/home/wso2carbon/wso2am-2.6.0/repository/conf/carbon.xml /Users/lakmini/Documents/carbon.xml

• Update the required IP for both HostName and MgtHostName as below example in carbon.xml file in the local file path.

<HostName>10.100.8.25</HostName> <MgtHostName>10.100.8.25</MgtHostName>

• Replace the updated file in the container.

sudo docker cp <carbon.xml file local path in the host machine> <Container name>:<carbon.xml file full path in the container> 
Ex: sudo docker cp /Users/lakmini/Documents/carbon.xml api-manager:/home/wso2carbon/wso2am-2.6.0/repository/conf/carbon.xml

• Restart the container

docker restart <Container ID>

Please note that in this method if the container terminates by any chance, we need to restart the container after manually done the configs changes which previously done.

Method 2: Volume mounting

However, in this method, we are having the config changes in the host machine and then we can simply mount the file to the container when running the docker image.

• Stop the API Manager container if it’s already running.

docker stop <Container ID>

• Copy the conf folder to some suitable location of the host machine.

sudo docker cp <Container name>:<conf directory path in the container> <local folder path in the host machine> Ex: sudo docker cp api-manager-public:/home/wso2carbon/wso2am-2.6.0/repository/conf /Users/lakmini/Documents/NewFolder

• Update the required IP for both HostName and MgtHostName in <local folder path in the host machine>/carbon.xml file as below.

<HostName>10.100.8.25</HostName> <MgtHostName>10.100.8.25</MgtHostName>

• Run the image by mounting the file to the container.

docker run -p 9443:9443 - volume <local folder path in the host machine>/carbon.xml:<conf directory path in the container>/carbon.xml wso2/wso2am:2.6.0 
Ex: docker run -p 9443:9443 - volume /Users/lakmini/Documents/NewFolder/conf/carbon.xml:/home/wso2carbon/wso2am-2.6.0/repository/conf/carbon.xml wso2/wso2am:2.6.0

Please note that the recommended approach is Method 2.

Some Key Points……

In order to avoid from errors like “No such container:path: api-manager:/wso2am-2.6.0” you need to pass the correct container path (ex: “/home/wso2carbon/wso2am-2.6.0/”).

Normally from ‘docker run’ command, it runs a new Docker container instance using the pulled Docker image. So without any configuration mounting a fresh APIM instance will be created.

However, we can add to or override the image defaults. Additionally, operators can override nearly all the defaults set by the Docker runtime itself. (Moreover, ‘docker restart’ will preserve the changes previously done to the container.)

For production development, we need to mount some additional configurations. Please find those configurations at a high level.

• <APIM_HOME>/repository/deployment/server/synapse-configs
• <APIM_HOME>/repository/deployment/server/executionplans
• <APIM_HOME>/repository/tenants
• <APIM_HOME>/solr
• <APIM_HOME>/repository/conf
• <APIM_HOME>/repository/logs
• Separate RDBMS for APIM DB, registry DB, and userstore DB
• WSO2 API Manager is shipped with an H2 database. This embedded H2 database is suitable for development and testing environments. However, for production environments, it is recommended to use an industry-standard RDBMS. Please refer to the documentation [2] for further details. (For testing purposes, we can mount <APIM_HOME>/repository/database which having H2 database.)

For changing the configurations in multiple files and mounting, it is a must to maintain the exact folder structure of the customized configuration files as in the original WSO2 product pack in the mounted folder (i.e. SOURCE_CONFIGS) at the Docker host.

docker run -v <SOURCE_CONFIGS>:/home/wso2carbon/wso2-config-volume -p 9443:9443 docker.wso2.com/wso2am:2.6.0

In order to avoid errors like “Failed to connect to xx.xxx.xxx.xxx port xxxx: Connection timed out” you have to expose API Manager specific ports mentioned in the document [3](according to your requirements) when starting the docker container.

docker run -p 9443:9443 -p 9763:9763 -p 8243:8243 -p 8280:8280 -p 10397:10397 -p 7711:7711 ...

Also, the latest updated WSO2 repositories can be found in [1] and you will need an active WSO2 subscription.

References

[1] http://docker.wso2.com/

[2] https://docs.wso2.com/display/AM260/Installing+and+Configuring+the+Databases

[3] https://docs.wso2.com/display/AM260/Default+Product+Ports#DefaultProductPorts-APIManager

[4] https://github.com/wso2/docker-apim/tree/v2.6.0.5/dockerfiles/ubuntu/apim