INSTALLING KAAZING WEBSOCKET GATEWAY - HTML5 EDITION ON AN AMAZON EC2 CLOUD SERVER A TECHNICAL WHITEPAPER Copyright 2012 Kaazing Corporation. All rights reserved. kaazing.com
Executive Overview This document promotes the rapid installation and setup of Kaazing WebSocket Gateway HTML5 Edition on an Amazon Elastic Compute Cloud (EC2) cloud server. It provides a detailed, step-by-step guide to installing the Gateway on an EC2 cloud server provided by Amazon. The use of the free Amazon instance makes these procedures ideal for costconstrained applications. About the Authors These instructions were originally created by John Bergmans of Bergmans Mechatronics LLC (jbergmans@bergmans.com) for version 9.06 of Kaazing WebSocket Gateway, and documented in collaboration with the Kaazing Technical Communication team. Introduction Kaazing WebSocket Gateway, developed by Kaazing Corporation, is a software application that allows continuous, bidirectional communication between web browsers and servers using the HTML5 WebSocket standard. The Gateway is well suited for enterprise applications due to its capacity for large numbers of simultaneous connections, support for many common messaging protocols, high availability options, and security features. The Gateway can be installed and operated on either of the following platforms: A local platform A remote server This type of 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. Although the basic concepts involved with installing and operating the Gateway on a cloud server are straightforward, the steps involved with actually setting up the Gateway in this configuration can be time-consuming for those unfamiliar with the Gateway or cloud server operation. This document guides the user by breaking the process down into a series of steps that simplifies the process and ensures first-time success. The high-level steps in the process include the following: Copyright 2012 Kaazing Corporation 2 kaazing.com
1. Create an EC2 Server Instance 2. Connect to the EC2 Server 3. Download Kaazing WebSocket Gateway 4. Prepare the Gateway Configuration File 5. Start Kaazing WebSocket Gateway 6. Test Kaazing WebSocket Gateway These steps require approximately one to two hours to complete. Create an EC2 Server Instance Perform the following steps to set up an Amazon Elastic Compute Cloud (EC2) instance. For more information: See the EC2 User s Guide at http://docs.amazonwebservices.com/awsec2/latest/userguide/ 1. Point your browser to http://aws.amazon.com. 2. If you already have an AWS (Amazon Web Services) account, click Sign in to the AWS Management Console, log in and skip to Step 4. 3. Perform the following steps to create an AWS account, if you don t already have one: a) Click Create an AWS Account. b) After creating the account, select Amazon Elastic Compute Cloud. Copyright 2012 Kaazing Corporation 3 kaazing.com
c) On the Elastic Compute Cloud page, click Sign Up for Amazon EC2. d) Enter your AWS account information and click Sign in using out secure server. e) Enter credit card information at the bottom of the Pricing page and click Continue. Your card is not charged at this step. f) On the Add A Billing Address page, click Use This Address or enter new billing information on the next page and click Continue. Copyright 2012 Kaazing Corporation 4 kaazing.com
g) Proceed through the three-step Identity Verification by Telephone process. This process involves entering a phone number. When the AWS system calls that number, enter on the phone the PIN number presented in the browser. Click Continue upon completion of the identity verification. a. Review your selections and click Complete Sign Up. b. After your AWS account has been activated, then sign in at http://aws.amazon.com and proceed to step 4. 4. On the AWS Management Console, select the Amazon EC2 tab. Copyright 2012 Kaazing Corporation 5 kaazing.com
5. Click Launch Instance. 6. Select Basic 32-bit Amazon Linux AMI 2011.02.1 Beta. Copyright 2012 Kaazing Corporation 6 kaazing.com
7. Select the Micro Instance Type and click Continue. 8. On the Advanced Instance Options page, click Continue to select all the defaults. 9. On the Request Instances Wizard page, enter a value for the Name of the instance and click Continue. 10. Create a new key pair: a) Select Create a new Key Pair. b) Enter a name for the key pair. c) Click Create & Download your Key Pair. d) Click Continue. my- key- pair Copyright 2012 Kaazing Corporation 7 kaazing.com
The wizard prompts you to save the key pair file and provides the.pem extension by default. (for example, the file in the example is saved as my-keypair.pem.) 11. On the Configure Firewall page: a) Select Create a new Security Group. b) Enter a Group Name and Group Description. c) Enable the following individual ports and port ranges by entering individual ports, or ranges of ports in the Port range field. After each port or port range is entered in the Port range field, click + Add Rule. Port Number Description 21-22 Default shell and secure shell ports 80 Default HTTP port 443 Default HTTPS port 2020 Default Kaazing Management Service port 5942-5943 Default Kaazing Cluster ports 8000-8001 Default Kaazing WebSocket service and echo service ports 8080-8081 Default Kaazing clustered WebSocket service and echo service ports 8161 Default Apache ActiveMQ Admin console 9000-9001 Default Kaazing WebSocket Secure and secure echo ports 9090-9091 Default Kaazing clustered WebSocket secure service and secure echo service ports 61613 Default Apache ActiveMQ Stomp ports 61616-61617 Default Apache ActiveMQ TCP and SSL ports 61222 Default Apache ActiveMQ XMPP port After entering the port information, the Wizard should appear similar to the following screenshot. Click Continue. Copyright 2012 Kaazing Corporation 8 kaazing.com
Note: The source IP is set to 0.0.0.0/0, meaning that any IP address may access these ports. If desired, it is possible to restrict access by IP address. For additional information on this subject, see the chapter about Using Security Groups in the EC2 User Guide at http://docs.amazonwebservices.com/awsec2/latest/userguide/ 12. The Review page displays. Click Launch to start the instance.!"#$%"#&'()* 13. Click Close on the final page of the wizard to return to the EC2 dashboard. Copyright 2012 Kaazing Corporation 9 kaazing.com
14. Select Instances in the list of links on the left side of the dashboard. The instance that was just launched should appear in the My Instances list. For example: 15. Display details about the instance by clicking the name of the new instance. The details are shown at the bottom of the window. For example: my- key- pair ec2-192.168.10.25.compute- 1.amazonaws.com 192.0.2.10 EC2 instances are assigned separate public and private IP address numbers. Copyright 2012 Kaazing Corporation 10 kaazing.com
Record the values of both IP addresses because these will be used later when configuring and using the Gateway. In the preceding screenshot, notice the following information: c. The private IP address is listed explicitly in the instance details. For example: 192.0.2.10. d. The public IP address of the instance is derived from the four decimal numbers following the ec2 value in the Public DNS entry using dotdecimal notation. For example, if the Public DNS entry is: ec2-192.168.10.25.compute-1.amazonaws.com Then, the public IP address of this instance is defined using the four decimal numbers (shown in bold typeface) separated by dots. For example: 192.168.10.25. Connect to the EC2 Server 1. In a terminal command shell, navigate to the location of the private key file that was downloaded when setting up this instance (Section 1, Step 10). 2. Connect to the EC2 server with a Secure Shell (SSH) client using one of the following methods. Mac and Linux users: a) Change the permission of the key file to allow read and write access by the owner only: chmod 600 key-file-name.pem b) Use the ssh command to connect to the instance: ssh -i key-file-name.pem -o ServerAliveInterval=10 ec2- user@xx.xx.xx.xx In the command: e. key-file-name.pem is the private key for this instance f. xx.xx.xx.xx is the external IP address of your server g. The ServerAliveInterval option prevents the ssh session from automatically disconnecting after a period of inactivity Copyright 2012 Kaazing Corporation 11 kaazing.com
Windows users: Use the PuTTY client to connect to the server. Notes regarding this client: h. The PuTTY client is available for download here: http://www.chiark.greenend.org.uk/~sgtatham/putty/). i. Detailed instructions provided by Amazon at the following URL describe how to configure the PuTTY client and connect to the EC2 instance: j. http://docs.amazonwebservices.com/amazonec2/gsg/2006-06-26/ k. Use the username ec2-user when logging in to the EC2 instance. Note: The first time you connect to the EC2 server, a message displays to indicate that the authenticity of the new server cannot be established. When prompted with the question Are you sure you want to continue connecting (yes/no)? type yes and press enter. Download Kaazing WebSocket Gateway Now that you have connected to the EC2 cloud server, note that the following steps are performed from the command line on the EC2 instance. The /home/ec2-user is the home directory for ec2-user (and it is the default location when you log in). 1. Download Kaazing WebSocket Gateway software using the wget command, or download the software from the Kaazing download page to your local machine and then transfer the file to the cloud machine using FTP. You can download either the Base 1 or Full 2 option for your operating system. For example, you would use the following command to download the full Gateway software for Linux, UNIX, or Mac, being sure to enter the entire command on one line: wget http://kaazingcorp.cachefly.net/com/download/html5/3.2.0.9/kaazingwebsocket-gateway-html5-3.2.0.tar.gz The command downloads the HTML5 Edition 3.2.0 version of the Gateway with a Development License. The Development License allows for full 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, enter the following command for Linux, UNIX, and Mac: tar -xf kaazing-websocket-gateway-html5-3.2.0.tar.gz 1 Base: Contains the minimal download of the Gateway for experienced users who are ready to use the Gateway in production. 2 Full: Contains the Base download plus the Gateway documentation and the services needed to run the Gateway demos. Copyright 2012 Kaazing Corporation 12 kaazing.com
3. Verify that the root user s home directory contents are similar to the following: kaazing-websocket-gateway-html5-3.2.0 kaazing-websocket-gateway-html5-3.2.0.tar.gz Prepare the Gateway Configuration File After you have installed the Gateway, you must configure some properties for the Gateway to run in the cloud. There are two types of Gateway configuration files: gateway-config-minimal.xml contains the minimal set of properties necessary to run the Gateway. If you downloaded the Base product, then the GATEWAY_HOME/conf directory includes only the gateway-configminimal.xml file. gateway-config.xml contains a complete set of Gateway properties, including the properties and services needed to run the Gateway documentation and demos. If you downloaded the Full installation (as described in the Download Kaazing WebSocket Gateway section, then both the gateway-config.xml and gatewayconfig-minimal.xml files are included in the GATEWAY_HOME/conf directory. This example in this paper downloads the Full installation and describes modifying the GATEWAY_HOME/conf/gateway-config.xml file. To learn more about the properties you use to configure the Gateway, see the Administrator s Guide. Perform the following steps to configure the Gateway to run on the cloud server: 1. On the cloud server, navigate to the Kaazing configuration directory: cd ~/kaazing-websocket-gateway-html5-3.2.0/conf/ 2. Edit the configuration file gateway-config.xml. vi editor users Open the file with the following command and skip to step 3. vi gateway-config.xml emacs users a) Install the emacs editor using the following command: apt-get install emacs Copyright 2012 Kaazing Corporation 13 kaazing.com
If asked if the size is okay ( Is this ok [y/n]: ), type y and press enter. b) Open the file in emacs using the following command and then skip to step 3: emacs gateway-config.xml Users who are unfamiliar with vi or emacs The use of a secure FTP client combined with local editing is recommended. The following steps outline this approach. a) Install one of the following secure FTP clients on your local platform: - WinSCP (Windows) - http://winscp.net/eng/download.php - Cyberduck (Mac) - http://cyberduck.ch - gftp (Linux) - http://gftp.seul.org/ b) Install the vsftpd secure ftp daemon on your EC2 instance using the command: apt-get install vsftpd If asked if the size is okay ( Is this ok [y/n]: ), type y and press enter. c) Start the server daemon using the command: sudo vsftpd d) Use your secure FTP client to transfer the file gateway-config.xml to your local platform for local editing. Perform steps 3 through 6 and then transfer the configuration file back to the EC2 instance. 3. Edit the property defaults section in the GATEWAY_HOME/conf/gatewayconfig.xml to set the default values for the Gateway hostname and port properties. Change the gateway.hostname property value from localhost to either the host name or the (external) IP address of the instance. The external IP address was determined during the EC2 instance setup in Section 1, Step 15 and is a four-number sequence using the dot-decimal notation, such as 192.168.10.25. Copyright 2012 Kaazing Corporation 14 kaazing.com
The following example uses the default (supplied) ports to bind the /base (port 8000) and the default /extras (port 8001) to the Gateway host http://192.168.10.25. <properties> <property> <name>gateway.hostname</name> <value>192.168.10.25</value> </property> <property> <name>gateway.base.port</name> <value>8000</value> </property> <property> <name>gateway.extras.port</name> <value>8001</value> </property> </properties> 4. Edit the Directory Service section of the gateway-config.xml file to bind the Gateway base port. Add network protocol bindings for the gateway base port in an <acceptoptions> element located just after the directory properties and just before the default <auth-constraint> element. Copyright 2012 Kaazing Corporation 15 kaazing.com
The following example shows the additions in bold typeface: <service> <accept>${gateway.hostname}:${gateway.base.port}/</accept> <type>directory</type> <properties> <directory>/base</directory> <welcome-file>index.html</welcome-file> <options>indexes</options> </properties> <accept-options> <http.bind>${gateway.base.port}</http.bind> </accept-options> <!-- <auth-constraint> <require-role>authorized</require-role> </auth-constraint> --> Copyright 2012 Kaazing Corporation 16 kaazing.com
</service> <service> <accept>http://${gateway.hostname}:${gateway.extras.port}/</accept> <type>directory</type> <properties> <directory>/extras</directory> <welcome-file>index.html</welcome-file> <options>indexes</options> </properties> <!-- <auth-constraint> <require-role>authorized</require-role> </auth-constraint> --> </service> Copyright 2012 Kaazing Corporation 17 kaazing.com
5. Configure network protocol bindings for all services. In the Service Defaults section of the gateway-config.xml file, add the <service-defaults> and <accept-options> elements, and configure the <protocol.bind> element to specify a default value for each network protocol binding for all services. These elements must be added to the file before any mime-mapping entries, as shown in the following sample network protocol bindings for the ws and http services. The following example shows the added lines in bold typeface: <service-defaults> <accept-options> <ws.bind> ${gateway.extras.port}</ws.bind> <http.bind>${gateway.extras.port}</http.bind> </accept-options> <mime-mapping> <extension>html</extension> <mime-type>text/html</mime-type> </mime-mapping> <mime-mapping> <extension>js</extension> Copyright 2012 Kaazing Corporation 18 kaazing.com
<mime-type>text/javascript</mime-type> </mime-mapping>... </service-defaults> Note: 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. 6. Save the configuration file and exit the text editor. Copyright 2012 Kaazing Corporation 19 kaazing.com
Start Kaazing WebSocket Gateway When you start the Gateway: If you downloaded the Base product, then the Gateway is started using the properties in the gateway-config-minimal.xml file. If you downloaded the Full product, then the Gateway is started using the properties in the gateway-config.xml file, by default. If there is no gatewayconfig.xml file, then the Gateway is started using gateway-configminimal.xml. The example in this paper downloaded the Full product. Thus, the Gateway is started using the properties in the gateway-config.xml file. Perform the following steps to start the Gateway: 1. Navigate to the Kaazing bin directory. In the following example, edition refers to the Gateway Edition (such as HTML5 or JMS) and release is the release number (for example, kaazing-websocketgateway-html5-3.2.0). cd ~/kaazing-websocket-gateway-edition-release/bin 2. Start the Gateway using the following command: For example:./gateway.start & cd ~/ kaazing-websocket-gateway-html5-3.2.0/bin./gateway.start & A sequence of messages similar to the following example may be displayed. Confirm that the lines similar to those in bold typeface below, but showing your IP addresses, are displayed. (In this example 192.168.10.25 is the public IP address and 0.0.0.0 means that any IP address may access these ports). In the following example, the lines shown in bold typeface contain the URL of the root of the web page structure (for both the /base and /extras directories) served by the Gateway s built-in HTTP server. INFO Kaazing WebSocket Gateway HTML5 Edition (3.2.0) INFO Configuration file: GATEWAY_HOME/conf/gateway-config.xml INFO Checking license information INFO Found license: Developer License, Maximum 50 connections, See Copyright 2012 Kaazing Corporation 20 kaazing.com
LICENSE.txt INFO Starting server INFO Starting services INFO http://192.168.10.25:8000/ @ 0.0.0.0:8000 INFO http://192.168.10.25:8001/ @ 0.0.0.0:8001 INFO Started services INFO Started server successfully in 0.033 secs at 2044-06-06 00:54:17 To Stop the Gateway on Windows: Press CTRL + C in the command prompt that was used to start the Gateway, or close the command prompt. To Stop the Gateway on Linux, UNIX, and Mac: Use the following commands to get the process ID [Process ID] of the Kaazing process, and then use the process ID in the kill command to stop the Gateway: ps ef grep kaazing kill [Process ID] Test Kaazing WebSocket Gateway 1. Test the HTTP server of the Gateway by pointing your browser to http://xx.xx.xx.xx:8001, where xx.xx.xx.xx is the public IP address of your server. The main Kaazing welcome page should display similar to the following. Copyright 2012 Kaazing Corporation 21 kaazing.com
The remaining steps in this whitepaper describe how to run the WebSocket Echo demo to further verify the Gateway setup on the cloud. 2. By default, the properties in the gateway-config.xml file enable the Gateway on the EC2 instance to provide an echo service on port 8001 and to host static files (using the "directory" service) on the Web on port 8000. The example in this whitepaper uses the default Gateway property settings, as shown in the following echo service section of the Gateway configuration file: <!-- Echo service --> Copyright 2012 Kaazing Corporation 22 kaazing.com
<service> <accept>ws://${gateway.hostname}:${gateway.extras.port}/echo</accept> <type>echo</type> <cross-site-constraint> <alloworigin>http://${gateway.hostname}:${gateway.extras.port}</allow-origin> </cross-site-constraint> </service> 3. On the Kaazing Welcome page, click Demos to go to the Kaazing JavaScript HTML5 Core demonstrations page. For example: Copyright 2012 Kaazing Corporation 23 kaazing.com
4. On the Demos page, click WebSocket - Echo Demo to start the echo demo. Copyright 2012 Kaazing Corporation 24 kaazing.com
5. In the Location field of WebSocket Demo page, enter the URL of the echo service if it isn t already filled in, and click Connect and then Send. You should see the messages similar to the following in the Log Messages area, indicating that this browser window has successfully connected to the Gateway. RESPONSE: Hello, WebSocket! SENT: Hello, WebSocket! CONNECTED CONNECT: ws://192.168.10.25:8001/echo Copyright 2012 Kaazing Corporation 25 kaazing.com