Setting Up Kaazing WebSocket Gateway
This guide helps you set up Kaazing WebSocket Gateway in your environment.
I want to use Kaazing WebSocket Gateway:
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!

To set up the Gateway on your local computer, perform the following steps:
- Ensure your system meets the system requirements. See the README.txt in your distribution.
- 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 serviceCompressed File (zip or tar.gz)
Uncompress to any directory and run in place; runs the Gateway standalone, not as a serviceInstall Via Repository
Add the Kaazing repository to your Linux repositories; runs the Gateway as a serviceWindows 64-bit(1) or 32-bit(2)N/ALinux (Debian) All Linux, UNIX, and MacN/AN/A1The 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 + Demos:
- Gateway Only downloads: Contain only the Gateway for experienced users who are ready to use the Gateway in production.
- Gateway + Demos downloads: Contain the Gateway plus demo-services that provide sample data for some of our demos. This download provides a great way to become familiar with the Gateway.
- 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
- Login to your Windows machine using an account that has administrator privileges.
- Invoke the Kaazing WebSocket Gateway Windows Installer Setup Wizard either by double-clicking the kaazing-websocket-gateway-gateway-4.0.x-x64.msi file that you downloaded or by running it with the msiexec /i command at the command prompt.
- 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.
- 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\gateway\4.0\Gateway
- For a 32-bit installation on a 64-bit Windows system: C:\Program Files (x86)\Kaazing\gateway\4.0\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\gateway\4.0\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 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, gateway\3.5 and gateway\4.0 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 for information about what changes occurred in each release.
- 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
- 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-gateway-4.0-4.0.x.y.deb
sudo dpkg -i kaazing-gateway-gateway-4.0-extras-4.0.x.y.deb
Notes: For Linux systems, the Demos download requires that you install the Gateway Only download first.- You may choose to install the Gateway Only download and then the 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 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-gateway-4.0-extras. If you get this error, then install the Gateway Only download before installing Demos.
- 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/gateway/4.0/ (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/gateway/4.0/ (Read/write) Contains the web content and libraries for the Gateway. If you installed "Extras" then the web directory contains the demos.
User files are not overwritten or deleted but files in the extras folder may be overwritten or deleted.
/etc/kaazing/gateway/4.0/ (Read/write) Contains the Gateway configuration files and the license file.
Modified files are not overwritten or deleted. /var/log/kaazing/gateway/4.0/ 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 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, gateway/3.5 and gateway/4.0 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 for information about what changes occurred in each release.
- 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 repository?
Debian-based Linux Repository Installation
Follow these steps to add the Kaazing repository to your list of repositories:
- Install the Kaazing repository signing key.
sudo sh -c "wget -O kaazing-repo-key http://archive.kaazing.com/archive.kaazing.com.pub | apt-key add kaazing-repo-key"
- Install the Kaazing repository list.
sudo wget -O /etc/apt/sources.list.d/archive.kaazing.com.list \
http://archive.kaazing.com/archive.kaazing.com.list
Follow these steps to install Kaazing WebSocket Gateway from the repository:
- Update local package index with latest changes from repositories.
sudo apt-get update
- Install the base product.
sudo apt-get install kaazing-gateway-gateway-4.0
- Install the demos.
sudo apt-get install kaazing-gateway-gateway-4.0-extras
Once installed, you can access Kaazing WebSocket Gateway using a browser. For example, to test locally on your computer, enter: http://localhost:8000.
Follow these steps to patch a Kaazing WebSocket Gateway previously that was installed from the repository:
- Patch the base product.
sudo apt-get upgrade kaazing-gateway-gateway-4.0
- Patch the demos.
sudo apt-get upgrade kaazing-gateway-gateway-4.0-extras
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.
- Optionally, if you want to start the demo services, navigate to the GATEWAY_HOME/bin directory and run the demo-services.start (Linux/Mac OSX) or the demo-services.start.bat (Windows) script. If the Gateway is running as a service on Windows, then you should run this script as Administrator (for example by right-clicking the script file in Windows Explorer). Note: Remember that the demos are included only with the "Gateway + Demos" download. By default, the service broadcasts on udp://example.com:50505. See the documentation for the broadcast service for more information.
- 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 KaazingHTML5v40x64Service
- For 32-bit JVM: net start KaazingHTML5v40x86Service
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-gateway-4.0 start
- For Ubuntu (Upstart):
sudo start kaazing-gateway-4.0
To include a configuration file name on the start command, use the config option:
sudo start kaazing-gateway-4.0 config=/tmp/my-config.xml
- Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-gateway-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.
When you successfully start the Gateway, messages display in your shell or command prompt indicating the services that are hosted by the Gateway.
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-gateway-4.0 stop).
- Verify the Gateway setup.
How do I verify that the Gateway is running?
To verify that the Gateway is up and running, view it with Command Center, which is a browser-based application enabled in the default Gateway configuration. See Monitor with Command Center for instructions.
Alternatively, open a browser and access the Gateway home page at http://localhost:8000/. If you downloaded the Gateway + Demos download, then click the Demos tab to view the demos. A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Demos download.
See the Release Notes 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 start building your first application, see the For Developers documentation topics.
- 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.
- For real-world product demos, see http://kaazing.com/demo.
- 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.

To set up a server configuration, perform the following steps:
- Ensure your system meets the system requirements. See the README.txt in your distribution.
- 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 serviceCompressed File (zip or tar.gz)
Uncompress to any directory and run in place; runs the Gateway standalone, not as a serviceInstall Via Repository
Add the Kaazing repository to your Linux repositories; runs the Gateway as a serviceWindows 64-bit(1) or 32-bit(2)N/ALinux (Debian) All Linux, UNIX, and MacN/AN/A1The 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 + Demos:
- Gateway Only downloads: Contain only the Gateway for experienced users who are ready to use the Gateway in production.
- Gateway + Demos downloads: Contain the Gateway plus demo-services that provide sample data for some of our demos. This download provides a great way to become familiar with the Gateway.
- 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
- Login to your Windows machine using an account that has administrator privileges.
- Invoke the Kaazing WebSocket Gateway Windows Installer Setup Wizard either by double-clicking the kaazing-websocket-gateway-gateway-4.0.x-x64.msi file that you downloaded or by running it with the msiexec /i command at the command prompt.
- 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.
- 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\gateway\4.0\Gateway
- For a 32-bit installation on a 64-bit Windows system: C:\Program Files (x86)\Kaazing\gateway\4.0\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\gateway\4.0\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 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, gateway\3.5 and gateway\4.0 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 for information about what changes occurred in each release.
- 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
- 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-gateway-4.0-4.0.x.y.deb
sudo dpkg -i kaazing-gateway-gateway-4.0-extras-4.0.x.y.deb
Notes: For Linux systems, the Demos download requires that you install the Gateway Only download first.- You may choose to install the Gateway Only download and then the 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 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-gateway-4.0-extras. If you get this error, then install the Gateway Only download before installing Demos.
- 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/gateway/4.0/ (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/gateway/4.0/ (Read/write) Contains the web content and libraries for the Gateway. If you installed "Extras" then the web directory contains the demos.
User files are not overwritten or deleted but files in the extras folder may be overwritten or deleted.
/etc/kaazing/gateway/4.0/ (Read/write) Contains the Gateway configuration files and the license file.
Modified files are not overwritten or deleted. /var/log/kaazing/gateway/4.0/ 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 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, gateway/3.5 and gateway/4.0 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 for information about what changes occurred in each release.
- 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 repository?
Debian-based Linux Repository Installation
Follow these steps to add the Kaazing repository to your list of repositories:
- Install the Kaazing repository signing key.
sudo sh -c "wget -O kaazing-repo-key http://archive.kaazing.com/archive.kaazing.com.pub | apt-key add kaazing-repo-key"
- Install the Kaazing repository list.
sudo wget -O /etc/apt/sources.list.d/archive.kaazing.com.list \
http://archive.kaazing.com/archive.kaazing.com.list
Follow these steps to install Kaazing WebSocket Gateway from the repository:
- Update local package index with latest changes from repositories.
sudo apt-get update
- Install the base product.
sudo apt-get install kaazing-gateway-gateway-4.0
- Install the demos.
sudo apt-get install kaazing-gateway-gateway-4.0-extras
Once installed, you can access Kaazing WebSocket Gateway using a browser. For example, to test locally on your computer, enter: http://localhost:8000.
Follow these steps to patch a Kaazing WebSocket Gateway previously that was installed from the repository:
- Patch the base product.
sudo apt-get upgrade kaazing-gateway-gateway-4.0
- Patch the demos.
sudo apt-get upgrade kaazing-gateway-gateway-4.0-extras
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.
- 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?
- 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.
- 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.
- Optionally, if you want to start the demo services, navigate to the GATEWAY_HOME/bin directory and run the demo-services.start (Linux/Mac OSX) or the demo-services.start.bat (Windows) script. If the Gateway is running as a service on Windows, then you should run this script as Administrator (for example by right-clicking the script file in Windows Explorer). Note: Remember that the demos are included only with the "Gateway + Demos" download. By default, the service broadcasts on udp://example.com:50505. See the documentation for the broadcast service for more information.
- 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 KaazingHTML5v40x64Service
- For 32-bit JVM: net start KaazingHTML5v40x86Service
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-gateway-4.0 start
- For Ubuntu (Upstart):
sudo start kaazing-gateway-4.0
To include a configuration file name on the start command, use the config option:
sudo start kaazing-gateway-4.0 config=/tmp/my-config.xml
- Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-gateway-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.
When you successfully start the Gateway, messages display in your shell or command prompt indicating the services that are hosted by the Gateway.
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-gateway-4.0 stop).
- Verify the Gateway setup.
How do I verify that the Gateway is running?
To verify that the Gateway is up and running, view it with Command Center, which is a browser-based application enabled in the default Gateway configuration. See Monitor with Command Center for instructions.
Alternatively, open a browser and navigate to the Gateway home page on your server (by default port 8000) and click Demos to view the demos. A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Demos download.
See the Release Notes for an overview of the supported 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 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.
- For real-world product demos, see http://kaazing.com/demo.
- To uninstall the Gateway, see the Uninstall Kaazing WebSocket Gateway section at the end of this document.
Setting Up Kaazing WebSocket Gateway in a Cloud Environment
You can install and manage the Gateway on a local machine, on a machine in a private (enterprise) cloud environment, or launch instances of Kaazing WebSocket Gateway in Amazon's cloud environment, AWS Marketplace. This section explains how to install the Gateway on a machine in a private (enterprise) cloud environment. For cloud deployments, please review the steps for creating images for your specific cloud environment before getting started.
Note: To use Kaazing WebSocket Gateway on Amazon Web Services (AWS) Marketplace, go to Marketplace, search for “Kaazing” and launch the edition you wish to use. Refer to Using Kaazing WebSocket Gateway on Amazon Web Services (AWS) Marketplace for more information.
To set up the Gateway in a private (enterprise) cloud environment, perform the following steps:
- Ensure your system meets the system requirements. See the README.txt in your distribution.
- Launch an instance in your cloud environment. For example, you can create an Ubuntu Linux, Red Hat Linux, or Microsoft Windows Server 2008 instance in AWS.
- Download Kaazing WebSocket Gateway.
How do I download the Gateway?
- 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/gateway/4.0.x.y/kaazing-websocket-gateway-gateway-4.0.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.
- Extract the contents of the downloaded file to your home directory. For example, on Linux, UNIX, or Mac enter the following command:
tar -xvfz kaazing-websocket-gateway-gateway-4.0.x.tar.gz
- 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-gateway-4.0.x kaazing-websocket-gateway-gateway-4.0.x.tar.gz
- 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.
- 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 hostname or IP address. See the directory element for more information and examples.
How do I edit my hostname and 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 the About Kaazing WebSocket Gateway Configuration Files topic.
How do I edit the configuration files on a server in a cloud environment?
Use a secure FTP client like Filezilla, WinSCP (Windows), Cyberduck (Mac OS X), gFTP (Linux) to transfer files, then edit the files locally with a text editor, then securely transfer the files back to the server.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>
Note when deploying the Gateway on a machine in Amazon EC2:If you are deploying the Gateway to an instance on Amazon EC2, you can use two optional parameters,
cloud.host
andcloud.instanceid
, to automatically reference the Amazon-supplied hostname for your cloud instance and the Amazon-supplied instance ID that is used as the password for Command Center. In this case, you must also set theprotocol.bind
element to enable the instance to resolve the hostname to the machine name. See Configure Kaazing WebSocket Gateway for more information about referencing these parameters in your Gateway configuration, or to modify the Gateway configuration to use your preferred hostname and password instead of the Amazon defaults. For help with protocol bindings, see How do I configure network protocol bindings. - In the configuration file, configure the services as desired. See Understanding Kaazing WebSocket Gateway Configuration for more information about configuring the Gateway, or refer directly to the Configuration Element Index.
- In the same configuration file, 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. To do so, locate the service-defaults section and configure network protocol bindings for all services.
How do I configure network protocol bindings?
- Edit the gateway-config.xml file and locate the Service Defaults section.
- Add the
element to the gateway-config.xml file. - Configure the protocol.bind element to specify a default value for each network protocol binding 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.
- You can choose to configure network bindings for all services by using the service defaults section in configuration file. You can also choose to supercede these values for any particular service in the service element. See the Service Defaults Reference for more information.
- You must specify accept-options 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>
- Optionally, if you want to start the demo services, navigate to the GATEWAY_HOME/bin directory and run the demo-services.start (Linux/Mac OSX) or the demo-services.start.bat (Windows) script. If the Gateway is running as a service on Windows, then you should run this script as Administrator (for example by right-clicking the script file in Windows Explorer). Note: Remember that the demos are included only with the "Gateway + Demos" download. By default, the service broadcasts on udp://example.com:50505. See the documentation for the broadcast service for more information.
- 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 9 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 KaazingHTML5v40x64Service
- For 32-bit JVM: net start KaazingHTML5v40x86Service
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-gateway-4.0 start
- For Ubuntu (Upstart):
sudo start kaazing-gateway-4.0
To include a configuration file name on the start command, use the config option:
sudo start kaazing-gateway-4.0 config=/tmp/my-config.xml
- Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-gateway-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.
When you successfully start the Gateway, messages display in your shell or command prompt indicating the services that are hosted by the Gateway.
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-gateway-4.0 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 + 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
- Verify the Gateway setup.
How do I verify that the Gateway is running?
To verify that the Gateway is up and running, view it with Command Center, which is a browser-based application enabled in the default Gateway configuration. See Monitor with Command Center for instructions.
Alternatively, open a browser and navigate to the Gateway home page in your cloud environment and click the Demos tab to view the demos. A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Demos download.
See the Release Notes 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 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.
- For real-world product demos, see http://kaazing.com/demo.
- To uninstall the Gateway, see the Uninstall Kaazing WebSocket Gateway section at the end of this document.
- Navigate to the GATEWAY_HOME/conf/ directory.
- 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?
- 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 the About Kaazing WebSocket Gateway Configuration Files topic.
- 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.
-
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.
- 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.
- 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.
Note: You must ensure that the file PostMessageBridge.html is hosted on the same origin (same scheme, host, and port) as the web server.
- 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 KaazingHTML5v40x64Service
- For 32-bit JVM: net start KaazingHTML5v40x86Service
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-gateway-4.0 start
- For Ubuntu (Upstart):
sudo start kaazing-gateway-4.0
To include a configuration file name on the start command, use the config option:
sudo start kaazing-gateway-4.0 config=/tmp/my-config.xml
- Run the gateway.start script by navigating to the GATEWAY_HOME/bin directory (/home/username/kaazing/kaazing-websocket-gateway-gateway-version/bin) where you installed the Gateway and enter ./gateway.start on the command line.
When you successfully start the Gateway, messages display in your shell or command prompt indicating the services that are hosted by the Gateway.
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-gateway-4.0 stop).
- Verify the Gateway setup.
How do I verify that the Gateway is running?
To verify that the Gateway is up and running, view it with Command Center, which is a browser-based application enabled in the default Gateway configuration. See Monitor with Command Center.
Alternatively, open a browser and navigate to a page on your web server to ensure you can access the Gateway services from there. Click Demos to view the demos. A WebSocket Echo demo service is bundled and started by default if you downloaded the Gateway + Demos download.
See the Release Notes for an overview of the supported browser versions for this release.
- To start building your first application, see the For Developers documentation topics.
- 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.
- For real-world product demos, see http://kaazing.com/demo.
- Secure network traffic Configure Transport Layer Security (TLS, also known as SSL) for secure communications channels to access the Gateway by setting up certificates. See Checklist: Secure Network Traffic with the Gateway for more information.
- Limit access to services Use Cross-Origin Resource Sharing to control access to Gateway services based on the origin of an application by configuring cross-site constraints in the gateway-config.xml file. See About Security with Kaazing WebSocket Gateway for more information.
- Configure authentication and authorization with constraints to limit access to Gateway services to authenticated and authorized users. See Checklist: Configure Authentication and Authorization for more information.
- Configure Kerberos network authentication for network authentication and communication between trusted hosts on untrusted networks. See Configuring Kerberos V5 Network Authentication Overview for more information.
- Login to your Windows machine using an account that has administrator privileges.
- 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!
- Invoke the Kaazing WebSocket Gateway Windows Installers Setup Wizard by double-clicking the kaazing-websocket-gateway-edition-version-type.msi file that you downloaded.
- 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.
- Verify that the Gateway is not running by viewing it in Command Center.
View the Gateway status with Command Center. See Monitor with Command Center for instructions.
Alternatively, you can 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.
- Back up any files that you modified and want to keep.
- Uninstall the Demos first, if that package is installed, and then uninstall the Gateway Only package.
If you installed the 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
kaazing-gateway-package-name.deb command, where package-name is the Gateway package you downloaded and installed. For example:dpkg --purge kaazing-gateway-gateway-4.0-4.0.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-gateway-4.0-extras-4.0.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/gateway/4.0 directory. Purging removes everything. See the Debian package management tools to learn more about removing versus purging a package.
- If you accidentally uninstall the Gateway before Demos, then the uninstallation stops and displays an error message. For example: dpkg: dependency problems prevent removal of kaazing-gateway-gateway-4.0-extras.
- To uninstall using the Debian package manager dpkg, enter the dpkg -r
- Monitor the messages returned by the uninstallation process.
Integrating Kaazing WebSocket Gateway with a Web Server

If you are hosting your web application on a separate web server, such as Apache HTTP Server or Microsoft IIS, perform the following steps:
You are done integrating the Gateway with an HTTP server.
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.

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.

For complete information about setting up a highly available configuration, see Checklist: Configure Kaazing WebSocket Gateway for High Availability.
Advanced 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
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
You are now done uninstalling Kaazing WebSocket Gateway.