Click here to toggle all content on this page

Setting Up Kaazing WebSocket Gateway

This guide helps you set up Kaazing WebSocket Gateway in your environment.

I want to use Kaazing WebSocket Gateway:

...on my computer
Local Setup
...within my intranet or enterprise
Server Setup
...on the cloud
Cloud Setup

Installation

...integrated with my HTTP server
HTTP server configuration
...and secure my WebSocket traffic
Secure configuration
...and configure high availability
HA configuration
...and perform advanced configuration
Advanced configuration

Configuration

Setting Up Kaazing WebSocket Gateway Locally on My Computer

Setting up Kaazing WebSocket Gateway on your local computer is recommended if you want to quickly try out the Gateway. Let's get started!

A Localhost configuration for Kaazing WebSocket Gateway
Figure: A Localhost Configuration for Kaazing WebSocket Gateway

To set up the Gateway on your local computer, perform the following steps:

  1. Ensure your system meets the system requirements.

    For specific environment and operating system information, see the README.txt file.

  2. Download Kaazing WebSocket Gateway for your platform from the Kaazing download page.
    What are my download options? 

    The following matrix shows the download options available for each operating system platform.

    Operating System Installer

    Installs in conventional operating system locations; runs the Gateway as a service
    Compressed File (zip or tar.gz)

    Uncompress to any directory and run in place; runs the Gateway standalone, not as a service
    Install Via Repository

    Add the Kaazing repository to your Linux repositories; runs the Gateway as a service
    Windows 64-bit(1) or 32-bit(2)
     
    N/A
    Linux (Debian)  
    All Linux, UNIX, and Mac
    N/A
    N/A

    1The 64-bit Windows download requires 64-bit Java JDK or JRE that can be installed only on Windows 64-bit operating systems.

    2The 32-bit Windows download requires 32-bit Java JDK or JRE. Note: You can install the 32-bit JVM on a 64-bit or 32-bit operating system. To determine if your JVM is 64-bit or 32-bit, enter java -version at the command-line prompt. Typically, "64-bit" is reported for a 64-bit JVM, but nothing is reported if the JVM is the 32-bit version.

    For each option except “Install via repository” you can download either the Gateway Only or Gateway + Documentation + Demos:

    • Gateway Only downloads: Contain only the Gateway for experienced users who are ready to use the Gateway in production.
    • Gateway + Documentation + Demos downloads: Contain the Gateway plus documentation and demo-services that provide sample data for some of our demos. This download provides a great way to become familiar with the Gateway.
  3. Install the Gateway for your platform either by running one of the Gateway installers or by unpacking a compressed download of the Gateway.

    You can use the Windows or Linux installer to install the Gateway into conventional operating system locations and automatically run the Gateway as a service. If you choose to unpack the .zip for Windows or .tar.gz for Linux, UNIX, or Mac), then you can uncompress the Gateway to any directory location and run it in place.

    How do I install the Gateway using the Windows installer?

    Windows (32-Bit or 64-Bit) Installation

    1. Login to your Windows machine using an account that has administrator privileges.
    2. Invoke the Kaazing WebSocket Gateway Windows Installer Setup Wizard either by double-clicking the kaazing-websocket-gateway-html5-3.5.x-x64.msi file that you downloaded or by running it with the msiexec /i command at the command prompt.
    3. Follow the steps in the setup wizard and note the following:
      • You cannot install both Windows 64-bit and 32-bit of the same Gateway on the same machine.
      • On the Java Installation Directory page, you are prompted to enter the root directory of your Java JDK or JRE software installation. For example: C:\Program Files\Java\jdk1.6.0_29\. Before the Gateway is installed, the setup wizard verifies that the Java installation directory is valid (for example, C:\temp is invalid), but the wizard does not validate if it is a 64-bit or a 32-bit Java installation. Important: Choose a Java installation that matches the word size (64-bit or 32-bit) of the Windows installer you are running. To verify that the Gateway started correctly as a service, look at the log file in GATEWAY_HOME/log/service.log that is generated when the service is started or stopped.
      • The default installation includes the Gateway, the documentation, and the demos.
    4. The setup wizard installs the Gateway and adds the new files in the GATEWAY_HOME.

      GATEWAY_HOME: The installer creates the default GATEWAY_HOME destinations as follows:

      • For 64-bit and 32-bit Windows systems:
        C:\Program Files\Kaazing\html5\3.5\Gateway
      • For a 32-bit installation on a 64-bit Windows system:
        C:\Program Files (x86)\Kaazing\html5\3.5\Gateway

      Gateway Service: The Gateway service starts automatically and verifies that the Java installation directory that you supplied to the setup wizard is a valid 64-bit or a 32-bit Java installation. Errors are recorded in the Kaazing service log (C:\Program Files\Kaazing\html5\3.5\Gateway\log\service.log).

      Patching: When running the Windows Installer Setup Wizard to install a Gateway patch, the installation process does not overwrite user-modified files under the GATEWAY_HOME/conf directory when the patch is applied. However, any unmodified files might be overwritten by newer replacement files. See the Release Notes (online only) for information about what changes occurred in each release.

      Upgrading: When running the Windows Installer Setup Wizard to install the next release of the Gateway, the newer release is installed in a separate directory that is at the same level in the directory structure as the earlier release. Earlier releases of the Gateway are not overwritten or removed. For example, html5\3.4 and html5\3.5 are separate but parallel directories. Note that you cannot run both releases at the same time unless you change the ports on one or the other. See the Release Notes (online only) for information about what changes occurred in each release.

    5. If you installed the Base product, then none of the default services are automatically started. You must manually start your desired services.
    How do I install the Gateway using the Debian-based Linux installer?

    Debian-based Linux Installation

    1. Install the Gateway either by double-clicking the Debian installer for the Gateway, or by entering the dpkg -i kaazing-gateway-package-name.deb command, where package-name is the Gateway package you downloaded. For example:

      sudo dpkg -i kaazing-gateway-html5-3.5-3.5.x.y.deb
      sudo dpkg -i kaazing-gateway-html5-3.5-extras-3.5.x.y.deb

      Notes: For Linux systems, the Documentation and Demos download requires that you install the Gateway Only download first.
      • You may choose to install the Gateway Only download and then the Documentation and Demos download, or install both using the Install via repository option. To download and install the Linux repository, click the "Install via repository" button and follow the instructions on the Gateway Download page.
      • If you accidentally install Documentation and Demos before you install the Gateway Only download, then the installation stops and displays an error message. For example: dpkg: dependency problems prevent configuration of kaazing-gateway-html5-3.5-extras. If you get this error, then install the Gateway Only download before installing Documentation and Demos.
       
    2. The installation creates the Gateway directory structure and starts the Gateway automatically.
       

      The installer creates the Gateway directory structure following the Linux Filesystem Hierarchy Standards.

      Directory Description Patches and Upgrades
      /usr/share/kaazing/html5/3.5/

      (Read only) Also known as GATEWAY_HOME. Contains the libraries and scripts to run the Gateway.

      Files might be overwritten or deleted.
      /var/lib/kaazing/html5/3.5/

      (Read/write) Contains the web content and libraries for the Gateway. If you installed "Extras" then the web directory contains the documentation and demos.

      User files are not overwritten or deleted but files in the extras folder may be overwritten or deleted.

      /etc/kaazing/html5/3.5/

      (Read/write) Contains the Gateway configuration files and the license file.

      Modified files are not overwritten or deleted.
      /var/log/kaazing/html5/3.5/

      Contains the log files.

      Files are not overwritten.

      Patching: When you eventually run the Linux installer to patch your Gateway software to a newer release, the installation process preserves user-modified files while the configuration is upgraded to the latest release of the Gateway. See the Release Notes (online only) for information about what changes occurred in each release.

      Upgrading: To upgrade the Gateway, the newer release is installed in a separate directory that is at the same level in the directory structure as the earlier release. Earlier releases of the Gateway are not overwritten or removed. For example, html5/3.4 and html5/3.5 are separate but parallel directories. Note that you cannot run both releases at the same time unless you change the ports on one or the other. See the Release Notes (online only) for information about what changes occurred in each release.

    3. If you installed the Base product, then none of the default services are automatically started. You must manually start your desired services.
    How do I unpack the compressed download of the Gateway (.zip for Windows or .tar.gz for Linux, UNIX, or Mac)

    On Windows you can unpack the Gateway .zip file using Windows Explorer, and on Linux, UNIX, or Mac you can unpack the .tar.gz file with the tar xvfz tar-file-name.tar.gz command.

    Standard UNIX Tar does not always handle long path names correctly (this is a 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 (gtar) from the directory /usr/gnu/bin/gtar or by using one of its links: /usr/bin/gtar or /usr/sfw/bin/gtar.

  4. Start the demo services by navigating to the GATEWAY_HOME/bin directory and running the demo-services.start (Linux) or the demo-services.start.bat (Windows) script. Note: Remember that the documentation and demos are included only with the "Gateway + Documentation + Demos" download.
    How do I start the demo services?

    On Windows:

    1. In Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.
    2. Either double-click the demo-service.start.bat file in Windows Explorer, or use the following command to start the demo services and substitute the public IP address or the public DNS name for example.com:

      demo-services.start.bat udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

    On Linux, UNIX, or Mac:

    1. Navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.

      In the following example, edition refers to the Product Edition (for example, html5 or jms) and version refers to the version number (for example, 3.5.x):

      cd /home/username/kaazing/kaazing-websocket-gateway-edition-version/bin

    2. Use the following command to start the demo services, and substitute either the public IP address or the public DNS name for example.com:

      demo-services.start udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

  5. Ensure Kaazing WebSocket Gateway is running. If you installed the Gateway using the Windows or Linux Installer, then the installer starts the Gateway automatically.

    How do I start and stop the Gateway?

    To Start the Gateway on Windows

    Use the Windows Services Manager or use one of the following commands at the command prompt with administrator rights:

    • For 64-bit JVM: net start KaazingHTML5v35x64Service
    • For 32-bit JVM: net start KaazingHTML5v35x86Service

    Alternatively, in Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway and double-click the gateway.start.bat script.

    To Start the Gateway on Linux, UNIX, or Mac

    Use either of the following methods:

    • Use Linux or Ubuntu commands
      • For Linux:
        sudo service kaazing-html5-3.5 start
        sudo service kaazing-html5-3.5 restart
      • For Ubuntu (Upstart):
        sudo start kaazing-html5-3.5
        sudo restart kaazing-html5-3.5


        To include a configuration file name on the start command, use the config option:

        sudo start kaazing-html5-3.5 config=/tmp/my-config.xml
    • Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-html5-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.

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

    INFO Kaazing WebSocket Gateway (3.5.x)
    INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml
    INFO Checking license information
    INFO Found license: Developer License, Maximum 50 connections, See LICENSE.txt
    INFO Starting server
    INFO Starting services
    INFO http://localhost:8000/
    INFO http://localhost:8001/
    INFO http://localhost:8001/session
    INFO http://localhost:9000/
    INFO sse://localhost:8001/sse
    INFO ws://localhost:8001/echo
    INFO Started services
    INFO Starting management
    INFO jmx://localhost:2020/
    INFO Started management
    INFO Started server successfully in 0.321 secs at 2044-06-06 22:22:00

    Note: The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Troubleshoot Kaazing WebSocket Gateway Configuration and Startup topic for more information.

    To Stop the Gateway on Windows

    Use the Windows Services Manager, press CTRL + C at the command prompt that was used to start the Gateway or simply close the command prompt, or use the net stop command to stop the Gateway service. See the Windows Server documentation for more command-line information.

    To Stop the Gateway on Linux, UNIX, and Mac

    Kill the process at the command line, or use the Linux or Ubuntu (Upstart) service stop command (for example, sudo service kaazing-html5-3.5 stop).

  6. Verify the Gateway setup by navigating to http://localhost:8000/ in your browser.
    How do I verify that the Gateway is running?

    To verify that the Gateway is up and running, open a browser and access the Gateway home page at http://localhost:8000/. If you downloaded the Gateway + Documentation + Demos download, then click the Documentation tab to see the documentation library and learn more about the Gateway. Click the Demos tab to view the demos.

    A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Documentation + Demos download. If you want to configure your own back-end service, see the Advanced configuration service and the client how-to guides on the Kaazing Documentation home page for more information.

    See the Release Notes (online only) for an overview of the certified browser versions for this release of the Gateway.

You are now done setting up Kaazing WebSocket Gateway locally. To uninstall the Gateway, see the Uninstall Kaazing WebSocket Gateway section at the end of this document.

Setting Up Kaazing WebSocket Gateway on a Server

You can override the Gateway default behavior and accept connections on a non-localhost host name or IP address. The following figure shows a server configuration in which multiple browser clients communicate via the Gateway and a back-end application located on a separate host at a different physical location. For custom protocol configurations, the back-end service is optional.

For more information about configuration settings and to perform additional Gateway configuration, see the Understanding Kaazing WebSocket Gateway Configuration Files, Elements, and Namespaces documentation topic.

This graphic shows a server configuration for Kaazing WebSocket Gateway
Figure: A Server Configuration for Kaazing WebSocket Gateway

To set up a server configuration, perform the following steps:

  1. Ensure your system meets the system requirements.

    For specific environment and operating system information, see the README.txt file.

  2. Download Kaazing WebSocket Gateway for your platform from the Kaazing download page.
    What are my download options? 

    The following matrix shows the download options available for each operating system platform.

    Operating System Installer

    Installs in conventional operating system locations; runs the Gateway as a service
    Compressed File (zip or tar.gz)

    Uncompress to any directory and run in place; runs the Gateway standalone, not as a service
    Install Via Repository

    Add the Kaazing repository to your Linux repositories; runs the Gateway as a service
    Windows 64-bit(1) or 32-bit(2)
     
    N/A
    Linux (Debian)  
    All Linux, UNIX, and Mac
    N/A
    N/A

    1The 64-bit Windows download requires 64-bit Java JDK or JRE that can be installed only on Windows 64-bit operating systems.

    2The 32-bit Windows download requires 32-bit Java JDK or JRE. Note: You can install the 32-bit JVM on a 64-bit or 32-bit operating system. To determine if your JVM is 64-bit or 32-bit, enter java -version at the command-line prompt. Typically, "64-bit" is reported for a 64-bit JVM, but nothing is reported if the JVM is the 32-bit version.

    For each option except “Install via repository” you can download either the Gateway Only or Gateway + Documentation + Demos:

    • Gateway Only downloads: Contain only the Gateway for experienced users who are ready to use the Gateway in production.
    • Gateway + Documentation + Demos downloads: Contain the Gateway plus documentation and demo-services that provide sample data for some of our demos. This download provides a great way to become familiar with the Gateway.
  3. Install the Gateway for your platform either by running one of the Gateway installers or by unpacking a compressed download of the Gateway.

    You can use the Windows or Linux installer to install the Gateway into conventional operating system locations and automatically run the Gateway as a service. If you choose to unpack the .zip for Windows or .tar.gz for Linux, UNIX, or Mac), then you can uncompress the Gateway to any directory location and run it in place.

    How do I install the Gateway using the Windows installer?

    Windows (32-Bit or 64-Bit) Installation

    1. Login to your Windows machine using an account that has administrator privileges.
    2. Invoke the Kaazing WebSocket Gateway Windows Installer Setup Wizard either by double-clicking the kaazing-websocket-gateway-html5-3.5.x-x64.msi file that you downloaded or by running it with the msiexec /i command at the command prompt.
    3. Follow the steps in the setup wizard and note the following:
      • You cannot install both Windows 64-bit and 32-bit of the same Gateway on the same machine.
      • On the Java Installation Directory page, you are prompted to enter the root directory of your Java JDK or JRE software installation. For example: C:\Program Files\Java\jdk1.6.0_29\. Before the Gateway is installed, the setup wizard verifies that the Java installation directory is valid (for example, C:\temp is invalid), but the wizard does not validate if it is a 64-bit or a 32-bit Java installation. Important: Choose a Java installation that matches the word size (64-bit or 32-bit) of the Windows installer you are running. To verify that the Gateway started correctly as a service, look at the log file in GATEWAY_HOME/log/service.log that is generated when the service is started or stopped.
      • The default installation includes the Gateway, the documentation, and the demos.
    4. The setup wizard installs the Gateway and adds the new files in the GATEWAY_HOME.

      GATEWAY_HOME: The installer creates the default GATEWAY_HOME destinations as follows:

      • For 64-bit and 32-bit Windows systems:
        C:\Program Files\Kaazing\html5\3.5\Gateway
      • For a 32-bit installation on a 64-bit Windows system:
        C:\Program Files (x86)\Kaazing\html5\3.5\Gateway

      Gateway Service: The Gateway service starts automatically and verifies that the Java installation directory that you supplied to the setup wizard is a valid 64-bit or a 32-bit Java installation. Errors are recorded in the Kaazing service log (C:\Program Files\Kaazing\html5\3.5\Gateway\log\service.log).

      Patching: When running the Windows Installer Setup Wizard to install a Gateway patch, the installation process does not overwrite user-modified files under the GATEWAY_HOME/conf directory when the patch is applied. However, any unmodified files might be overwritten by newer replacement files. See the Release Notes (online only) for information about what changes occurred in each release.

      Upgrading: When running the Windows Installer Setup Wizard to install the next release of the Gateway, the newer release is installed in a separate directory that is at the same level in the directory structure as the earlier release. Earlier releases of the Gateway are not overwritten or removed. For example, html5\3.4 and html5\3.5 are separate but parallel directories. Note that you cannot run both releases at the same time unless you change the ports on one or the other. See the Release Notes (online only) for information about what changes occurred in each release.

    5. If you installed the Base product, then none of the default services are automatically started. You must manually start your desired services.
    How do I install the Gateway using the Debian-based Linux installer?

    Debian-based Linux Installation

    1. Install the Gateway either by double-clicking the Debian installer for the Gateway, or by entering the dpkg -i kaazing-gateway-package-name.deb command, where package-name is the Gateway package you downloaded. For example:

      sudo dpkg -i kaazing-gateway-html5-3.5-3.5.x.y.deb
      sudo dpkg -i kaazing-gateway-html5-3.5-extras-3.5.x.y.deb

      Notes: For Linux systems, the Documentation and Demos download requires that you install the Gateway Only download first.
      • You may choose to install the Gateway Only download and then the Documentation and Demos download, or install both using the Install via repository option. To download and install the Linux repository, click the "Install via repository" button and follow the instructions on the Gateway Download page.
      • If you accidentally install Documentation and Demos before you install the Gateway Only download, then the installation stops and displays an error message. For example: dpkg: dependency problems prevent configuration of kaazing-gateway-html5-3.5-extras. If you get this error, then install the Gateway Only download before installing Documentation and Demos.
       
    2. The installation creates the Gateway directory structure and starts the Gateway automatically.
       

      The installer creates the Gateway directory structure following the Linux Filesystem Hierarchy Standards.

      Directory Description Patches and Upgrades
      /usr/share/kaazing/html5/3.5/

      (Read only) Also known as GATEWAY_HOME. Contains the libraries and scripts to run the Gateway.

      Files might be overwritten or deleted.
      /var/lib/kaazing/html5/3.5/

      (Read/write) Contains the web content and libraries for the Gateway. If you installed "Extras" then the web directory contains the documentation and demos.

      User files are not overwritten or deleted but files in the extras folder may be overwritten or deleted.

      /etc/kaazing/html5/3.5/

      (Read/write) Contains the Gateway configuration files and the license file.

      Modified files are not overwritten or deleted.
      /var/log/kaazing/html5/3.5/

      Contains the log files.

      Files are not overwritten.

      Patching: When you eventually run the Linux installer to patch your Gateway software to a newer release, the installation process preserves user-modified files while the configuration is upgraded to the latest release of the Gateway. See the Release Notes (online only) for information about what changes occurred in each release.

      Upgrading: To upgrade the Gateway, the newer release is installed in a separate directory that is at the same level in the directory structure as the earlier release. Earlier releases of the Gateway are not overwritten or removed. For example, html5/3.4 and html5/3.5 are separate but parallel directories. Note that you cannot run both releases at the same time unless you change the ports on one or the other. See the Release Notes (online only) for information about what changes occurred in each release.

    3. If you installed the Base product, then none of the default services are automatically started. You must manually start your desired services.
    How do I unpack the compressed download of the Gateway (.zip for Windows or .tar.gz for Linux, UNIX, or Mac)

    On Windows you can unpack the Gateway .zip file using Windows Explorer, and on Linux, UNIX, or Mac you can unpack the .tar.gz file with the tar xvfz tar-file-name.tar.gz command.

    Standard UNIX Tar does not always handle long path names correctly (this is a 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 (gtar) from the directory /usr/gnu/bin/gtar or by using one of its links: /usr/bin/gtar or /usr/sfw/bin/gtar.

  4. Navigate to the GATEWAY_HOME/conf/ directory and edit the Gateway configuration to update the value of the gateway.hostname property by replacing localhost with your host name or IP address.
    How do I update my hostname and which gateway configuration file should I edit?
    1. Edit either of the Gateway configuration file options: gateway-config.xml or gateway-config-minimal.xml, or edit your custom configuration file if you created one. The Gateway configuration files are described in detail in Understanding Kaazing WebSocket Gateway Configuration.
    2. Replace localhost with your host name or IP address.

      For example, the hostname example.com replaces localhost in the "Property defaults" section of the following Gateway configuration file:

      <properties>
          <property>
             <name>gateway.hostname</name>
             <value>example.com</value>
          </property>
          <property>
             <name>gateway.base.port</name>
             <value>8000</value>
          </property>
          <property>
             <name>gateway.extras.port</name>
             <value>8001</value>
          </property>
      </properties>

      See the Directory element for more information and examples.

      Note: You can optionally specify default values for configuration elements using the properties element in the "Property defaults" section of the Gateway configuration file. Doing so is recommended because it allows you to define a property value once and have its value used throughout the configuration.
  5. Start the demo services by navigating to the GATEWAY_HOME/bin directory and running the demo-services.start (Linux) or the demo-services.start.bat (Windows) script. Note: Remember that the documentation and demos are included only with the "Gateway + Documentation + Demos" download.
    How do I start the demo services?

    On Windows:

    1. In Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.
    2. Use the following command to start the demo services, and substitute either the public IP address or the public DNS name for example.com:

      demo-services.start.bat udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

    On Linux, UNIX, or Mac:

    1. Navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.

      In the following example, edition refers to the product edition (for example, html5 or jms) and version refers to the Release Number (for example, 3.5.x):

      cd /home/username/kaazing/kaazing-websocket-gateway-edition-version/bin

    2. Use the following command to start the demo services, and substitute either the public IP address or the public DNS name for example.com:

      demo-services.start udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

  6. Ensure Kaazing WebSocket Gateway is running. If you installed the Gateway using the Windows or Linux Installer, then the installer starts the Gateway automatically.

    How do I start and stop the Gateway?

    To Start the Gateway on Windows

    Use the Windows Services Manager or use one of the following commands at the command prompt with administrator rights:

    • For 64-bit JVM: net start KaazingHTML5v35x64Service
    • For 32-bit JVM: net start KaazingHTML5v35x86Service

    Alternatively, in Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway and double-click the gateway.start.bat script.

    To Start the Gateway on Linux, UNIX, or Mac

    Use either of the following methods:

    • Use Linux or Ubuntu commands
      • For Linux:
        sudo service kaazing-html5-3.5 start
        sudo service kaazing-html5-3.5 restart
      • For Ubuntu (Upstart):
        sudo start kaazing-html5-3.5
        sudo restart kaazing-html5-3.5


        To include a configuration file name on the start command, use the config option:

        sudo start kaazing-html5-3.5 config=/tmp/my-config.xml
    • Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-html5-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.

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

    INFO Kaazing WebSocket Gateway (3.5.x)
    INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml
    INFO Checking license information
    INFO Found license: Developer License, Maximum 50 connections, See LICENSE.txt
    INFO Starting server
    INFO Starting services
    INFO http://localhost:8000/
    INFO http://localhost:8001/
    INFO http://localhost:8001/session
    INFO http://localhost:9000/
    INFO sse://localhost:8001/sse
    INFO ws://localhost:8001/echo
    INFO Started services
    INFO Starting management
    INFO jmx://localhost:2020/
    INFO Started management
    INFO Started server successfully in 0.321 secs at 2044-06-06 22:22:00

    Note: The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Troubleshoot Kaazing WebSocket Gateway Configuration and Startup topic for more information.

    To Stop the Gateway on Windows

    Use the Windows Services Manager, press CTRL + C at the command prompt that was used to start the Gateway or simply close the command prompt, or use the net stop command to stop the Gateway service. See the Windows Server documentation for more command-line information.

    To Stop the Gateway on Linux, UNIX, and Mac

    Kill the process at the command line, or use the Linux or Ubuntu (Upstart) service stop command (for example, sudo service kaazing-html5-3.5 stop).

  7. Verify the Gateway setup by navigating to the Gateway home page on your server.
    How do I verify that the Gateway is running?

    To verify that the Gateway is up and running, open a browser and navigate to the Gateway home page on your server (by default port 8000). Click the Documentation tab to see the documentation library and learn more about the Gateway. Click the Demos tab to view the demos.

    A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Documentation + Demos download. If you want to configure your own back-end service, see the Advanced configuration service and the client how-to guides on the Kaazing Documentation home page for more information.

    See the Release Notes (online only) for an overview of the certified browser versions for this release.

You are done configuring the Gateway on a server. To start building your first application, see the For Developers documentation topics.

To uninstall the Gateway, see the Uninstall Kaazing WebSocket Gateway section at the end of this document.

Setting Up Kaazing WebSocket Gateway on a Cloud Server

The Gateway can be installed and operated on either a local platform or on a remote server. A remote server, commonly referred to as a Cloud Server, is operated by firms specializing in operating and leasing commodity servers and is used for highly reliable and scalable applications.

A Cloud Server configuration for Kaazing WebSocket Gateway
Figure: A Cloud Server Configuration for Kaazing WebSocket Gateway

To set up the Gateway on a cloud server, perform the following steps:

  1. Ensure your system meets the system requirements.

    For specific environment and operating system information, see the README.txt file.

  2. Create and connect to a cloud server instance.

    These instructions assume that you have already set up and connected to a cloud server.

    How do I connect to a cloud server instance?

    Refer to the Documentation for complete instructions about using Kaazing WebSocket Gateway in Amazon Web Services to create and connect to a cloud server instance.

  3. Download Kaazing WebSocket Gateway.
    How do I download the Gateway?
    1. Download Kaazing WebSocket Gateway software using the wget command on the cloud machine, or download the software from the Kaazing download page to your local machine and then transfer the file to the cloud machine using FTP.

      For example, on Linux, UNIX, or Mac, the wget command would be similar to the following:

      wget http://kaazingcorp.cachefly.net/com/download/html5/3.5.x.y/kaazing-websocket-gateway-html5-3.5.x.tar.gz

      The Gateway is downloaded with a Development License, which allows for complete functionality for up to 50 connections. Further information about licensing and the different Gateway releases is available from http://www.kaazing.com/download.html.

    2. Extract the contents of the downloaded file to your home directory. For example:

      tar -xf kaazing-websocket-gateway-html5-3.5.x.tar.gz

    3. Verify that the root user’s home directory contents are similar to the following by running the ls command. The output should look similar to this:

      kaazing-websocket-gateway-html5-3.5.x
      kaazing-websocket-gateway-html5-3.5.x.tar.gz

  4. Replace localhost with your host name or IP address.

    To do this, perform the following steps:

    1. Navigate to the GATEWAY_HOME/conf/ directory.
    2. Edit the Gateway configuration file gateway-config.xml and update the value of the gateway.hostname parameter by replacing localhost with your host name or IP address. See the Directory element for more information and examples.
      Which gateway configuration file should I edit?

      Edit either of the Gateway configuration file options: gateway-config.xml or gateway-config-minimal.xml, or edit your custom configuration file if you created one. The Gateway configuration files are described in detail in Understanding Kaazing WebSocket Gateway Configuration Files, Elements, and Namespaces.

      How do I edit files on a cloud machine?

      vi editor users

      Open the file using the following command:

      vi gateway-config.xml

      emacs users

      1. Install the emacs editor using the following command:

        sudo apt-get install emacs

        If asked if the size is okay (“Is this ok [y/N]:”), type y and press enter.

      2. Open the file in emacs using the following command:

        emacs gateway-config.xml

      For users who are unfamiliar with vi or emacs, the use of a secure FTP client combined with local editing is recommended.

      You can also edit files locally and copy them to the cloud machine using FTP. The following steps outline this approach.

      1. Install one of the following secure FTP clients on your local platform:
      2. Install the vsftpd secure ftp daemon on your cloud instance using the command:

        sudo apt-get install vsftpd

        If asked if the size is okay (“Is this ok [y/N]:”), type y and press enter.

      3. Start the server daemon using the following command:

        sudo vsftpd

      4. Use your secure FTP client to transfer the gateway-config.xml file to your local platform for local editing and transfer the configuration file back to the cloud instance.

      The following example replaced localhost with the hostname example.com:

      <properties>
          <property>
             <name>gateway.hostname</name>
             <value>example.com</value>
          </property>
          <property>
             <name>gateway.base.port</name>
             <value>8000</value>
          </property>
          <property>
             <name>gateway.extras.port</name>
             <value>8001</value>
          </property>
      </properties>
  5. Configure network protocol bindings for all services.

    You can specify default values for all network protocol bindings one time in the gateway-config.xml file and have the values apply to all services.

    How do I configure network protocol bindings?
    1. Edit the gateway-config.xml file and locate the Service Defaults section.
    2. Add the element to the gateway-config.xml file.
    3. Configure the protocol.bind element to specify a default value for each network protocol bindings for all services. Note the following:
      • You can bind the address to a specific port, or to a hostname and port. If you specify a hostname, then you must specify a port. If you specify only the port number, it effectively tells the Gateway to listen on all available network interfaces using the specified port number.
      • If you default values for all services and you then specify values for a particular service, the service accept options supersede the default values with your specified values.
      • You must specify the accept options elements before any mime-mapping entries.

    The following example shows a portion of the gateway-config.xml file with sample network protocol bindings for the ws and http services.

        <service-defaults>
             <accept-options>
                <ws.bind>8000</ws.bind>
                <http.bind>8000</http.bind>
            </accept-options>
        <mime-mapping>
            <extension>html</extension>
            <mime-type>text/html</mime-type>
        </mime-mapping>
        <mime-mapping>
            <extension>js</extension>
            <mime-type>text/javascript</mime-type>
        </mime-mapping>
           .
           .
           .
         </service-defaults>
  6. Start the demo services by navigating to the GATEWAY_HOME/bin directory and running the demo-services.start (Linux) or the demo-services.start.bat (Windows) script.
    How do I start the demo services?

    On Windows:

    1. In Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.
    2. Either double-click the demo-service.start.bat file in Windows Explorer, or use the following command to start the demo services and substitute the public IP address or the public DNS name for example.com:

      demo-services.start.bat udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

    On Linux, UNIX, or Mac:

    1. Navigate to the GATEWAY_HOME/bin directory where you installed the Gateway.

      In the following example, edition refers to the product edition (for example, html5 or jms) and version refers to the version number (for example, 3.5.x):

      cd /home/username/kaazing/kaazing-websocket-gateway-edition-version/bin

    2. Use the following command to start the demo services, and substitute either the public IP address or the public DNS name for example.com:

      demo-services.start udp://example.com:50505

      By default the service accepts on udp://localhost:50505. See the documentation for the broadcast element to configure the corresponding broadcast element for a different address.

  7. Start Kaazing WebSocket Gateway.

    Note: If you installed the Gateway using the Windows or Linux Installer, then the installer starts the Gateway service automatically and you can skip to Step 6 to verify the configuration.
    How do I start and stop the Gateway?

    To Start the Gateway on Windows

    Use the Windows Services Manager or use one of the following commands at the command prompt with administrator rights:

    • For 64-bit JVM: net start KaazingHTML5v35x64Service
    • For 32-bit JVM: net start KaazingHTML5v35x86Service

    Alternatively, in Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway and double-click the gateway.start.bat script.

    To Start the Gateway on Linux, UNIX, or Mac

    Use either of the following methods:

    • Use Linux or Ubuntu commands
      • For Linux:
        sudo service kaazing-html5-3.5 start
        sudo service kaazing-html5-3.5 restart
      • For Ubuntu (Upstart):
        sudo start kaazing-html5-3.5
        sudo restart kaazing-html5-3.5


        To include a configuration file name on the start command, use the config option:

        sudo start kaazing-html5-3.5 config=/tmp/my-config.xml
    • Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-html5-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.

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

    INFO Kaazing WebSocket Gateway (3.5.x)
    INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml
    INFO Checking license information
    INFO Found license: Developer License, Maximum 50 connections, See LICENSE.txt
    INFO Starting server
    INFO Starting services
    INFO http://localhost:8000/
    INFO http://localhost:8001/
    INFO http://localhost:8001/session
    INFO http://localhost:9000/
    INFO sse://localhost:8001/sse
    INFO ws://localhost:8001/echo
    INFO Started services
    INFO Starting management
    INFO jmx://localhost:2020/
    INFO Started management
    INFO Started server successfully in 0.321 secs at 2044-06-06 22:22:00

    Note: The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Troubleshoot Kaazing WebSocket Gateway Configuration and Startup topic for more information.

    To Stop the Gateway on Windows

    Use the Windows Services Manager, press CTRL + C at the command prompt that was used to start the Gateway or simply close the command prompt, or use the net stop command to stop the Gateway service. See the Windows Server documentation for more command-line information.

    To Stop the Gateway on Linux, UNIX, and Mac

    Kill the process at the command line, or use the Linux or Ubuntu (Upstart) service stop command (for example, sudo service kaazing-html5-3.5 stop).

    How does the Gateway start and how do I override the default startup method?

    By default, the Gateway is started using the properties in the gateway-config.xml or the gateway-config-minimal.xml file in the GATEWAY_HOME/conf directory, as follows:

    • If you downloaded the Gateway Only product, then the Gateway is started using the properties in the gateway-config-minimal.xml file.
    • If you downloaded the Gateway + Documentation + Demos download, then the Gateway is started using the properties in the gateway-config.xml file, by default. If there is no gateway-config.xml file, then the Gateway looks for and uses the gateway-config-minimal.xml.

    To override the default method for starting the Gateway, include the --config command on the gateway.start (Linux) or gateway.start.bat (Windows) command line to start the Gateway and explicitly name the configuration file that should be invoked at startup. The following example starts the Gateway and explicitly specifies the gateway-config-minimal.xml configuration file in the GATEWAY_HOME/conf directory:

    ./gateway.start --config ../conf/gateway-config-minimal.xml

  8. Verify the Gateway setup by navigating to the Gateway home page on your cloud server in your browser.
    How do I verify that the Gateway is running?

    To verify that the Gateway is up and running, open a browser and navigate to the Gateway home page on your cloud server. Click the Documentation tab to see the documentation library and learn more about the Gateway. Click the Demos tab to view the demos.

    A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Documentation + Demos download. If you want to configure your own back-end service, see the Advanced configuration service and the client how-to guides on the Kaazing Documentation home page for more information.

    See the Release Notes (online only) for an overview of the certified browser versions for this release.

You are done configuring the Gateway on a server. To start building your first application, see the For Developers documentation topics.

To uninstall the Gateway, see the Uninstall Kaazing WebSocket Gateway section at the end of this document.

Integrating Kaazing WebSocket Gateway with a Web Server

Web integration with Kaazing WebSocket Gateway
Figure: Web Integration with Kaazing WebSocket Gateway

If you are hosting your web application on a separate web server, such as Apache HTTP Server or Microsoft IIS, perform the following steps:

  1. Navigate to the GATEWAY_HOME/conf/ directory.
  2. Edit the Gateway configuration to update the value of the gateway.hostname property by replacing localhost with your host name or IP address.
    How do I update my hostname and which gateway configuration file should I edit?
    1. Edit either of the Gateway configuration file options: gateway-config.xml or gateway-config-minimal.xml, or edit your custom configuration file if you created one. The Gateway configuration files are described in detail in Understanding Kaazing WebSocket Gateway Configuration.
    2. Replace localhost with your host name or IP address.

      For example, the hostname example.com replaces localhost in the "Property defaults" section of the following Gateway configuration file:

      <properties>
          <property>
             <name>gateway.hostname</name>
             <value>example.com</value>
          </property>
          <property>
             <name>gateway.base.port</name>
             <value>8000</value>
          </property>
          <property>
             <name>gateway.extras.port</name>
             <value>8001</value>
          </property>
      </properties>

      See the Directory element for more information and examples.

      Note: You can optionally specify default values for configuration elements using the properties element in the "Property defaults" section of the Gateway configuration file. Doing so is recommended because it allows you to define a property value once and have its value used throughout the configuration.
  3. To make your application work in Internet Explorer releases 6 and 7, perform the following steps to integrate your web server with the Gateway. For this example, assume that your source origin web server is serving up content on http://www.example.com and that the Gateway is running on http://www.gateway.com.

    1. Copy the file GATEWAY_HOME/lib/client/javascript/PostMessageBridge.html and serve it from the source origin web server (http://www.example.com); for example at http://www.example.com/bridge/PostMessageBridge.html.
    2. Note: You must ensure that the file PostMessageBridge.html is hosted on the same origin (same scheme, host, and port) as the web server.

    3. Add the following tags (shown in lines 2 and 3) to the head section of your main application page:
          <head>
      	    <meta name="kaazing:postMessageBridgeURL"
      	    content="http://www.example.com/bridge/PostMessageBridge.html" >
      	    .
      	    .
      	    .
      	</head>
      
      What about document.domain?

      You are strongly discouraged from setting document.domain in your application pages, because origin-based security supersedes domain-based security. If you must use it in your code, contact Kaazing Support for instructions.

  4. Start Kaazing WebSocket Gateway.

    How do I start and stop the Gateway?

    To Start the Gateway on Windows

    Use the Windows Services Manager or use one of the following commands at the command prompt with administrator rights:

    • For 64-bit JVM: net start KaazingHTML5v35x64Service
    • For 32-bit JVM: net start KaazingHTML5v35x86Service

    Alternatively, in Windows Explorer, navigate to the GATEWAY_HOME/bin directory where you installed the Gateway and double-click the gateway.start.bat script.

    To Start the Gateway on Linux, UNIX, or Mac

    Use either of the following methods:

    • Use Linux or Ubuntu commands
      • For Linux:
        sudo service kaazing-html5-3.5 start
        sudo service kaazing-html5-3.5 restart
      • For Ubuntu (Upstart):
        sudo start kaazing-html5-3.5
        sudo restart kaazing-html5-3.5


        To include a configuration file name on the start command, use the config option:

        sudo start kaazing-html5-3.5 config=/tmp/my-config.xml
    • Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-html5-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.

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

    INFO Kaazing WebSocket Gateway (3.5.x)
    INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml
    INFO Checking license information
    INFO Found license: Developer License, Maximum 50 connections, See LICENSE.txt
    INFO Starting server
    INFO Starting services
    INFO http://localhost:8000/
    INFO http://localhost:8001/
    INFO http://localhost:8001/session
    INFO http://localhost:9000/
    INFO sse://localhost:8001/sse
    INFO ws://localhost:8001/echo
    INFO Started services
    INFO Starting management
    INFO jmx://localhost:2020/
    INFO Started management
    INFO Started server successfully in 0.321 secs at 2044-06-06 22:22:00

    Note: The startup message may differ depending on your Gateway configuration. If the server does not start successfully, contact your administrator or see Troubleshoot Kaazing WebSocket Gateway Configuration and Startup topic for more information.

    To Stop the Gateway on Windows

    Use the Windows Services Manager, press CTRL + C at the command prompt that was used to start the Gateway or simply close the command prompt, or use the net stop command to stop the Gateway service. See the Windows Server documentation for more command-line information.

    To Stop the Gateway on Linux, UNIX, and Mac

    Kill the process at the command line, or use the Linux or Ubuntu (Upstart) service stop command (for example, sudo service kaazing-html5-3.5 stop).

  5. Verify the Gateway setup by navigating to your web server in your browser and test if you can access Gateway services from there.
    How do I verify that the Gateway is running?

    To verify that the Gateway is up and running, open a browser and navigate to a page on your web server to ensure you can access the Gateway services from there. Click the Documentation tab to see the documentation library and learn more about the Gateway. Click the Demos tab to view the demos.

    A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Documentation + Demos download. If you want to configure your own back-end service, see the Advanced configuration service and the client how-to guides on the Kaazing Documentation home page for more information.

    See the Release Notes (online only) for an overview of the certified browser versions for this release.

You are done integrating the Gateway with an HTTP server. To start building your first application, see the For Developers documentation topics.

Setting Up a Secure Kaazing WebSocket Gateway Configuration

By default, the Gateway listens for non-encrypted traffic. Secure communication between the browser and the server is necessary to ensure that only the intended recipient of a message can read the transmitted message and to allow the message recipient to trust that the message is indeed from the expected source.

An encrypted configuration using Kaazing WebSocket Gateway
Figure: An Encrypted Configuration Using Kaazing WebSocket Gateway

For secure communication with the Gateway, consider configuring for the following levels of security:

Configuring Kaazing WebSocket Gateway for High Availability

High availability for services is achieved by configuring multiple gateways to be part of a cluster, and balancing the workload across the cluster members.

A high availability Kaazing WebSocket Gateway configuration
Figure: A High Availability Kaazing WebSocket Gateway Configuration

For complete information about setting up a highly available configuration, see Checklist: Configure Kaazing WebSocket Gateway for High Availability.

Advanced Configuration

An advanced Kaazing WebSocket Gateway configuration
Figure: An Advanced Kaazing WebSocket Gateway Configuration

For more information about setting up additional, and more advanced configurations, see Checklist: Configure Kaazing WebSocket Gateway.

Uninstall Kaazing WebSocket Gateway

If you installed Kaazing WebSocket Gateway by unpacking the tar.gz or ZIP file, you can uninstall the Gateway by simply stopping all the services and deleting the directory that contains the Gateway files. If you installed the Gateway using the Windows or Linux installers, use the following steps as appropriate for Windows or Linux systems:

How do I uninstall the Gateway on Windows systems?

To Uninstall Kaazing WebSocket Gateway on Windows Systems

  1. Login to your Windows machine using an account that has administrator privileges.
  2. Back up any files that you modified and want to keep. For example, you might have modified the Gateway configuration in the \conf directory, and any files you modified under the \web directory. Uninstalling the Gateway removes all of your files!
  3. Invoke the Kaazing WebSocket Gateway Windows Installers Setup Wizard by double-clicking the kaazing-websocket-gateway-edition-version-type.msi file that you downloaded.
  4. Remove the Gateway.

    On the "Change, repair, or remove installation" page, click Remove and then follow the steps in the setup wizard to remove the Gateway.

  5. Verify that the Gateway is not running.

    Open a browser and access the Gateway home page at http://localhost:8000/. Your browser returns an error indicating that it cannot display the web page.

You are now done uninstalling Kaazing WebSocket Gateway.

How do I uninstall the Gateway on Debian-based Linux systems?

To Uninstall Kaazing WebSocket Gateway on Debian-based Linux Systems

  1. Back up any files that you modified and want to keep.
  2. Uninstall the Documentation and Demos first, if that package is installed, and then uninstall the Gateway Only package.

    If you installed the Documentation and Demos download, then you must uninstall that package before you uninstall the Gateway. You can perform the uninstallation using Synaptic Package Manager (see the online Help system for instructions) or at the command line using either the Debian package manager dpkg command or the apt-get command.

    • To uninstall using the Debian package manager dpkg, enter the dpkg -r or dpkg --purge kaazing-gateway-package-name.deb command, where package-name is the Gateway package you downloaded and installed. For example:

      dpkg --purge kaazing-gateway-html5-3.5-extras-3.5.x.y
      dpkg --purge kaazing-gateway-html5-3.5-3.5.x.y

    • To uninstall using the apt-get command, enter apt-get remove package-name or apt-get purge package-name, where package-name is the Gateway package you downloaded and installed. For example:

      apt-get remove kaazing-gateway-html5-3.5-extras-3.5.x.y
      apt-get remove kaazing-gateway-html5-3.5-3.5.x.y

    • Notes:
      • You can uninstall using either the remove or purge option at the command line. Removing a package removes the program files but retains the Gateway configuration files located in the /etc/kaazing/html5/3.5 directory. Purging removes everything. See your Debian documentation to learn more about removing versus purging a package.
      • If you accidentally uninstall the Gateway before Documentation and Demos, then the uninstallation stops and displays an error message. For example: dpkg: dependency problems prevent removal of kaazing-gateway-html5-3.5-extras.
  3. Monitor the messages returned by the uninstallation process.

You are now done uninstalling Kaazing WebSocket Gateway.