WSO2 Tutorial 17 min

Setting up a Dockered WSO2 API Manager (Part 1)

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
Dockered WSO2 API Manager

Dockered WSO2 API Manager.jpegInstalling WSO2 API Manager (APIM), or any WSO2 product for that matter, is a cinch. We have detailed the steps in this blog. However, the last half year or so, Docker keeps popping up as the new environment to run WSO2 products!

To make this blog accessible to more readers, let’s talk about what Docker is before telling how to set up a Dockered WSO2 API Manager.


Docker 101

Docker is nothing more or less than a new way to do virtualization of environments.

A traditional computing environment will look something like this:

traditional computing enviroment.png

As you can see, the OS is installed on the hardware (which includes all drives, memory and processors). On top of the OS there is the application-layer (running various applications). The example shows what you could install to run APIM on your local PC.

When you run virtualization software like VMWare or VirtualBox, the picture changes slightly.

run virtualization software.png

The lower tiers are the same as when you run locally, but you add a virtualization layer that will allow to run a bundled set containing both the OS and applications, known as a virtual appliance. This allows you to have multiple environment flavors that you can deploy, for instance running APIM on CentOS and ESB on SUSE. However, each virtual appliance includes the OS as well as all the applications.

Docker on the other hand is a hybrid. It is very much like to a local PC environment since there is no virtualization software visible. At the same time, Docker has something similar to the virtual appliances of the traditional virtualization environments. A Docker Image can be built to contain Java, WSO2 and all other required software to run APIM.

Docker Image.png

Setting up the Docker environment

Of course we need to install Docker on our computer. Since Docker runs on Linux (in other words, it uses Linux commands) we cannot run Docker Natively on Windows. I am running Windows so I need to create a virtual machine that runs Linux for this example.

I am going to use Vagrant for this purpose. Vagrant is a tool that allows me to create and start a VirtualBox instance that runs Linux with Docker and all other things installed.

Installing vagrant

In order to keep this blog ‘short-ish’, I will refer to this blog for the installation instructions on vagrant.

Once you have a vagrant environment installed, go to the command line of  your system and create a directory for the vagrant files. I’ve done the following

md vagrant

cd vagrant

md docker

cd docker

From the directory I’ve initialized vagrant using

vagrant init

Vagrant Docker.png

This will create a Vagrantfile that describes the VM that we are going to use. Change the default settings (I am only showing the changes) to create a suitable VM. Please note that I assume you installed according to the blog referenced  earlier.

You need to change the  following parameters:

Vagrant.configure("2") do |config|
  ENV["LC_ALL"] = "en_US.UTF-8"
  config.vm.box = "centos/7"
  config.vm.box_check_update = false
config.vm.define "Yenlo Docker" do |machine|
    machine.vm.hostname = "centosdocker"   
    machine.vm.provider "virtualbox" do |vb|
      vb.name = "YENLO Docker 1.0"
      vb.memory = "4096"
    machine.vm.network "private_network", ip: ""
config.vm.provision "shell", inline: <<-SHELL

Once you have made the changes to the Vagrantfile, run the following command:

vagrant up

This will create an environment that we can use to install Docker. All of the commands that you will type in are also in a Vagrantfile that will automate the complete process. It is best to follow the blog instructions once to get a better understanding of Docker. After that, feel free to use and change the Vagrantfile. We will include this Vagrantfile in this blog. You can download it here.

Vagrant SSH

To install Docker we will SSH into the newly created machine using the command:

vagrant ssh

At the command line type the following

sudo yum install -y docker

This installs Docker. To test the installation you can type

docker -v

it will give you the version of Docker installed.

Make sure the Docker daemon is running with this command:

sudo service docker start

Sudo service docker start.png

Another test is to actually run a Docker image in a container. To do this, enter the following command:

sudo docker run hello-world

Sudo docker hello world.png

This also show the way Docker works. The image below shows the steps:

  1. the command line tells Docker to run a specific Docker image
  2. the docker-deamon will retrieve the image from the Docker Hub
  3. the docker-deamon will create a container with the retrieved image
  4. the docker-deamon will take the output and show it on the command line
Hello world - docker.png

Docker Builder

But we need more to build a docker api manager library. There are of course versions in the Docker Hub but it is better to build our own image.

If we  want to do a distributed deployment, e.g. WSO2 API Manager components in different containers, we also need to install Docker Compose.  Although we do not envision a complete distributed deployment, the WSO2 Dockerfiles that were previously available are gone. But we will show how to install docker-compose anyway. The WSO2 Dockerfiles also include a Docker Compose set of files. We will explain more about that in the next blog.

First, install python-pip as prerequisite:

  • sudo yum install -y epel-release
  • sudo yum install -y python-pip

Then you can install Docker Compose:

  • sudo pip install docker-compose

You will also need to upgrade your Python packages on CentOS 7 to get docker-compose to run successfully:

  • sudo yum upgrade -y python*

Finally we install unzip and wget

sudo yum install -y unzip

sudo yum install -y wget

and download the WSO2 API Manager docker files from github

wget https://github.com/wso2/docker-apim/archive/master.zip

We  unzip the downloaded zip file using

sudo unzip master -d /opt

We now have the structure to create our docker image. We will refer to /opt/docker-apim-master as the [Docker-Home] location.

If you ask, what is inside the directory?

What is in Dockerfile?

When we look in the Dockerfile we find several sections:

  • Settings with regards to the container, settings like the User, User Group, JAVA_HOME etc
  • Install the container files, Debian, curl, iproute2, telnet, unzip
  • ;Create a usergroup and user;
  • Copy the files in the /files directory to the
  • Installing the required packages (JDK to the user home directory and unzipping
  • Set user, and work directory, set enivronments and remove unneeded files, expose posrts and start WSO2

In short we create a typical environment to run WSO2, in this case in Docker. Nothing more.

# ------------------------------------------------------------------------
# Copyright 2017 WSO2, Inc. (http://wso2.com)
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at|
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License
# ------------------------------------------------------------------------

# set to latest Ubuntu LTS

FROM ubuntu:16.04

MAINTAINER WSO2 Docker Maintainers dev@wso2.org
# set user configurations
ARG USER=wso2carbon
# set dependant files directory
ARG FILES=./files
# set jdk configurations
ARG JDK_ARCHIVE=jdk-8u*-linux-x64.tar.gz
# set wso2 product configurations

# install required packages
RUN apt-get update &&
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends --no-install-suggests
    unzip &&
    rm -rf /var/lib/apt/lists/*

# create a user group and a user
RUN groupadd --system ${USER_GROUP} &&
    useradd --system --create-home --home-dir ${USER_HOME} --no-log-init -g ${USER_GROUP} ${USER}

# copy the jdk and wso2 product distribution zip files to user's home directory

# install the jdk, wso2 server, remove distributions and set folder permissions
RUN mkdir -p ${JAVA_HOME} &&
    tar -xf ${USER_HOME}/${JDK_ARCHIVE} -C ${JAVA_HOME} --strip-components=1 &&
    unzip -q ${USER_HOME}/${WSO2_SERVER_PACK} -d ${USER_HOME}/ &&
    rm ${USER_HOME}/${JDK_ARCHIVE} &&
    rm ${USER_HOME}/${WSO2_SERVER_PACK} &&
    chown -R ${USER}:${USER_GROUP} ${USER_HOME} &&
    chmod -R g=u ${USER_HOME}

# set the user and work directory

# set environment variables

# expose ports
EXPOSE 8280 8243 9763 9443 9099 5672 9711 9611 7711 7611 10397

ENTRYPOINT ${WSO2_SERVER_HOME}/bin/wso2server.sh

In order to make that possible we need to copy the files to the files directory in the directory structure. In this case the apim subdirectory, because there is also an apim-anlytics.

This is the tree

├── docker-compose
│               └── apim-analytics

│               ├── am-2.1.0-pattern-1.png
│               ├── am-analytics
│                                └── carbon
│                                                  └── repository
│                                                                   ├── components
│                                                                                     │   └── lib
│                                                                   └── conf
│                                                                                     └── datasources
│                                                                                                      ├── analytics-datasources.xml
│                                                                                                      └── stats-datasources.xml
│               ├── api-manager
│                  └── carbon
│                                └── repository
│                                                  ├── components
│                                                  │   └── lib
│                                └── conf
│                                                  ├── api-manager.xml
│                                                  ├── carbon.xml
│                                                  ├── datasources
│                                                  │   └── master-datasources.xml
│                                                  └── tomcat
│                                                                   └── catalina-server.xml
│               ├── docker-compose.yml
│               ├── mysql
│                                 └── scripts
│                                ├── apim_mysql5.7.sql
│                                └── carbon_mysql5.7.sql
│               └── README.md
├── dockerfiles
│               ├── apim
│                                ├── Dockerfile
│                                ├── files
│                                │               ├── jdk-8u161-linux-x64.tar.gz
│                                │               └── wso2am-2.1.0.zip
│                                └── README.md
│               └── apim-analytics
│                                ├── Dockerfile
│                                ├── files
│                                └── README.md
├── issue_template.md
├── pull_request_template.md
└── README.md

In order to make all of this work we need to add the JDK and WSO2 APIM to the vagrant environment so it can subsequently be moved to the Docker image.

Add Java 8 JDK

We need to download the Oracle Java JDK 8 and  add it to the files directory.  Use the Java SE Development Kit 8u161 since previous versions (151) had issues with WSO2.

You can download the file from here.

After downloading the file, copy it to the [Docker-Home]/dockerfiles/apim/files directory.

sudo cp jdk-8u161-linux-x64.tar.gz /opt/docker-apim-master/dockerfiles/apim/files

Add WSO2 API Manager

Download the WSO2 API Manager 2.1.0 distribution (http://wso2.com/api-management/try-it/) and copy that to [Docker-Home]/dockerfiles/apim/files .

Build the Docker image.

Navigate to [Docker-Home]/dockerfiles/apim directory.
Execute docker build command as shown below. Do not forget the ‘.’ (dot) at the end of the command.

      docker build -t wso2am:2.1.0 .

Running the Docker image

When you have built the image, the image can be run like this.

docker run -it -p 9443:9443 wso2am:2.1.0

docker run -it- p 9443-9443 wso2am-2.1.0-1.png

Accessing management console

As you can see from the console output the image is running in the Docker Container. In order to access the Management UI we need to access the management console. Since we created a private network, we can use a browser from outside the VirtualBox environment to access the Management UI.

To access the management console, use the docker host IP and port 9443.
API management console - docker.png

More advanced Docker

What we have done now is a straightforward Docker API Manager running in VirtualBox. In the next blog we will look to Docker Compose for starting multiple containers and making changes to our docker container.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product SupportWSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.

Full API lifecycle Management Selection Guide


smartmockups l0qqucke