Deploying the API Microgateway in Docker

WSO2 API Microgateway has a runtime Docker image in which you can provide executable runtime artifacts as a mount. Let's follow the instructions below to see how we can create Docker image by including the runtime executable artifacts, so that you do not have to mount the artifacts from outside. This approach uses the deployment-config.toml file as an input to the WSO2 API Microgateway Toolkit, which generates the Docker images from the WSO2 API Microgateway base image by including all the API runtime artifacts as well.

Let's deploy WSO2 API Microgateway in Docker.

Step 1 - Follow the installation prerequisites

Make sure to install and set up Docker and the installation prerequisites for the Microgateway Toolkit.

Step 2 - Create a microgateway project

Navigate to a preferred workspace folder using the command line to set the location that is used to store the Microgateway project.
Create a project.
Let's create a project named "petstore" by running the following command. This will create the folder structure for the artifacts to be included.
Format
```
micro-gw init <project_name> 
```
Example
```
micro-gw init petstore  
Project 'petstore' is initialized successfully.
```

Step 3 - Build the microgateway project

Add the API to the project.
Navigate to the /petstore/api_definitions directory and add the OpenAPI definition(s) to this directory. Let's use the Petstore sample OpenAPI definition in this scenario.
Create the input for WSO2 API Microgateway Toolkit.
Create a file named deployment.toml in a preferred location.This TOML file should contain the relevant deployment configurations (e.g., Docker image name, registry, tag, etc.) as shown below. For more information on each of the above parameters, see deployment.toml for Docker. Note that you will have to use this TOML file as the input, by way of passing the file path, when creating the Microgateway project.
```
[docker]
  [docker.dockerConfig]
    enable = true
    name = "petstore"
    registry = 'docker.wso2.com'
    tag = 'v1'
    #buildImage = ''
    #dockerHost = ''
    #dockerCertPath = ''
    baseImage = 'wso2/wso2micro-gw:3.0.2'
    #enableDebug = ''
    #debugPort = ''
    #push = ''
  [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
```
Specify docker credentials

If the docker image push is enabled to push the image to a docker registry , specifying of the username and password should be done using environment variables

export DOCKER_USERNAME=<USER>
export DOCKER_PASSWORD =<PASSWORD>
Build the microgateway project.
Use your command line tool to navigate to where the project directory ("petstore") was created and execute the following command to build the project.
Format
```
micro-gw build <project_name> --deployment-config <path-to-the-deployment.toml>
```
Example
```
micro-gw build petstore --deployment-config /Users/kim/Downloads/deployment.toml
```
The Docker image is created in your local registry and you can use it to spawn a WSO2 API Microgateway Docker container.

Step 4 - Run the Docker container

Run the Docker container using the following command.

docker run -d -p 9090:9090 -p 9095:9095 docker.wso2.com/<docker_name>:<docker_tag>

When following this Docker deployment guide, you will end up by creating a Docker image with APIs built into it; thereby, the .balx file will already be inside the Docker image. Therefore, unlike in the Quick Start Guide for Docker you do not have to specify the project name when running the Docker container and mount the .balx file in to the Docker image.

If you are working in a Linux environment, you can either use the above command or the following command to start your Docker container. In the following command the Docker container uses the host network driver for your container.

docker run --network host -d docker.wso2.com/<docker_name>:<docker_tag>

For more information on working with Docker in different environments, see the relevant Docker documentation: Docker for Mac, Docker for Windows.

Step 5 - Invoke the sample API

Step 5.1 - Obtain token

After the APIs are exposed via WSO2 API Microgateway, you can invoke an API with a valid JWT token or an opaque access token.
In order to use JWT tokens, WSO2 API Microgateway should be presented with a JWT signed by a trusted OAuth2 service.
Let's use the following sample JWT token that never expires, which was generated using WSO2 API Manager for testing purposes.

JWT Token

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==

More information

You can obtain a JWT token from any third-party secure token service or via the WSO2 API Manager.
Alternatively, you can also use an OAuth2 token to invoke the API.

For more information, see the FAQs on Working with Tokens.

Step 5.2 - Invoke the API

Invoke the API using the JWT token using the following command.

Retrieve the Docker container IP address.

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

Execute the command below to set a self-contained OAuth2.0 access token in the JWT format as a variable on your terminal session.

Format

TOKEN=<JWT-token>

Example

TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==

When you are deploying the Microgateway in production, make sure to change its default certificates.

You can now invoke the API running on the Microgateway using the following cURL command.

Format

curl -X GET "<container_IP>:<MGW-runtime-port>/<API-context>/<API-resource>" -H "accept: application/xml" -H "Authorization:Bearer <JWT_TOKEN>" -k

Examples

curl -X GET "https://localhost:9095/petstore/v1/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

curl -X GET "https://localhost:9095/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k