All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: ✉️ Explain Deployment parameters in the docs for Micro Gateway

Please note that this page is WIP.

titleBefore you begin, make sure you have downloaded the following:
  1. Start the API Manager and log in to the API Publisher (https://<hostname>:9443/publisher) using admin as the username and password. 
  2. Create and publish an API (e.g. Petstore).
  3. Log in to the API Store and create an application that supports JWT tokens.

  4. Subscribe to the Petstore API and generate a JWT token to invoke the API.

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

    Code Block
        enable = true
        name = "petstore"
        registry = ''
        tag = 'v1'
        #buildImage = ''
        #dockerHost = ''
        #dockerCertPath = ''
        #baseImage = ''
        #enableDebug = ''
        #debugPort = ''
        #push = ''
        #username = ''
        #password = ''
        enable = true
            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.

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

    Table of Contents


    ParameterDescriptionDefault value
    nameName of the docker image.output balx file name
    registryName of the docker registry.None
    tagThe docker image tag.latest
    buildImageEnable or disable the option to build the docker images.true
    dockerHostDocker host IP and docker PORT. E.g. minikube IP and docker PORTunix:///var/run/docker.sock
    dockerCertPathDocker cert path.null
    baseImageBase image to create the docker image.ballerina/ballerina:latest
    enableDebugEnable or disable debugging.false
    debugPortRemote debug port.5005
    pushEnable or disable pushing the docker image to the remote registry.false
    usernameUsername for docker registry.None
    passwordPassword for docker registry.None


    ParameterDescriptionDefault value
    sourceThe source path of the file (in your local machine).None
    targetThe target path (inside container).None
    isBallerinaConfThe option to flag if file is a ballerina config file.false


  6. 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.
  7. Navigate to the <MICROGW_TOOLKIT_HOME>/bin directory and run the following command,

    Code Block
    ./micro-gw setup <project_name> -a <API_name> -v <version> --deployment-config deployment.toml

    For example,

    Code Block
    ./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 

  8. Build the project using the following command,

    Code Block
    ./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.

  9. Run the docker container using the following command,

    Code Block
    docker run -d<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:

    Code Block
    docker run -d -p 9090:9090 -p 9095:9095<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:

    Code Block
    docker run --network host -d<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.

  10. Retrieve the docker container IP address as follows,

    Code Block
    docker ps - This provides the container id
    docker inspect <Container_ID> | grep "IPAddress"
  11. 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