Deploying the On-Prem Gateway

1. Navigate to <ON-PREM_GATEWAY_HOME>/bin, and execute the following command to configure the On-Prem Gateway:
   On Windows: cloud-init.bat --run
On Linux/Mac OS: sh cloud-init.sh
   This configures the downloaded Gateway with the 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.
   
3. The status of the On-Prem Gateway will be displayed after completion.
   
4. Navigate to <ON-PREM_GATEWAY_HOME>/bin, and execute the following command to run the start up script:
   On Windows: wso2server.bat --run
On Linux/Mac OS: sh wso2server.sh
   The status of the On-Prem Gateway will be updated when you start the gateway.
   

Now you have configured a single On-Prem Gateway instance. Next let's test the deployment.

1. Be sure to download and run two On-Prem Gateway instances.

    Click here for detailed instructions on how to run an On-Prem Gateway instance:

   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.

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

   <Offset>1</Offset>

   Follow the steps below for each of the On-Prem Gateway instances that you downloaded.

   1. Navigate to <ON-PREM_GATEWAY_HOME>/bin, and execute the following command to configure the On-Prem Gateway:
      On Windows: cloud-init.bat --run
On Linux/Mac OS: sh cloud-init.sh
      This configures the downloaded Gateway with the 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.
      The status of the On-Prem Gateway will be displayed after completion.
      
   3. Navigate to <ON-PREM_GATEWAY_HOME>/bin, and execute the following command to run the start up script:
      On Windows: wso2server.bat --run
On Linux/Mac OS: sh wso2server.sh
      The status of the On-Prem Gateway will be updated when you start the gateway.
      

   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.

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

   <Offset>1</Offset>

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.

      sudo openssl genrsa -des3 -out <key_name>.key 1024

   2. Submit the certificate signing request (CSR).

      sudo openssl req -new -key <key_name>.key -out server.csr

   3. Remove the password.

      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.

      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. 

       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 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 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.

      /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:

      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.

      sudo service nginx reload

      sudo service nginx restart

Now you have configured the high availability deployment. Next let's test the deployment.