If you want to start working with the products from WSO2, there are several possibilities as far as deploying them. You can run them locally on your computer when you are using MacOS, Windows or Linux.
Variations on a theme
Many of these options are variations on the same theme. For instance, when you are running in VirtualBox you are basically running in a hypervised environment. The hypervisor creates an environment that looks like an isolated machine. For instance, you can run a Linux CentOS environment using VirtualBox on your Windows PC. As far as anything running within the CentOS environment it looks like a regular operating system.
Working with Docker
When you are working with Docker it is slightly different. Docker containers are lightweight and do not need a hypervisor, as they will directly access the required kernel routines. On Windows you can also run Docker. However, you need the Windows Subsystem for Linux installed on Windows.
We can use Docker to quickly spin up WSO2 instances using the WSO2 Docker repo that is available for registered users of the WSO2 website. In this blog I am going to show you how you can quickly set up a simple API Manager using Docker and Docker compose. Let us start with some explanation about what is inside a Docker container.
What is inside a Docker container?
A Docker container is based off of a Docker image. The Docker image consists of ‘layers’ and several layers make a base from which other users of that image can start building their container. The Docker images created by WSO2 consist of a minimal install with tools like bash, some other tools and of course a WSO2 product. There are multiple types of Docker images available, each with a specific version and type of WSO2 product.
How to look inside a Docker container
There are several ways in which we can look inside a Docker container and one of this is to use the docker command-line tool that comes with Docker.
We can access the container by opening a command-line shell in it. This shell is started from within the container but is visualized on your command-line. This allows you to interact with the container as if you are logged into it through an SSH session.
In order to open up a shell to a running Docker container, we should first start it and then identify the container by its ID or name. When we know which container we need, then we can open up a shell and look inside.
The commands that I am using are all standard Docker commands. I am assuming that we have a running Docker container.
Typing docker ps will show you the running containers. Adding ‘-a’ to the command will also show non running containers (I am only showing the relevant container).
| CONTAINER ID | IMAGE | COMMAND | CREATED | STATUS | PORTS | NAMES |
| 8a787ffa823e | fbbec18d601c | “/home/wso2carbon/do…” | About an hour ago | Up About an hour | 5672/tcp, 8243/tcp, 8280/tcp, 9099/tcp, 9443/tcp, 9611/tcp, 9711/tcp, 9763/tcp, 9999/tcp, 11111/tcp | wso2apim-320 |
Now that we know the container ID, we can use that to execute bash inside the container. The number will be unique for your container. The command is quite simple:
docker exec -it 8a787ffa823e bash
As you can see, we now have a command line interface that we can use to look inside the container. Traversing the directory tree, we can see that there is an API Manager installed at /home/wso2carbon/wso2am-3.2.0
Alternatives to a Docker, Portainer
An alternative to the Docker command-line is a graphical user interface called Portainer. According to its website, Portainer is a ‘universal’ container management tool for Kubernetes, Docker, Docker Swarm and Azure ACI. This GUI lets you manage containers without having to know the docker commands. When you’d like to stay away from the command-line then this can be handy.
So, the beauty of Portainer is that it will actually run in a container. So, there is no install and there are little downloads to be done. And basically, you can have your Portainer up and running within minutes. Portainer provides install instructions that are simple to follow and to show how easy this is, follow along.
Portainer needs a location where it can store some persistent data. In docker terms this is called a ‘volume’. A volume can either be managed by docker or you can point docker to a location of your choice to any folder on your filesystem. To simplify matters and let docker manage the volume for us we first create a volume for Portainer.
docker volume create portainer_data
When the volume is there, then we can start portainer with the following command:
docker run -d -p 8000:8000 -p 9000:9000 –name=portainer –restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce
In a nutshell, we tell docker to run a container in the background, based on the portainer/portainer-ce image, and we specify some ports through which we want to access the portainer GUI. There are two volumes configured so that portainer can access the docker-management information and store some things it needs to run.
When the container is started, you can use the docker ps command I mentioned earlier. Then you can access the interface via the browser on localhost via http://localhost:9000/#!/home.
This is the interface:
If there are other containers running on your Docker installation, you will see them in a list as shown in above screenshot.
In the third column of that list there are four icons: Logs, Inspect, Stats and Exec Console.
Logs will show the docker console output, Inspect gives insight into the container details. Stats shows among others the memory and CPU usage and Exec allows the start of a terminal into the container.
When we run a WSO2 container, then the docker console output will show the WSO2 carbon log output.
How do we start a WSO2 Docker image?
Now that we have portainer running, we can start the latest (image-)version of the WSO2 API Manager container with the following command:
docker run -d -p 9443:9443 -p 8280:8280 -p 8243:8243 –name WSO2AM320 wso2/wso2am:latest
This will make the container run detached (i.e., in the background and will get the name WSO2AM320) and will allow you to access the ports 9443,8280 and 8243 from your system. If you don’t specify these ports, then you cannot access the WSO2 API Manager Management console.
Running the container in detached mode also causes us to not see the console output.
When you execute the above command, a containerID will be shown. We can use that ID to see the console output. Use the following command and substitute my ID with yours:
docker logs -f 8a787ffa823e
When we use the browser, we can see the API Manager Management console and sign into the API Manager.
Docker compose
In the above examples we can see that the docker commands can get quite long and cumbersome to construct. You could put these commands in a start script to simplify things or you can use docker-compose.
Docker-compose enables you to specify services in docker-compose.yml file. Each service is a container with a configuration. You can specify multiple services in a single file and thus you can start multiple containers with a single command.
For now, we can make life a little easier by just specifying the configuration of the WSO2 API Manager container above, with all configurations that we want it to use.
To make things a little more interesting let’s apply some small custom configuration to the WSO2 API Manager installation and let’s change the port offset.
I am manipulating one file: the deployment.toml file. There I made a change to the port offset.
I then created a docker-compose.yml file and created a config/wso2am subfolder. In that subfolder this deployment.toml file is placed.
Below you can see my docker-compose.yml file. There is a service named ‘apimanager’ that is based off of the wso2/wso2am:latest image and I specified three ports that I want to map from my machine into a port that WSO2 opens when it starts.
To override the deployment.toml that ships a volume into the location where the deployment.toml is stored inside the container, with the image I specified where I mapped the file from my machine’s location (./config/wso2am/deployment.toml).
The weak link is of course the fact that I am using WSO2 latest, but am referring to a specific version (i.e., 3.2.0) location in the container. If the ‘latest’ version changes to another version, then the volume-mapping may no longer be valid.
I start the composition using docker-compose up.
Some logs start showing and as you can see in the top line the offset is now applied, giving a URL of https://localhost:9453/publisher, rather than the regular 9443 for an offset of zero. I am able to log in to the WSO2 API Manager Management console and can work with the API Manager in Docker!
Yenlo is the product leader and multi-award winner in WSO2, Boomi, MuleSoft and Microsoft Azure technologies and offers best-of-breed solutions from multiple leading integration vendors.
With over 240+ experts in the API, integration, and Identity Access Management domain and over $35 million in annual revenue, Yenlo is one of the largest and best API-first and Cloud-first integration specialists worldwide.
