Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The topics in this section describe how you can quickly configure and test a single node On-Prem Gateway deployment and a high availability deployment scenario. This section walks you through the following Microgateway deployment scenarios:

  • A single node Microgateway deployment.
  • A high availability deployment scenario where you have two Microgateway instances fronted by a load balancer.
Tip

If you want to run the Microgateway on Docker, see Deploying the Microgateway as a Docker Container.

The following topics provide step-by-step instructions to get started with your Microgateway deployment:

Table of Contents
maxLevel3
minLevel3

Anchor
prerequisites
prerequisites
Prerequisites

To download and run the Microgateway: 

Excerpt
  • Ensure that you have the Java SE Development Kit (JDK) installed. You can install either OpenJDK 8 or Oracle JDK 1.8.*.

    Note
    titleImportant!

    WSO2 recommends installing JDK 8u161 or later.

  • Be sure that you meet the following system requirements

...

  • :

    Physical
    • 3 GHz Dual-core Xeon/Opteron (or latest)
    • 4 GB RAM (2 GB for JVM and 2 GB for the operating system)
    • 10 GB free disk space
    • ~ Recommended minimum - 2 Cores.
    Tip

    For high concurrencies and better performance you can use 4 Cores.

    Disk space is based on the expected storage requirement calculated by considering file uploads and backup policies.

    Virtual Machine (VM)
    • 2 compute units minimum (each unit having 1.0-1.2 GHz Opteron/Xeon processor)
    • 4 GB RAM
    • 10 GB free disk space
    • One CPU unit for the operating system and one for JVM.

    ~ 512 MB heap size. This is generally sufficient to process typical SOAP messages but the requirements vary with larger message sizes and the number of messages processed concurrently.

    EC2
    • One c5.large instance to run one

...

    • Microgateway instance.


Download

...

a Microgateway instance

  1. Log Sign in to WSO2 API Cloud (https://api.cloud.wso2.com) as an Admin UserIn admin user.

  2. On the API Publisher, click On-Prem GatewaysMicrogateways.
    Image Removed

    Click Download On-Prem Gateway to

    Image Added

  3. Click DOWNLOAD MICROGATEWAY to start the download.
    Image Removed
  4. You will receive a notification as shown below, when the download begins.
    Image Removed

...

  1. Image Added
    Once the Microgateway download completes, you can configure the

...

  1. Microgateway deployment depending on your use case.

Configure the

...

Microgateway deployment

Depending on your requirement you can either quickly try out the basic single node On-Prem Gateway Microgateway deployment for testing purposes, or you can try out a production level high availability deployment.
Expand
titleClick here for instructions on how to configure a single node On-Prem Gateway Microgateway deployment:
Tip
titleTip

Let’s refer to the On-Prem Gateway Microgateway download location as <ON-PREM_GATEWAY<MICROGATEWAY_HOME> throughout this section.

  1. Navigate to <ON-PREM<MICROGATEWAY_GATEWAY_HOME>/bin, and execute the following command to configure the On-Prem Gatewaystart configuring the Microgateway:
    On - On Windows: cloud-init.bat --run
    On - On Linux/Mac OS: sh cloud-init.sh
    This configures allows you to configure the downloaded Gateway Microateway with the settings required settings to integrate with API Cloud.
  2. Provide your email address, organization key, and password.
    Your organization key will be displayed as shown below.
    Image Removed Image Added
    The status of the On-Prem Gateway Microgateway will be displayed after on completion.
    Image Removed Image Added
  3. Navigate to <ON-PREM_GATEWAY<MICROGATEWAY_HOME>/bin, and execute the following command to run the start up script:
    On - On Windows: wso2server.bat --run
    On - On Linux/Mac OS: sh wso2server.sh
    The Microgateway status of the On-Prem Gateway will be updated when you start the gatewayit starts.
    Image RemovedImage Added

Now you have configured a single On-Prem Gateway Microgateway instance. Next let's The next step is to test the deployment.

Expand
titleClick here for instructions on how to configure a production level high availability deployment scenario:
Tip
titleTip

In this high availability deployment you will have two

On-Prem Gateways (

Microgateway instances running on two nodes

)

fronted by a load balancer

. NGINX will be

as depicted in the following diagram:
Image Added
Here, we will use NGINX is used as the load balancer

.Let’s refer to the On-Prem Gateway download location as <ON-PREM_GATEWAY_HOME> throughout this section

.

  1. Be sure to download and run two On-Prem Gateway Microgateway instances on two different nodes. Let’s refer to each Microgateway download location as <MICROGATEWAY_HOME> throughout this section.

    Expand
    titleClick here for detailed instructions on how to run an On-Prem Gateway instancetwo Microgateway instances:

    Follow the steps below to run each On-Prem Gateway instance on a different nodefor each Microgateway instance that you downloaded.

    Note
    titleNote

    We do not recommend running the two On-Prem Gateway Microgateway instances on a single node for production level high availability deployments.

    1. Navigate to <ON-PREM_GATEWAY_<MICROGATEWAY_HOME>/bin, and execute the following command to configure the On-Prem Gatewaystart configuring the Microgateway:
      On - On Windows: cloud-init.bat --run
      On - On Linux/Mac OS: sh cloud-init.sh
      This configures allows you to configure the downloaded Gateway Microgateway with the settings required settings to integrate with API Cloud.
    2. Provide your email address, organization key, and password.
      Your organization key will be displayed as shown below.:
      Image Added
      Image RemovedThe status of the On-Prem Gateway Microgateway will be displayed after on completion.
      Image Removed Image Added
    3. Navigate to <ON-PREM_GATEWAY<MICROGATEWAY_HOME>/bin, and execute the following command to run the start up script:
      On - On Windows: wso2server.bat --run
      On - On Linux/Mac OS: sh wso2server.sh
      The Microgateway status of the On-Prem Gateway will be updated when you start the gatewayit starts.
      Image RemovedImage Added
  2. Install NGINX in a server configured in your cluster. For instructions on installing NGINX, see installing NGINX community version.
  3. Follow the steps below to create a SSL certificate for NGINX.
    1. Create the server key.

      Code Block
      sudo openssl genrsa -des3 -out <key_name>.key 1024
    2. Submit the certificate signing request (CSR).

      Code Block
      sudo openssl req -new -key <key_name>.key -out server.csr
    3. Remove the password.

      Code Block
      sudo cp <key_name>.key <key_name>.key.org 
      sudo openssl rsa -in <key_name>.key.org -out <key_name>.key
    4. Sign your SSL certificate.

      Code Block
      sudo openssl x509 -req -days 365 -in server.csr -signkey <key_name>.key -out <certificate_name>.crt
    5. Copy the key and certificate files that you generated above to the /etc/nginx/ssl/ location.

  4. Configure NGINX to direct HTTP and HTTPS requests based on your deployment.

    1. Run the following command to identify the exact location of the <NGINX_HOME> directory. 

      Code Block
       nginx -V

      Inspect the output to identify the --prefix tag that provides the location of the <NGINX_HOME> directory.

    2. Update the ngnix.conf file with the required NGINX configuration given below. Alternatively, you can create a file with the .conf suffix and copy it to the <NGINX_HOME>/conf.d directory.

      Note
      titleNote the following with regard to the sample configuration below:
      • /etc/nginx/conf.d/hybrid_gateway_upstream.conf is the NGINX configuration file name.
      • Placeholders <IP1> and <IP2> represent the IP addresses of On-Prem Gateway Microgateway node 1 and node 2 respectively.
      • gateway.foo.com is the domain of the certificate you created in step 2 above. Note that the DNS should be mapped to the NGINX public IP. If you do not do the mapping, the client will have to add an entry in /etc/hosts to resolve the domain name.
      • The key and the certificate for SSL is assumed to be in the <NGINX_HOME>/ssl/ location. The placeholders <cert.pem> and <key.pem> represent the generated certificate file and key file.
      • /etc/nginx/log/wso2_hybrid_gateway/https/ is the directory used for access logs. You need create the directory if it does not exist.
      Code Block
      /etc/nginx/conf.d/hybrid_gateway_upstream.conf 
      upstream gateway_https {
          server <IP1>:8243;
          server <IP2>:8243;
      } 
      
      
      server {
          listen 80;
          server_name gateway.foo.com;
          rewrite ^/(.*) https://gateway_https/$1 permanent;
      }
       
      server {
          listen 443;
          server_name gateway.foo.com;
          proxy_set_header X-Forwarded-Port 443;
          ssl on;
          ssl_certificate /etc/nginx/ssl/<cert.pem>;
          ssl_certificate_key /etc/nginx/ssl/<key.pem>;
          location / {
                     proxy_set_header X-Forwarded-Host $host;
                     proxy_set_header X-Forwarded-Server $host;
                     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                     proxy_set_header Host $http_host;
                     proxy_read_timeout 5m;
                     proxy_send_timeout 5m;
                     proxy_pass https://gateway_https;
              }
       
              access_log /etc/nginx/log/wso2_hybrid_gateway/https/access.log;
              error_log /etc/nginx/log/wso2_hybrid_gateway/https/error.log;
      }
    3. Execute the following command to restart the NGINX server:

      Tip

      You do not need to restart the server if you are simply making a modification to the VHost file. The following command is sufficient in such cases.

      Code Block
      sudo service nginx reload
      Code Block
      sudo service nginx restart

Now you have configured the high availability deployment. Next let's The next step is to test the deployment.

Anchor
TestGateway
TestGateway

Test the deployment

Follow the steps below to test your On-Prem Gateway Microgateway deployment:

  1. Log Sign in to WSO2 API Cloud and create an API.
  2. Subscribe to and invoke the API.
  3. Invoke the API using curl .
    The curl command to invoke the GET method of the API should be similar to the following:

    Code Block
    curl -k -X GET --header 'Accept: text/xml' --header 'Authorization: Bearer dXNlckBvcmcuY29tQHRlc3RPcmcxMjM6UGFzc3dvcmQ=’
    'https://gateway.api.cloud.wso2.com:443/t/ccc2222/phoneverify/1.0.0/CheckPhoneNumber?PhoneNumber=18006785432&LicenseKey=0'

    Replace https https://gateway.api.cloud.wso2.com:443 in the above curl command with your On-Prem Gateway URL as Microgateway URL as indicated below, and then run it. The response to this curl should be identical to that received in the previous step.

    Code Block
    curl -k -X GET --header 'Accept: text/xml' --header 'Authorization: Bearer dXNlckBvcmcuY29tQHRlc3RPcmcxMjM6UGFzc3dvcmQ=’
    'https://on-premise-gateway-ip:8243/t/ccc2222/phoneverify/1.0.0/CheckPhoneNumber?PhoneNumber=18006785432&LicenseKey=0'
    Info

    Note that you can also use the HTTP port for API invocations. The HTTP port number would be 8280 by default. An example is given below.

    Code Block
    curl -X GET --header 'Accept: text/xml' --header 'Authorization: Bearer dXNlckBvcmcuY29tQHRlc3RPcmcxMjM6UGFzc3dvcmQ=’
    'http://on-premise-gateway-ip:8280/t/ccc2222/phoneverify/1.0.0/CheckPhoneNumber?PhoneNumber=18006785432&LicenseKey=0'
    Info

    When you run multiple On-Prem Gateway instances on the same server or virtual machine (VM), you must change the default port of each Gateway with an offset value to avoid port conflicts. An offset defines the number by which all ports in the runtime (e.g., HTTP/S ports) will be increased. For example, if the default HTTPS port is 8243 and the offset is 1, the effective HTTPS port will change to 8244. For each additional On-Premise Gateway instance that you run in the same server or virtual machine, you have to set the port offset to a unique value. The offset of the default port is considered to be 0.

    There are two ways to set an offset to a port:

    • Pass the port offset to the server during start up. The following command starts the server with the default port incremented by 1.
    Code Block
    ./wso2server.sh -DportOffset=1
    • Set the port offset in the Ports section in the <ON-PREM_GATEWAY_HOME>/repository/conf/carbon.xml file as shown below.
    Code Block
    <Offset>1</Offset>
  4. If  your request is successful, your response will be similar to the following.

    Code Block
    <?xml version="1.0" encoding="utf-8"?>
    <PhoneReturn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://ws.cdyne.com/PhoneVerify/query">
      <Company>Toll Free</Company>
      <Valid>true</Valid>
      <Use>Assigned to a code holder for normal use.</Use>
      <State>TF</State>
      <RC />
      <OCN />
      <OriginalNumber>18006785432</OriginalNumber>
      <CleanNumber>8006785432</CleanNumber>
      <SwitchName />
      <SwitchType />
      <Country>United States</Country>
      <CLLI />
      <PrefixType>Landline</PrefixType>
      <LATA />
      <sms>Landline</sms>
      <Email />
      <AssignDate>Unknown</AssignDate>
      <TelecomCity />
      <TelecomCounty />
      <TelecomState>TF</TelecomState>
      <TelecomZip />
      <TimeZone />
      <Lat />
      <Long />
      <Wireless>false</Wireless>
      <LRN />
    </PhoneReturn>

...