Deploying the API Microgateway in Docker

This documentation is for the API Microgateway component that is coupled with WSO2 API Manager 2.5.0.
View the documentation for the latest release - WSO2 API Microgateway 3.1.0.

Please note that this page is WIP.

Before you begin, make sure you have downloaded the following:

WSO2 API Manager
WSO2 Microgateway ToolKit - version 2.5.0 (WSO2 Microgateway Toolkit is packed with the WSO2 Microgateway Version 2.5.0)

Start the API Manager and log in to the API Publisher (https://<hostname>:9443/publisher) using admin as the username and password.
Create and publish an API (e.g. Petstore).
Log in to the API Store and create an application that supports JWT tokens.
Subscribe to the Petstore API and generate a JWT token to invoke the API.

Create a deployment.toml file containing the relevant deployment configurations such as docker image name, registry, tag, etc. as shown below.

[docker]
  [docker.dockerConfig]
    enable = true
    name = "petstore"
    registry = 'docker.wso2.com'
    tag = 'v1'
    #buildImage = ''
    #dockerHost = ''
    #dockerCertPath = ''
    #baseImage = ''
    #enableDebug = ''
    #debugPort = ''
    #push = ''
    #username = ''
    #password = ''
  [docker.dockerCopyFiles]
    enable = true
    [[docker.dockerCopyFiles.files]]
        source = '<MICROGW_TOOLKIT_HOME>/resources/conf/micro-gw.conf'
        target = '/home/ballerina/conf/micro-gw.conf'
        isBallerinaConf = true

Note that the docker image name must be in lower case.

Click here to see the description for each parameter...

docker.dockerConfig

Parameter	Description	Default value
name	Name of the docker image.	output balx file name
registry	Name of the docker registry.	None
tag	The docker image tag.	latest
buildImage	Enable or disable the option to build the docker images.	true
dockerHost	Docker host IP and docker PORT. E.g. minikube IP and docker PORT	unix:///var/run/docker.sock
dockerCertPath	Docker cert path.	null
baseImage	Base image to create the docker image.	ballerina/ballerina:latest
enableDebug	Enable or disable debugging.	false
debugPort	Remote debug port.	5005
push	Enable or disable pushing the docker image to the remote registry.	false
username	Username for docker registry.	None
password	Password for docker registry.	None

docker.dockerCopyFiles

Parameter	Description	Default value
source	The source path of the file (in your local machine).	None
target	The target path (inside container).	None
isBallerinaConf	The option to flag if file is a ballerina config file.	false

docker.dockerExpose

Copy the micro-gw.conf file to the docker image as it contains the key manager configurations, JWT configurations, etc. This can be done by enabling the docker copy files configuration as shown above.

Let’s create a project called petstore_project and provide the deployment.toml file as an input.
Navigate to the <MICROGW_TOOLKIT_HOME>/bin directory and run the following command,
```
./micro-gw setup <project_name> -a <API_name> -v <version> --deployment-config deployment.toml
```
For example,
```
./micro-gw setup petstore-project -a petstore -v 1.0.0 --deployment-config deployment.toml
```
This commands creates the following folders under the petstore_project folder.
├── petstore_project
│   ├── conf
│   │ └── deployment-config.toml
│   ├── src
│   │ ├── extension_filter.bal
│   │ ├── petstore.bal
│   │ ├── listeners.bal
│   │ └── policies
│   │    ├── application_10PerMin.bal
│   │    ├── application_20PerMin.bal
│   │    ├── application_50PerMin.bal
│   │    ├── subscription_Bronze.bal
│   │    ├── subscription_Gold.bal
│   │    ├── subscription_Silver.bal
│   │    ├── subscription_Unauthenticated.bal
│   │    └── throttle_policy_initializer.bal
│   ├── target
│   └── temp
│       └── hashes.json
└── test.toml
Build the project using the following command,
```
./micro-gw build <project_name>
```
The docker image is created in your local registry and can be used to spawn an API Microgateway docker container.
Run the docker container using the following command,
```
docker run -d docker.wso2.com/<API_name>:<version>
```
If you are working in a Mac environment, start the docker container with the following command to bind the docker container ports to the localhost or the docker host machine:
docker run -d -p 9090:9090 -p 9095:9095 docker.wso2.com/<API_name>:<version>
If you are working in a Linux environment, you can also start the docker container using the host network driver for your container as follows:
docker run --network host -d docker.wso2.com/<api_name>:<version>
For more information on working with Docker in different environments, see the relevant Docker documentation: Docker for Mac, Docker for Windows.
If you are working in a Mac environment, skip step 10.

Retrieve the docker container IP address as follows,

docker ps - This provides the container id
docker inspect <Container_ID> | grep "IPAddress"

Using a REST client or a cURL command, access the API using the following details:

If you are working in a Mac environment, the URL is https://<localhost>:9095/<API_name>/<version>/<resource>.
URL - https://<Container_IP>:9095/<API_name>/<version>/<resource>
Headers - Authorization : Bearer <JWT_TOKEN>
Method - GET

As JWT is a self-contained access token, the Microgateway does not need to connect to the Key Manager. However, if you are using an Oauth2 access token, point the Microgateway to the Key Manager using the Key Manager details in the micro-gw.conf configuration file of the Microgateway. You can provide the Key Manager serverUrl as shown below. The serverUrl has to be accessible from the Microgateway.

[keyManager]
serverUrl="https://localhost:9443"
username="admin"
password="admin"
tokenContext="oauth2"
timestampSkew=5000