Getting started with webMethods API Portal using Docker images

Knowledge base
,
1

webMethods API Portal tutorial

Table of contents:

  1. Log in to Docker® store
  2. Request an API Portal image
  3. Overview
  4. Installation
    1. Unix installation
    2. Windows installation
  5. Additional helper scripts for administrative purposes
  6. Working directly with docker-compose
  7. Common problems & troubleshooting
  8. Documentation
  9. Feedback
  10. Free trial restrictions
  11. License
  12. Base Image

1. Log in to Docker® store through:

https://store.docker.com

2. Request an API Portal image through:

https://store.docker.com/images/softwareag-apiportal 

3. Overview

webMethods API Portal is a multi-container application, i.e., for the application to work, several Docker containers have to be started at once. To simplify installation and starting of API Portal , a special container softwareag/aris-deploy-tools is provided which will copy a number of scripts onto your Docker host, that will allow you to generate a Docker compose file that includes all required API Portal containers. In addition, the compose file will create Docker volumes in which the persistent data of your API Portal installation is kept. These volumes allow you to remove the installation (i.e., the Docker containers and images), while keeping your data.

4. Installation

To copy the scripts to your host, run the command

docker run --rm -v <hostTargetDir>:/arisDockerSetup store/softwareag/aris-deploy-tools:<version> <hostTargetDir> store/

and replace

  • <hostTargetDir> with the directory on the host where the compose file should be generated into (e.g., “~/api” to put it into the “api” subdirectory of your user’s home directory. Warning: The content of this directory will be deleted when running the deploy-tools!) and
  • <version> with the version of container images you want to install, e.g., 10.0.8.0

The contents of the directory chosen for <hostTargetDir> will be deleted!

For example, to install the scripts for container images of version 10.0.4.1 into a folder "~/api", you would run the command

docker run --rm -v ~/api:/arisDockerSetup store/softwareag/aris-deploy-tools:10.0.8.0 ~/api/ store/

Inside the selected target folder, three subfolders will be generated, "compose", "enhancements", and "scripts".

Based on the platform in which you are running the docker daemon we have different set of instructions to follow.

4.1. Unix installation

Navigate to the “scripts” folder. There you will find the actual scripts. To generate the compose file and run it with docker-compose (which needs to be installed on your host), you need to run the deploy.sh script with sudo access. To install API Portal, pass a single parameter “api” to it:

./deploy.sh api

The compose file docker-compose.yml will be generated and put into the target folder ("~/api" in our example) and will be used with a “docker-compose up” command to start the installation. After a while, of everything works as expected, the script will finish with the output

All container are up and healthy after 125 sec.
+++ DONE (deploy.sh) +++
return :  0

If any other return code other than "0" is reported, please refer to the troubleshooting section below.

4.2 Windows installation (Docker toolbox/Native docker support with Windows 10)

Open a cygwin shell and navigate to “compose” folder under the target("~/api" in our example). You can use the script createComposeForParameter.sh to generate the compose file for API Portal, pass a single parameter “api” to it.

./createComposeForParameter.sh api

Above command will generate a docker-compose.yml file in target folder (~/api directory). Navigate to ~/api directory and execute

docker-compose -p api up -d

5. Additional helper scripts for administrative purposes

In addition to the deploy.sh script itself, a number of helper scripts are provided which can help you to start, stop, or remove the existing installation. In general, these scripts will only affect those containers, images, and other Docker objects that were created through the deploy.sh script, unless noted otherwise:

  • scripts/start.sh - Pulls (if not already in the local repository) and starts the API Portal containers
  • scripts/stop.sh - Gracefully stops the API Portal containers
  • scripts/kill.sh - Performs a hard shutdown of the API Portal containers
  • scripts/teardown.sh - Stops and removes the API Portal containers and also removes the API Portal images from the node
  • scripts/clean.sh - Similar to teardown.sh, but this script will also remove any other containers that are labeled as being “ARIS” containers (for which we use the label “com.softwareag.product=ARIS”)
  • scripts/refresh.sh - This script accepts the same set of parameters as the deploy.sh script. It should be used if you want to change the original parameterization that you used when running deploy.sh (e.g., to add one of the add-ons).

6. Working directly with docker-compose

As an alternative to using the helper scripts, you can also use docker-compose directly. To do that, change into the target directory (i.e., the directory containing the docker-compose.yml) and use the usual compose commands. Note that you need to pass the “project name” “api” to docker-compose using the “-p” switch. For example, to see the list and current state of all API Portal containers created via docker-compose by the deploy script, run

docker-compose -p api ps

Once all the containers are up and running you can acccess the portal using http://dockerhost or https://dockerhost URLs.

7. Common problems & troubleshooting

  • Elasticsearch container crashes (Exit code 78) or the deploy.sh scripts complains about an incorrect value of the setting “vm.max_map_count”

Problem: After running the script (in particular in a Docker-Toolbox-based Docker environment), most containers are shown as running. Most are shown as “healthy” in the output of “docker ps”, some are “unhealthy”. The Elasticsearch container (image name softwareag/aris-elastic, container name api_elastic_1) is shown as “Exited”, with exit code 78. When looking at the logs with the command

docker logs api_elastic_1

the log ends with an error message

[...]
bootstrap checks
ERROR: [1] bootstrap checks failed
[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
[2018-04-24T13:14:29,556][INFO ][o.e.n.Node               ] [elastic] stopping ...
[2018-04-24T13:14:30,159][INFO ][o.e.n.Node               ] [elastic] stopped
[2018-04-24T13:14:30,159][INFO ][o.e.n.Node               ] [elastic] closing ...
[2018-04-24T13:14:30,327][INFO ][o.e.n.Node               ] [elastic] closed

Root cause: On startup, Elasticsearch performs certain system checks, to assure that the environment it is running is configured correctly. One setting, vm.max_map_count, is often not set properly. Note that this settings is not a setting inside the container itself, but a setting on the Linux host (i.e., the machine running Docker daemon).

Solution (NON-Docker-Toolbox environments): To change this setting, open a shell on the host. To change the setting transiently (i.e., only until the next docker host reboot), run the command

sudo sysctl -w vm.max_map_count=262144

No reboot is required.

To change it permanently, as root user, edit the file /etc/sysctl.conf and add the line

vm.max_map_count=262144

Note that the deploy.sh script actually checks the value of this setting and should exit immediately if it isn’t set correctly. However, on some environments (in particular when running the deploy scripts in the MinGW terminal on a Windows host in Docker Toolbox environment), the check cannot work.

Solution (Docker-Toolbox environments):

Open an SSH shell into your boot2docker machine (using “docker-machine ssh <nameOfTheDockerMachine>”). Edit the file /var/lib/boot2docker/profile as root user and add the line

sysctl -w vm.max_map_count=262144

to the end. Save the file and restart your boot2docker VM.

  • Containers fails to start with out of memory error in docker toolbox environment

Root cause:
The default vm shipped with docker toolbox environment has the configuration of 1GB RAM and 1 core processor.

Solution (Docker-Toolbox environments):
Please edit the configuration for default machine and provide the additional memory RAM 8GB / Processor: 2 core

8. Documentation

The full documentation is available on the the documentation website: Documentation as well as the Tech Community

On the community website you can also find forum discussions and blog posts about using webMethods API Portal along with tutorials and code samples. 

http://techcommunity.softwareag.com/web/guest/pwiki/-/wiki/product/name/api-portal

http://techcommunity.softwareag.com/ecosystem/communities/public/webmethods/products/api-portal/video

9. Feedback

For customers with a commercial license support is available via Empower as normal. For community users use the forums on Tech Community.

10. Free trial restrictions

Full-featured version of the webMethods API Portal, free trial is limited to 90 days for non-production use.

11. License

License terms for this product can be found here: License

If you wish to purchase a commercial license for webMethods API Portal, please contact us here: http://www.softwareag.com/contact

12. Base Image

This product references the official alpine image as its base image.

Software AG is not responsible for the contents of this base image.
 

Got more questions? 

Feel free to publish them under the webMethods API Management Free Trial forum.