February 26, 2016 | Written by: Charles Martin
Categorized: Compute Services | How-tos
Share this post:
Following on from Adrian’s post on the Message Hub Incubator, this tutorial is about the first feature that we are developing, the MQ Light API.
This tutorial shows how to deploy a Node.js messaging app using the Message Hub Incubator Bluemix service and its MQ Light API. After following it you’ll understand how the service works, see the benefits of worker offload, and be able to get started developing your own applications.
Why use the MQ Light API?
The MQ Light API provides a simple but powerful AMQP-based messaging API which can used on a standalone machine, as part of an on-premise enterprise messaging solution or in the cloud.
By using the API to connect to the Message Hub Incubator service in Bluemix, applications can take advantage of the highly scalable, high throughput, secure cloud messaging bus that Message Hub provides, simplifying connecting on and off-premise applications as well as providing easy access to streaming services such as analytics.
The MQ Light API is currently available in Java, Node.js and Ruby. They all work in a similar way, but here we’ll use Node.js.
What does the sample do?
The sample app is actually composed of two simple apps which work together:
- MQL.fishalive.node.frontend – A web front-end where a user types in a sentence to be capitalized. The app breaks the sentence down into words which are sent to the back-end application below as a series of messages for processing.
- MQL.fishalive.node.backend – The back-end processing application receives the words from the front-end, capitalizes them and sends them back. Any number of the back-end application can be run according to the processing capacity required.
Although the work performed by the sample is trivial, it demonstrates:
- How easy it is to get disjoint apps talking to each other using the MQ Light Service. The apps could just as easily be running outside of Bluemix either on a local server or another cloud.
- The simplicity of using the MQ Light API to perform worker offload, a classic messaging scenario, where a front end app which needs to stay responsive to users offloads intensive operations to a back-end app which can be seamlessly scaled up or down as needed.
Get the sample code and deploy it
Complete the following steps:
Download the sample
The sample source code is available in GitHub. To download, clone the repository for the language you want to use. For Node.js:
git clone https://github.com/ibm-messaging/mqlight-fishalive-node
(To try out the Java or Ruby samples substitute ‘node’ in the URL above with either ‘java’ or ‘ruby’).
Deploying to Bluemix
To create an instance of the Message Hub Incubator service for the sample to use, run the following Cloud Foundry command:
cf cs MessageHubIncubator experimental MQLight-sampleservice
This creates an instance of the MessageHubIncubator service, named
, using the experimental (free) payment plan. Services can also be created using the Bluemix WebGUI console by selecting ‘Catalog’ from the main menu and clicking on the tile for the service.
Tip: The service can be given any name, however the two ‘services’ fields in the sample’s
manifest.yml file must be updated to match. This ensures that when the sample apps are deployed they are bound to the correct service.
To deploy the sample to Bluemix, run the
cf push command from the directory where the sample was cloned. The
manifest.yml file in this directory contains the information needed by Bluemix to deploy the sample. The
manifest.yml file is optional, but it avoids having to specify all the arguments each time you run the command. For a full list of options, run the command
cf push -h.
Once the apps finish deploying, you can use the command
cf apps to check their status (or take a look at them in the Bluemix dashboard).
To try the sample, copy the URL listed for the front-end app in to a browser. You’ll see something similar to the screenshot shown at the start of the tutorial.
Clicking ‘Submit work’ triggers the front-end app to divide the given sentence into words and publish them as messages to a topic called
The back-end worker apps are subscribed to this topic and on receiving each message, capitalizise it and return it using the topic
mqlight/sample/wordsuppercase/. As each back-end worker app is subscribed to the same topic, to ensure each message is only received by one of them the sample uses a feature of the MQ Light API called a ‘shared destination’. This ensures messages are distributed fairly between all subscribing applications rather each receiving its own copy of every message.
The front-end application is subscribed to the topic
mqlight/sample/wordsuppercase/ and displays each word as it’s returned.
In a real-world scenario, if more processing power was required, the capacity of the back-end app could be changed by changing the number of back-end instances. For example, to scale out to 5 instances, run the command
cf scale MQL.sample.node.backend -i 5. That’s it! You’ve deployed the samples, used the Incubator service to allow them to communicate and experimented with the principals of worker offload.
If you’d like to understand more about how the samples used the MQ Light API to achieve the above, take a look at the
app.js files in the
backend directories at the location the sample was cloned.
To find out more about the Message Hub Incubator service and its latest features, see IBM Message Hub Incubator overview and get started with it in the Bluemix Catalog. Or try the full Message Hub service in the catalog.