How to install webMethods API Gateway using Docker?

Why Docker?

Applications often fail to run correctly when moved from one environment to another due to differences in configurations, underlying library requirements, and other dependencies. To enable developers and IT professionals to deploy applications seamlessly across environments, software development technologies increasingly use a technique called containerization.

Containers solve this problem by providing lightweight, immutable deployment and packaging infrastructure. Docker is one such containerization framework that can be used to create and run webMethods API Gateway as containers. webMethods API Gateway container bundles together the code of the application along with the configuration files, libraries, and dependencies required for webMethods API Gateway to run. Containerized applications can be tested individually and deployed as container image instances to the host operating system. By this means, developers and IT professionals can deploy webMethods API Gateway across environments with little or no modification.

You can run webMethods API Gateway in containers or on Virtual machines. Running webMethods API Gateway in containers is favourable as the containers can be orchestrated with container orchestration platforms like Kubernetes. To facilitate running webMethods API Gateway in a Docker container, IBM provides webMethods API Gateway images in the MyIBM Container Software Library.

IBM offers a Docker image for webMethods API Gateway that includes both the webMethods API Gateway server and its UI. Containers using this image must be composed with separate external Elasticsearch and external Kibana instances, both version 8.12.2. webMethods API Gateway will not start unless it is connected to a running Elasticsearch instance.

This article explains how to run an webMethods API Gateway container, apigw and start using webMethods API Gateway.

Before you begin

Ensure that you have installed the latest version of Docker.
Ensure that the docker host provides at least 4 GB of main memory. To accommodate the space for Elasticsearch, set the virtual memory kernel setting to 262144 by running the following command on your Docker host:
```
sysctl -w vm.max_map_count=262144
```
Complete the following steps to download certified container images from IBM Entitled Registry:
1. Ensure that you have obtained the entitlement key.
2. Log in to MyIBM Container Software Library with the IBM ID and Password that are associated with the entitled software. In case, you are not directed to the entitlement page, click Get an entitlement key and obtain the entitlement key.
3. In the Entitlement key section, click Copy key to copy the entitlement key to the clipboard.
4. Save the entitlement key to a safe location for later use.
5. Open Command Prompt.
6. Log in to Docker using the docker login command.
  A sample docker login command is as follows:
```
docker login cp.icr.io -u cp -p entitlement_key
```
  Replace entitlement_key with the actual entitlement key that you obtained from the MyIBM Container Software Library. This key grants access to entitled container images.
7. Download the certified container image using the docker pull command.
  A sample docker pull command to download the webMethods API Gateway image is as follows:
```
docker pull cp.icr.io/cp/webmethods/api/image-name:tag
```
  - Replace image-name with the actual name of the Docker image you want to pull. For example, if you are pulling the webMethods API Gateway image, you might use api-gateway.
  - Replace tag with the specific version (or tag) of the image you want. For example, use a version like 11.1.3 to pull that specific version of the image.

To install webMethods API Gateway using Docker

Run the webMethods API Gateway container image by composing it with an Elasticsearch container and a Kibana container. Start the Elasticsearch instance or container using the following command:
```
docker network create apigw
docker run --name elastic-svc 
--net apigw -d -p 9200:9200 -p 9300:9300 -e "xpack.security.enabled=false" 
-e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.12.2
```
The container starts within the apigw network.
Once the Elasticsearch container is available, start the webMethods API Gateway container using the following command:
```
docker run -d -p 5555:5555 -p 9072:9072 \
-v ${PWD}/meteringConfiguration.xml:/opt/softwareag/common/metering/conf/meteringConfiguration.xml
--env apigw_elasticsearch_hosts=elastic-svc:9200 \
--env apigw_kibana_dashboardInstance=http://kibana-svc:5601 \
--hostname apigw-svc \
--net apigw \
--name apigw cp.icr.io/cp/webmethods/api/api-gateway:11.1.3
```
where:
- 5555 and 9072 is the HTTP port of Integration Server and webMethods API Gateway UI respectively, which is configured during installation.
- meteringConfiguration.xml is the configuration file for the metering functionality. Add this configuration file from where the docker container starts, so that the configuration file gets looked up from PWD, which is present working directory. For details about how to download metering 2 How to install API Gateway using Docker? Configuration.XML see https://docs.webmethods.io/on-premises/webmethods-infrastructure/en/11.1.0/webhelp/index.html#page/wsi-webhelp%2Fta-configure_mta_onprem.html%23.
- apigw-svc is the host information of the Docker container that is set, and apigw is the name of the container that is set.
- cp.icr.io/cp/webmethods/api/api-gateway:11.1.3 specifies the Docker image to use for the container.
The docker run is parameterized with the Integration Server and the webApp port exposed by the Docker container. If you have configured different ports for Integration Server and UI, use the corresponding ports in the command.
You can check the status of the webMethods API Gateway Docker container, apigw by running the following command:
```
docker ps
```
Wait until the status of the container turns healthy to start using webMethods API Gateway.
The Elasticsearch container uses the environment variable apigw_elasticsearch_hosts. The Kibana instance uses apigw_kibana_dashboardInstance.
Once the webMethods API Gateway container is running, start the Kibana container using the following command:
```
docker run --name kibana-svc --net apigw -d -p 5601:5601 \
--env ELASTICSEARCH_HOSTS=http://elastic-svc:9200 \
--env SERVER_BASEPATH=/apigatewayui/dashboardproxy \
docker.elastic.co/kibana/kibana:8.12.2
```
Start using webMethods API Gateway.
Open http://defaulthost:defaultport of Integration Server and webMethods API Gateway.
Integration Server:
```
http://localhost:5555
```
Port is the HTTP port of Integration Server configured during installation; by default, 5555.
webMethods API Gateway:
```
http://localhost:9072
```
Port is the HTTP port of webMethods API Gateway configured during installation; by default, 9072.
The home page of webMethods API Gateway appears after you log in using the default Username and Password (Administrator and manage).

You are now ready to create and manage APIs using webMethods API Gateway.

Troubleshooting Tips

If the status of the container does not turn healthy, you can check the docker logs using the following command:

docker logs --follow [container_id]

For example,

docker logs --follow [a7101d3e49d5]

The container_id is generated when you run the webMethods API Gateway container.

Next Steps

In case you want to stop the containers, use following commands:

Use the docker stop command to stop the webMethods API Gateway, Elasticsearch, and Kibana containers. A sample docker stop command is as follows:
```
docker stop elastic-svc
docker stop apigw-svc
docker stop kibana-svc
```
Use the docker rm command to remove the stopped containers. A sample docker rm command is as follows:
```
docker network rm apigw
docker rm elastic-svc
docker rm apigw-svc
docker rm kibana-svc
```

Setting JVM Heap Size

The webMethods API Gateway container image sets the initial JVM heap size to 2GB and the maximum JVM heap size to 4GB by default.

You can adjust the default settings using the environment variables:

apigw_wrapper_java_initmemory for the initial heap size.
apigw_wrapper_java_maxmemory for the maximum heap size.

A sample command to start the webMethods API Gateway container with the modified heap sizes is as follows:

docker run -d -p 5555:5555 -p 9072:9072 \
--env apigw_elasticsearch_hosts=elastic-svc:9200 \
--env apigw_kibana_dashboardInstance=http://kibana-svc:5601 \
--env apigw_wrapper_java_initmemory=4096 \
--env apigw_wrapper_java_maxmemory=8192 \
--hostname apigw-svc \
--net apigw \
--name apigw cp.icr.io/cp/webmethods/api/api-gateway:11.1.3

Using Volume Mapping for Archive and Restore

Archive and restore webMethods API Gateway data from a file system outside the Docker container by adding the following parameter to the Docker run command:

-v /home/user/archives:/tmp/default

In this command, /home/user/archives is the directory for storing the webMethods API Gateway archives.

Base Image

webMethods API Gateway references the official RedHat UBI 9 image as its base image.

Additional Resources

For details about optional arguments and additional Docker commands, see Docker Configuration.
For details about how to set up webMethods API Gateway Docker Container with Externalized Elasticsearch and external Kibana, see API Gateway Docker Container with Externalized Elasticsearch and Kibana.
For details about Docker and container technology, see Docker documentation, https://docs.docker.com/.
For details about the important system settings to be considered before you start webMethods API Gateway, see external Elasticsearch documentation, https://www.elastic.co/guide/index.html.

Docker Security related best practices

For detailed guidelines about security best practices, see Docker Security documentation, https://docs.docker.com/engine/security/.
For details about the script that can test containers and their hosts' security configurations against a set of best practices provided by the Center for Internet Security, see Docker bench, https://github.com/docker/docker-bench-security.
For details about how to establish a secure configuration baseline for the Docker Engine, see https://www.cisecurity.org/benchmark/docker for Information Security (CIS) Docker Benchmark (Docker CE 17.06).
For details about potential security concerns associated with the use of containers and recommendations for addressing these concerns, see SP 800 publication (Application Container Security Guide), https://csrc.nist.gov/publications/sp800.