Kaazing and NGINX – The Best of Both Worlds

Jesse Selitham

Kaazing is well-known for a multitude of products based on the WebSocket IETF and W3C standard.  Using WebSocket allows us to extend different types of asynchronous, message-oriented infrastructure such as JMS and AMQP easily and securely over the web.

NGINX is another awesome tool.  It is one of the world’s most popular, high-powered web servers.  Many of the large websites on the planet prefer NGINX as their webserver of choice.

Wouldn’t it be really cool to combine the secure messaging features of the Kaazing Gateway together with the high performance Nginx web server?  Your hyper fast website would have additional security measures to protect your internal network from unauthenticated users and you’d be able to automagically connect to internal enterprise messaging systems without learning brand-new APIs.

Now that’s a powerful combination.  Let’s setup a deployment to get the best of both.  

We can have incoming WebSocket-based messaging requests passed through an Nginx webserver (proxy) instance to a Kaazing WebSocket Gateway server instance.  Normal incoming HTTP/S traffic would be directly handled by Nginx.

Image may be NSFW.
Clik here to view.

This topology also allows us to avoid exposing the internal URL or private infrastructure information that hosts the Kaazing WebSocket Gateway server (which is a simple Java process btw).

CONFIGURING THE KAAZING GATEWAY

The first step is to download the Kaazing WebSocket Gateway if you haven’t already.  I’m using the standalone JMS Edition 4.0 on Windows that you can find here (Make sure you download the “Gateway + demos” version).  Once you’ve unzipped the file, we’ll want to make one change to the default gateway.config file (gateway-config.xml).  This file is located in the “…\conf” subdirectory below the your install directory.

…\{KAAZING_DIRECTORY}\kaazing-websocket-gateway-jms-4.0.9\conf

Down the middle of the page of the gateway-config.xml file, within the JMS <service> tag, we’ll need to change this (parameterized) line here

<allow-origin>
http://${gateway.hostname}:${gateway.extras.port}
</allow-origin>

This property is enabled for security reasons by default.  This setting will block incoming websocket connections if the request is NOT originating from the specified host (${gateway.hostname}) and port (${gateway.extras.port}).  In a non-proxy topology, you would typically keep the origin URL (typically coming from a browser) set for protection.  But in our case, Nginx will be proxying the connection coming from a different port than the actual origin.  For the purposes of development simplicity, let’s change this setting:

    <allow-origin>*</allow-origin>

Using “*”  allows websocket connections from any origin through to the JMS service.  In production, you will definitely want to strengthen security.  The security documentation for the Kaazing Gateway has detailed information for enhanced security.

STARTING THE GATEWAY AND MESSAGE BROKER

The JMS Edition of the Kaazing Gateway was designed to work out-of-the-box with any JMS 1.1 compliant message broker.   For convenience the binary version of the  popular message broker ActiveMQ is included in the JMS Edition distribution.  In addition, the gateway-config.xml configuration file has a simple, default configuration for ActiveMQ.

Let’s start the Kaazing WebSocket Gateway and the ActiveMQ message broker.  The startup scripts for both are located in the …\bin subdirectory.

…\{KAAZING_DIRECTORY}\kaazing-websocket-gateway-jms-4.0.9\apache-activemq-5.10.0\bin\activemq.bat

…\{KAAZING_DIRECTORY}\kaazing-websocket-gateway-jms-4.0.9\kaazing-websocket-gateway-jms-4.0.9\bin\gateway.start.bat

CONFIGURING NGINX

The last step is to install and configure Nginx.  Setup is very easy.  The installation documentation on the Nginx website can help you.    Below is my configuration for my nginx.conf file.

events {
    worker_connections 1024;
}

http {
    server {
        listen 9000;

        #websocket
        location /jms {
            proxy_pass http://localhost:8001/jms;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
        location / {
            proxy_pass http://localhost:8001;
        }
    }
}

I’ve stripped the Nginx configuration down to the bare minimum.  This configuration simply proxies requests through to the Kaazing Gateway server.  

Now we simply start up Nginx.   

At this point, we have an instance of Nginx acting as a normal webserver handling HTTP requests and also acting as a WebSocket proxy.  The JMS-over-WebSocket requests (identified by “http://localhost:8001/jms” are passed through Nginx and handled by an instance of the Kaazing WebSocket Gateway.  The Gateway takes that connection request and handles it as it would have if there were no proxy and completes the connection to the instance of the ActiveMQ message broker.   Everything is now in place for a full integration test.

TESTING OUR COMPLETE CONFIGURATION

Included with the JMS Edition of the Kaazing Gateway is a simple JavaScript publish/subscribe messaging demonstration.  We can use this demo to test our full setup.  

Start your favorite browser and visit this URL:

http://localhost:9000/demo/jms/javascript/jms.html

If you look in the Location textfield, you will see the URL: ws://localhost:9000/jms

Notice the port we are using here, i.e., 9000.  This is the port that we configured our nginx server to listen on, which means Nginx served up the webpage.  Next click on the Connect button.  If we’ve done everything correctly, we should see “CONNECTED” in the “Log messages” text area to the right.

Image may be NSFW.
Clik here to view.

Voila!  We have successfully allowed a WebSocket connection to pass through Nginx, connect with the Kaazing Gateway and subsequently connect to the back-end ActiveMQ message broker.  I will leave the subscribe and publish fun of the demo app up to you!   

Image may be NSFW.
Clik here to view.

Image may be NSFW.
Clik here to view.