Installation of a Kaazing WebSocket Gateway on an Amazon EC2 ...

Bergmans Mechatronics LLC

Installation of a  Kaazing WebSocket Gateway  on an Amazon EC2 Micro Instance  The Kaazing WebSocket Gateway, developed by Kaazing Corporation (www.kaazing.com), is a software application that allows continuous, bidirectional communication between web browsers and servers using the HTML5 WebSocket standard. The Kaazing 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: •

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 simple, 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 has been developed to promote the rapid setup of the Kaazing Gateway in a cloud environment. It contains a detailed, step-by-step guide to installing the Gateway on an Amazon Elastic Compute Cloud (EC2) cloud server provided by Amazon aws.amazon.com. The use of the free Amazon Micro instance makes these procedures ideal for cost-constrained applications. Details on the restrictions applied to this instance type are available in Appendix A. Kaazing offers three different editions of the Gateway product. This document describes the installation of the Dragonfire edition which is designed for developers using the STOMP, AMQP and XMPP messaging protocols. Additional information on the different Gateway editions is available at www.kaazing.com/download.html The main sections of this guide are as follows: 1) Create an EC2 Server Instance 2) Connect to the EC2 Server 3) Download the Kaazing Gateway 4) Start the ActiveMQ Message Broker 5) Prepare the Kaazing Gateway Configuration File 6) Start the Kaazing Gateway 7) Test the Kaazing Gateway Appendix A AWS Micro Instance Restrictions Appendix B Apache ActiveMQ Start Messages The estimated time to complete the steps presented in this guide is one to two hours. Please contact John Bergmans ([email protected]) if you have any questions or comments about this document.

BML-Doc-2011-2

1

1) Create an EC2 Server Instance  The steps below describe the set up of an Amazon Elastic Compute Cloud (EC2) instance. Additional information about the EC2 system can be found in EC2 User Guide at http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/. 1. Point your browser to http://aws.amazon.com. 2. If you already have an Amazon Web Services (AWS) 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.

c.

On the Elastic Compute Cloud page, click Sign Up for Amazon EC2.

BML-Doc-2011-2

2

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.

g. Proceed through the three-step Identity Verification by Telephone process.This process involves entering your phone number. When the AWS system calls your number, enter on the phone the PIN number presented in the browser. Click Continue upon completion of the identity verification.

BML-Doc-2011-2

3

h. Review your selections and click Complete Sign Up.

i.

Once your AWS account has been activated, sign in on at http://aws.amazon.com and proceed to step 4.

4. Select the Amazon EC2 tab. 5. Click Launch Instance.

BML-Doc-2011-2

4

6. Select the Basic 32-bit Amazon Linux AMI 2011.02.1 Beta.

7. Select the Micro Instance Type. While there is no charge for the initial setup of this instance type, as described in Appendix A, there are limitations to the free use of this type. The basic Gateway testing steps that are described below are however within the limitations. Click Continue.

8. On the Advanced Instance Options page, select all the defaults by clicking Continue.

BML-Doc-2011-2

5

9. 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. The key pair is automatically downloaded to your download folder. d) Click Continue.

11. On the Configure Firewall page: a) Select Create a new Security Group. b) Enter a Group Name and Group Description. c) Enable Firewall ports by entering individual ports, or ranges of ports in the Port range field. In this step, enable the following individual ports and port ranges; After each port or port range is entered in the Port range field, click + Add Rule. 21-22 80 443 2020 5942-5943 8000-8001 8080-8081 8161 9000-9001 9090-9091 61613-61616-61617-61222 BML-Doc-2011-2

6

After entering the port information, the Wizard should appear similar to the following screenshot. Click Continue.

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. See the chapter about “Using Security Groups” in the EC2 User Guide for additional information on this subject.

BML-Doc-2011-2

7

12. The Review page appears. Click Launch to start the instance.

13. Click Close on the final page of the wizard to return to the EC2 dashboard. 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.

BML-Doc-2011-2

8

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:

EC2 instances are assigned separate public and private IP address numbers. Record the values of both IP addresses because these will be required when configuring and using the Kaazing Gateway. In the preceding screenshot, notice that: a. The private IP address is listed explicitly in the instance details. For example: 10.210.67.51. b. The public IP address of the instance is derived from the four decimal numbers following the “ec2” value in the Public DNS entry and uses dot-decimal notation. For example, if the Public DNS entry is: ec2-50-19-35-250.compute-1.amazonaws.com then, the public IP address of this instance, defined using the four decimal numbers (shown in bold typeface) is 50.19.35.250.

BML-Doc-2011-2

9

2) Connect to the EC2 Server  1. Connect to the EC2 server with a Secure Shell (SSH) client using one of the following methods. Mac and Linux users: a) Open a terminal window and navigate to the location of the private key file that was downloaded when setting up this instance (Section 1, Step 10). b) Change the permission of the key file to allow read and write access by the owner only: chmod 600 KEYFILENAME.pem c) Use the ssh command to connect to the instance: ssh -i KEYFILENAME.pem -o ServerAliveInterval=10 [email protected]

In the command: • KEYFILENAME.pem is the private key for this instance • xx.xx.xx.xx is the public IP address of your server • The ServerAliveInterval option prevents the ssh session from automatically disconnecting after a period of inactivity Windows users: Use the PuTTY client to connect to the server. Notes regarding this client: • • • •

The PuTTY client is available for download here: http://www.chiark.greenend.org.uk/~sgtatham/putty/). Note the location of the private key that was downloaded when setting up this instance (Section 1, Step 10). This file will be required in the instructions referenced in the following bullet. Detailed instructions provided by Amazon at the following URL describe how to configure the PuTTY client and connect to the EC2 instance: http://docs.amazonwebservices.com/AmazonEC2/gsg/2006-06-26/ Use the username ec2-user when logging in to the EC2 instance.

2. Whether using ssh or PuTTY to connect to the EC2 server, on your first connection attempt, a message will appear indicating that the authenticity of the new server can’t be established and you will be prompted with a question similar to “Are you sure you want to continue connecting (yes/no)?” Type yes and press enter.

BML-Doc-2011-2

10

3) Download the Kaazing 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 and that /home/ec2-user is the home directory for ec2-user (and the default location when you log in): 1. Download the Kaazing WebSocket Gateway software using the following command (Enter the entire command on one line): wget http://kaazingcorp.cachefly.net/com/download/kaazingenterprise-gateway-demos-9.06_20-bin.tar.gz This command downloads the Dragonfire 9.06_20 version of the Gateway with a Development License. The Development License allows for full functionality for up to 50 connections. Further information on licensing and the different Gateway versions is available from http://www.kaazing.com/download.html 2. Extract the contents of the downloaded file to your home directory using: tar -xf kaazing-enterprise-gateway-demos-9.06_20-bin.tar.gz

3. The results of a listing of the root user’s home directory should look similar to the following: drwxr-xr-x 9 ec2-user ec2-user 4096 drwxrwxr-x 8 ec2-user ec2-user 4096 gateway-9.06_20 -rw-rw-r-- 1 ec2-user ec2-user 51393007 gateway-demos-9.06_20-bin.tar.gz drwxr-xr-x 11 ec2-user ec2-user 4096

May 1 2008 apache-activemq-5.1.0 May 15 16:32 kaazing-enterpriseApr 20 07:23 kaazing-enterpriseSep 25

2008 openfire-3.6.0a

BML-Doc-2011-2

11

4) Start the ActiveMQ Message Broker  1. Start the ActiveMQ message broker using the following command: nohup ~/apache-activemq-5.1.0/bin/activemq & Note: To ensure that the message broker is not terminated upon closing your shell session, start ActiveMQ using the nohup command. If termination of the broker upon closing your shell session is acceptable, run the ActiveMQ message broker using the following command: ~/apache-activemq-5.1.0/bin/activemq & The resulting start sequence messages are shown in Appendix B. The ampersand symbol (“&”) at the end of this command causes the message broker to run as a background process. 2. Optionally, you can verify the running state of Apache ActiveMQ using the ActiveMQ Web Console. Invoke the console by pointing your browser to http://xx.xx.xx.xx:8161/admin, (where xx.xx.xx.xx is the public IP address of your server).

To Stop ActiveMQ: For both Windows and Unix installations, you can stop ActiveMQ by entering CTRL-C in the console or command shell in which it is running. If ActiveMQ was started in the background on Unix, then the process can be killed with the following commands (where [PID] is the process id of the ActiveMQ process): ps –ef | grep activemq kill [PID]

BML-Doc-2011-2

12

5) Prepare the Kaazing Gateway Configuration File  1. Navigate to the Kaazing configuration directory: cd ~/kaazing-enterprise-gateway-9.06_20/conf/ 2. Edit the configuration file gateway-config.xml. a) vi editor users can open the file using the following command and then skip to step 3. vi gateway-config.xml b) emacs users i.

Install the emacs editor using the following command: sudo yum install emacs If asked if the size is okay (“Is this ok [y/N]:”), then type y and press enter.

ii.

Open the file in emacs using the following command: emacs gateway-config.xml

iii.

Skip to step 3.

c) For 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. i.

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/

ii.

Install the vsftpd secure ftp daemon on your EC2 instance using the command: sudo yum install vsftpd If asked if the size is okay (“Is this ok [y/N]:”), then type y and press enter.

iii.

Start the server daemon using the command: sudo vsftpd

iv.

Use your secure FTP client to transfer the file gateway-config.xml to your local platform for local editing. Proceed with steps 3 through 5 below, and then transfer the configuration file back to the EC2 instance.

BML-Doc-2011-2

13

3. Make the following edits, highlighted below, to the Directory element of the gateway-config.xml file. a) For the first location (http://localhost:8000/) in the Directory element, replace localhost with the public IP address of your instance. The public 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 50.19.35.250. In the entry highlighted in the example below, this value is represented as xx.xx.xx.xx. b) Add an element containing an element. Within this latter element, enter the private IP address of your EC2 instance (see Section 1, Step 15) and the port on which this service is provided (port 8000). The private IP address is a four number sequence such as 10.210.67.51 and is represented below as yy.yy.yy.yy. This element allows the directory service of the Gateway to provide service on the public IP address and port combination. http://xx.xx.xx.xx:8000/ https://localhost:9000/ yy.yy.yy.yy:8000 directory / index.html AUTHORIZED -->

BML-Doc-2011-2

14

4. Make the following three modifications, highlighted below, to the Proxy element. a) Change localhost in the first element to the public IP address of your instance. This address is represented below as xx.xx.xx.xx. b) Add the element shown. In this element substitute yy.yy.yy.yy with the private IP address of your instance. c) Modify the first of the two elements by substituting localhost with the public IP address of your instance: ws://xx.xx.xx.xx:8000/activemq wss://localhost:9000/activemq yy.yy.yy.yy:8000 proxy stomp://localhost:61613 AUTHORIZED --> http://xx.xx.xx.xx:8000 https://localhost:9000 5. Save the configuration file and exit the text editor. If you edited the configuration file locally, transfer it back to the EC2 instance using your secure FTP client.

BML-Doc-2011-2

15

6) Start the Kaazing Gateway  1. Navigate to the Kaazing bin directory cd ~/kaazing-enterprise-gateway-9.06_20/bin/ 2. Start the Gateway using the command ./gateway.start & A sequence of messages similar to the following example is displayed. Confirm that two lines similar to those highlighted below, but showing your IP addresses, are displayed. (In this example 50.19.35.250 is the public IP address and 10.210.67.51 is the private IP address). The first highlighted line contains the URL of the root of the web page structure served by the Gateway’s built-in HTTP server. The second highlighted line contains the URL of the ActiveMQ proxy service. INFO Checking license information INFO No valid Kaazing enterprise license found INFO Using Kaazing developer license INFO For licensing information see http://www.kaazing.com/license INFO Node-ID file can be found at: /home/ec2-user/kaazing-enterprisegateway-9.06_20/license/domU-12-31-39-09-3C-C5.id INFO Starting server INFO Starting services INFO http://50.19.35.250:8000/ @ 10.210.67.51:8000 INFO http://localhost:8000/keyring INFO http://localhost:8000/session INFO https://localhost:9000/ INFO https://localhost:9000/keyring INFO https://localhost:9000/session INFO sse+ssl://localhost:9000/sse INFO sse://localhost:8000/sse INFO ws://50.19.35.250:8000/activemq @ 10.210.67.51:8000 INFO ws://localhost:8000/amqp INFO ws://localhost:8000/darkstar INFO ws://localhost:8000/freenode INFO ws://localhost:8000/gtalk INFO ws://localhost:8000/jabber INFO ws://localhost:8000/stomp-driver INFO ws://localhost:8000/stomp-jms INFO ws://localhost:8001/echo INFO wss://localhost:9000/activemq INFO wss://localhost:9000/amqp INFO wss://localhost:9000/darkstar INFO wss://localhost:9000/freenode INFO wss://localhost:9000/gtalk INFO wss://localhost:9000/jabber INFO wss://localhost:9000/stomp-driver INFO wss://localhost:9000/stomp-jms INFO wss://localhost:9001/echo INFO Started services INFO Starting management INFO jmx://localhost:2020/ INFO Started management INFO Started server successfully in 0.454 secs at 2011-05-23 21:23:54

BML-Doc-2011-2

16

To Stop the Gateway: For both Windows and Unix installations, you can terminate the Gateway following commands (where [PID] is the process id of the ActiveMQ process): ps –ef | grep kaazing kill -9 [PID]

BML-Doc-2011-2

17

7) Test the Kaazing Gateway  1. Test the HTTP server of the Gateway by pointing your browser to http://xx.xx.xx.xx:8000 where xx.xx.xx.xx is the public IP address of your server. The main Kaazing welcome page should display.

The following steps verify that the Gateway is configured to interface with the ActiveMQ message broker. These steps also demonstrate the Publish/Subscribe messaging model of ActiveMQ. 2. Point your browser to the Streaming Text Orientated Messaging Protocol (STOMP) demo page: http://xx.xx.xx.xx:8000/demo/demo.html#stomp (where xx.xx.xx.xx is the public IP address of your server). For example:

BML-Doc-2011-2

18

3. Click Connect. A message similar to the following text should appear in the Log messages window indicating that this browser window has successfully connected to the ActiveMQ Message broker via the Gateway.

4. In the Destination field under “Subscribe, send messages, and unsubscribe to a particular destination”, enter the following STOMP topic name: /topic/test_topic 5. Click Subscribe to subscribe to this STOMP topic. The following message from the ActiveMQ message broker should appear: SUBSCRIBE: /topic/test_topic This browser will now automatically receive messages published on the STOMP topic /topic/test_topic 6. Open a second browser and point it to the same STOMP demo URL specified in Step 2. Note that this browser can be either on the same computer as the first browser or a separate computer. BML-Doc-2011-2

19

7. In the second browser, click Connect. A message similar to that shown in Step 3 should display in the Log messages window. 8. In the Destination field under “Subscribe, send messages, and unsubscribe to a particular destination”, enter the following STOMP topic name: /topic/test_topic 9. In the Message field, enter some arbitrary test message. For example: This is a test message 10. Click Send 11. In the Log window of the second browser, you should see: SEND: This is a test message /topic/test_topic 12. In the Log window of the first browser you should immediately see the message transmitted from the second browser. For example:

If the message from the second browser appears in the Log messages of the first browser, then you have successfully set up the Kaazing WebSocket Gateway on an Amazon EC2 Micro instance!

BML-Doc-2011-2

20

Appendix A  AWS Micro Instance Restrictions  As of May 2011, the following information was published on aws.amazon.com regarding the restrictions on AWS Micro Instances. New AWS customers will receive the following EC2 services each month for one year. Usage is calculated each month across all regions and automatically applied to your bill unused monthly usage will not roll over. Restrictions apply; see offer terms for more details. • • • •

750 hours of Amazon EC2 running Linux/Unix Micro Instance usage (613 MB of memory and 32-bit and 64-bit platform support) - enough hours to run steady state each month 750 hours of Elastic Load Balancing plus 15 GB data processing 10 GB of Amazon Elastic Block Storage (EBS) plus 1 million IOs, 1 GB snapshot storage, 10,000 snapshot Get Requests and 1,000 snapshot Put Requests 15 GB of bandwidth in and 15 GB of bandwidth out aggregated across all AWS services

BML-Doc-2011-2

21

Appendix B  Apache ActiveMQ Start Messages  ACTIVEMQ_HOME: /root/apache-activemq-5.1.0 ACTIVEMQ_BASE: /root/apache-activemq-5.1.0 Loading message broker from: xbean:activemq.xml INFO BrokerService - Using Persistence Adapter: AMQPersistenceAdapter(/root/apache-activemq-5.1.0/data) INFO BrokerService - ActiveMQ 5.1.0 JMS Message Broker (localhost) is starting INFO BrokerService - For help or more information please see: http://activemq.apache.org/ INFO AMQPersistenceAdapter - AMQStore starting using directory: /root/apache-activemq-5.1.0/data INFO KahaStore - Kaha Store using data directory /root/apache-activemq-5.1.0/data/kr-store/state INFO AMQPersistenceAdapter - Active data files: [] INFO KahaStore - Kaha Store using data directory /root/apache-activemq-5.1.0/data/kr-store/data INFO TransportServerThreadSupport - Listening for connections at: tcp://TestServer1.example.com:61616 INFO TransportConnector - Connector openwire Started INFO TransportServerThreadSupport - Listening for connections at: ssl://TestServer1.example.com:61617 INFO TransportConnector - Connector ssl Started INFO TransportServerThreadSupport - Listening for connections at: stomp://TestServer1.example.com:61613 INFO TransportConnector - Connector stomp Started INFO TransportServerThreadSupport - Listening for connections at: xmpp://TestServer1.example.com:61222 INFO TransportConnector - Connector xmpp Started INFO BrokerService - ActiveMQ JMS Message Broker (localhost, ID:TestServer1.example.com-38063-13028785034340:0) started INFO log - Logging to org.slf4j.impl.JCLLoggerAdapter(org.mortbay.log) via org.mortbay.log.Slf4jLog INFO log - jetty-6.1.9 INFO WebConsoleStarter - ActiveMQ WebConsole initialized. INFO /admin - Initializing Spring FrameworkServlet 'dispatcher' INFO log - ActiveMQ Console at http://0.0.0.0:8161/admin INFO log - ActiveMQ Web Demos at http://0.0.0.0:8161/demo INFO log - RESTful file access application at http://0.0.0.0:8161/fileserver INFO log - Started [email protected]:8161

BML-Doc-2011-2

22