webMethods API Portal tutorial
Table of contents:
- Log in to Docker® store
- Request an API Portal image
- Additional helper scripts for administrative purposes
- Working directly with docker-compose
- Common problems & troubleshooting
- Free trial restrictions
- Base Image
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.
To copy the scripts to your host, run the command
docker run --rm -v <hostTargetDir>:/arisDockerSetup store/softwareag/aris-deploy-tools:<version> <hostTargetDir> store/
- <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:
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.
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.
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
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.shscript. 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).
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
Elasticsearch container crashes (Exit code 78) or the
deploy.shscripts 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:  bootstrap checks failed : max virtual memory areas vm.max_map_count  is too low, increase to at least  [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
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
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
For customers with a commercial license support is available via Empower as normal. For community users use the forums on Tech Community.
Full-featured version of the webMethods API Portal, free trial is limited to 90 days for non-production use.
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.