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:
| Anchor |
|---|
| prerequisites |
|---|
| prerequisites |
|---|
|
PrerequisitesTo download and run the Microgateway:
...
: | 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
|
|---|
|
...
Download
...
a Microgateway instance
Log Sign in to WSO2 API Cloud (https://api.cloud.wso2.com) as an Admin UserIn admin user.
On the API Publisher, click On-Prem GatewaysMicrogateways.
Image Removed
Click Download On-Prem Gateway to 
Image Added
- Click DOWNLOAD MICROGATEWAY to start the download.
Image Removed - You will receive a notification as shown below, when the download begins.
Image Removed
...
-
Image Added
Once the Microgateway download completes, you can configure the 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 |
|---|
| title | Click here for instructions on how to configure a production level high availability deployment scenario: |
|---|
|
| Tip |
|---|
| In this high availability deployment you will have two On-Prem Gateways two 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. |
Be sure to download and run two Microgateway instances on two different nodes. Let’s refer to
the On-Prem Gateway each Microgateway download location as
<ON-PREM_GATEWAY<MICROGATEWAY_HOME> throughout this section.
Be sure to download and run two On-Prem Gateway instances. | Expand |
|---|
| title | Click here for detailed instructions on how to run an On-Prem Gateway instance: |
|---|
| | 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> |
|
Follow the steps below for each of the On-Prem Gateway instances that you downloaded. Navigate to <ON-PREM_GATEWAY_| two Microgateway instances: |
| Follow the steps below for each Microgateway instance that you downloaded. | Note |
|---|
| We do not recommend running two Microgateway instances on a single node for production level high availability deployments. |
- Navigate to
<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. - 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 - 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 Removed Image Added
|
- Install NGINX in a server configured in your cluster. For instructions on installing NGINX, see installing NGINX community version.
- Follow the steps below to create a SSL certificate for NGINX.
Create the server key. | Code Block |
|---|
sudo openssl genrsa -des3 -out <key_name>.key 1024 |
Submit the certificate signing request (CSR). | Code Block |
|---|
sudo openssl req -new -key <key_name>.key -out server.csr |
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 |
Sign your SSL certificate. | Code Block |
|---|
sudo openssl x509 -req -days 365 -in server.csr -signkey <key_name>.key -out <certificate_name>.crt |
Copy the key and certificate files that you generated above to the /etc/nginx/ssl/ location.
Configure NGINX to direct HTTP and HTTPS requests based on your deployment. Run the following command to identify the exact location of the <NGINX_HOME> directory. Inspect the output to identify the --prefix tag that provides the location of the <NGINX_HOME> directory. 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 |
|---|
| title | Note 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;
} |
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. |
Test the deployment
Follow the steps below to test your On-Prem Gateway Microgateway deployment:
- Log Sign in to WSO2 API Cloud and create an API.
- Subscribe to and invoke the API.
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> |
|
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> |
...