• Events
  • Blog
  • W3C
Kaazing in action
websockets.org

Getting Started

Welcome to Kaazing WebSocket Gateway! This document explains how to get up-and-running with Kaazing WebSocket Gateway, a process that should not take longer than 5 minutes. This document contains the following sections:

Refer to Release Notes for a list of new features in this release.

System Requirements

The following are the minimum system and software requirements for running the Kaazing WebSocket Gateway demo bundle:

Operating System

  • Windows: Windows 7, Windows Vista, Windows XP SP3
  • Unix: Ubuntu Linux or any Unix or Linux platform that is certified with Java 1.6.0_14 (Java 6)

Environment

  • Java Developer Kit (JDK) 1.6.0_14 or greater.
  • The JAVA_HOME environment variable must be set to the directory where the JDK is installed, for example C:\Program Files\Java\jdk1.6.0_14.

Browser Certification

Refer to Release Notes for an overview of the certified browser versions for this release.

Installing the Kaazing WebSocket Gateway Demo Bundle

After you have downloaded the Kaazing WebSocket Gateway demo bundle, unpack the distribution into a directory of your choice (for example, C:\kaazing or /home). This top level directory, referred to as KAAZING_HOME in the Kaazing documentation, contains the Kaazing WebSocket Gateway directory, for example, C:\kaazing\kaazing-websocket-gateway. This directory contains Kaazing WebSocket Gateway and its components and is referred to as GATEWAY_HOME in the Kaazing documentation.

Note: Standard Unix Tar does not always handle long pathnames correctly (this is a well-known issue), so it is better to use GNU Tar. GNU Tar is the default on Linux but on Solaris and OpenSolaris (or any other non-Linux platforms) it is best to start GNU Tar from the directory /usr/gnu/bin/tar.

Starting the Kaazing WebSocket Gateway Demo Bundle

To see the demos in action, you must start Kaazing WebSocket Gateway. To do this, perform the following steps in a shell or command prompt:

  1. Navigate to GATEWAY_HOME/bin.
  2. Run gateway.start (Linux) or gateway.start.bat (Windows).
  3. Optionally, run the news.start (Linux) or news.start.bat (Windows) script to start the newsfeed data source.

(Step 3 is required to view the Server-Sent Events demo.)

When you successfully start Kaazing WebSocket Gateway, messages similar to the following example INFO messages display in your shell or command prompt:

INFO  Checking license information
INFO    No valid license found, see http://kaazing.com/license
INFO    Node-ID file can be found at: C:\kaazing\license\mycomputer.id
INFO  Starting in development mode
INFO Starting server
INFO Starting services
INFO http://localhost:8000/
INFO http://localhost:8000/keyring
INFO http://localhost:8000/session
INFO https://localhost:9000/
INFO https://localhost:9000/keyring
INFO https://localhost:9000/session
INFO sse://localhost:8000/sse
INFO sse+ssl://localhost:9000/sse
INFO ws://localhost:8001/echo
INFO wss://localhost:9001/echo
INFO Started services
INFO Starting management
INFO jmx://localhost:2020/
INFO Started management
INFO Started server successfully in 0.123 secs at 2010-06-06 22:22:00

Configuring Kaazing WebSocket Gateway

You can perform additional gateway configuration by modifying settings in the file GATEWAY_HOME/conf/gateway-config.xml. For example, you can change accept host names and ports and add authorization constraints for services. For more information about gateway configuration, security, and monitoring tasks, see the Administrator's Guide.

Verifying the Installation

To verify that Kaazing WebSocket Gateway is up-and-running, open a browser and access the Kaazing WebSocket Gateway home page at http://localhost:8000/. The Kaazing WebSocket Gateway home page displays. Click the Documentation tab to see the documentation library. Refer to the Documentation page for additional information about Kaazing WebSocket Gateway. Click the Demos tab to see the demos.

Moving Beyond Localhost

Installing the gateway on your machine and then accessing it with a browser running on that same machine is fine for testing purposes, but you'll probably want to do more than that soon. For example, you may want to have others access your gateway on an internal network or over the Internet. Some additional configuration is required to achieve that. This section contains the most common uses cases and instructions (or pointers to instructions) on how to configure the gateway for those scenarios, to get you up-and-running quickly. Configuration is performed by updating the file GATEWAY_HOME/conf/gateway-config.xml. You must restart the gateway after making changes.

Accepting Connections at a Non-Localhost IP Address or Host Name

Kaazing WebSocket Gateway demo services in the demo bundle are configured to accept connections on localhost by default.  The cross-origin sites allowed to access those services are also configured for localhost-only by default. If you want to accept connections on a non-localhost IP address or host name you must update your gateway configuration to accept connections at that IP address or DNS name.

In addition, you must specify the IP address or DNS name of the the page from which a service is accessed in a cross-site constraint. Cross origin access to back-end services is denied by default and cross-site constraints allow you to "white-list" the origin (an origin consists of a protocol scheme, a fully qualified host name, and a port number) of the cross-origin site that is allowed to access the service. Using Cross-Origin Resource Sharing therefore provides a way to explicitly and securely allow a cross-origin site access to a back-end service.

The following example shows a default Echo service definition, using localhost.

<!-- Proxy service to Echo server -->
<service>
  <accept>ws://localhost:8001/echo</accept>
  <type>echo</type>
  .
  .
  .
  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

The following example shows how that service can be reconfigured to allow access to a back-end service at the URL ws://www.example.com on port 8000 from the page http//www.example.com on port 8001.

<!-- Proxy service to Echo server -->
<service>
  <accept>ws://www.example.com:8001/echo</accept>
  <type>echo</type>
  .
  .
  .
  <cross-site-constraint>
    <allow-origin>http://www.example.com:8000</allow-origin>
  </cross-site-constraint>
</service>

Alternatively, you can also use an IP address, as shown in the following example.

<!-- Proxy service to Echo server -->
<service>
  <accept>ws://192.0.2.1:8001/echo</accept>
  <type>echo</type>
  .
  .
  .
  <cross-site-constraint>
    <allow-origin>http://192.0.2.1:8000</allow-origin>
  </cross-site-constraint>
</service>

Note: Configure the service accept element to use the exact name that clients will use to access it. You can use multiple accept elements.

Refer to the section the section titled "Description of the gateway-config.xml Configuration Elements" in the Administrator's Guide for more information.

Configuring Kaazing WebSocket Gateway on an Internal Network behind Firewalls, Load-Balancing Routers, or in the Cloud

When a firewall or load-balancing router front-ends Kaazing WebSocket Gateway or when you configure the gateway in the cloud, DNS will usually resolve to the public IP address of an intermediary device, which is in turn configured to forward requests to Kaazing WebSocket Gateway on an internal network. By default, Kaazing WebSocket Gateway resolves the local interface address by looking up the DNS name, which in this case does not represent the local network interface, resulting in a failure to serve requests. To override the gateway's default behavior, you must use the network configuration address-mapping element. Refer to the section the section titled "Configuring Network Address Mapping" in the Administrator's Guide for more information.

Configuring a Web Server to Integrate with Kaazing WebSocket Gateway

If you are hosting your web application on a separate web server, such as Apache HTTP Server or Microsoft IIS, then cross-origin access using HTML5 Cross Document Messaging (the PostMessage API) is required for those applications to connect to Kaazing WebSocket Gateway. Microsoft Internet Explorer versions 6 and 7 do not support communication across origins and require additional configuration on the web server. To configure this, perform the steps documented in the section titled "Configuring a Web Server to Integrate with Kaazing WebSocket Gateway" in the Administrator's Guide.

Upgrading Your License

The developer's version of the Kaazing WebSocket Gateway demo bundle allows only a limited number of concurrent client connections. To upgrade your license, contact sales@kaazing.com. After you place a valid license key in GATEWAY_HOME/license, messages similar to the following example INFO messages display in your shell or command prompt at server startup:

INFO  Checking license information
INFO    Valid license found for: Joe User, Example Corporation, joe@example.com
INFO    License expires on 06 Jun 2044
INFO  Starting in licensed mode

Next Steps

To get more familiar with with Kaazing WebSocket Gateway, take a look at the additional documentation and run some of the preconfigured demos.