Introduction to BlueMix Updated: Jan 24, 2014 dev@Pulse Lab Mentors:

Lee Surprenant, IBM Software Engineer lmsurpre@us.ibm.com @IBMjStart @lmsurprenant

Jay Allen, IBM Software Architect, Managing Consultant allenj@us.ibm.com @IBMjStart

Sanjay Joshi, IBM Project Manager, jStart Cloud-related projects joshisa@us.ibm.com @IBMjStart

This lab shows how to create a Twitter analysis application that runs on IBM BlueMix and makes use of BlueMix services such as MongoDB. The application also makes use of external social data services provided by Twitter and Klout. You have the option of creating the application using either node.js, Java, or Python since BlueMix is a scalable polyglot application platform. When the lab is completed, your application will be running on the web and will be able to be administered (stop, start, monitor) via the BlueMix user interface. Lab options to learn about the BlueMix environment:

Lab A Node.js Twitter Influencer Analyzer application on BlueMix Lab B Java Twitter Influencer Analyzer application on BlueMix Lab C Python Twitter Influencer Analyzer application on BlueMix

The Node.js Twitter Influencer Analyzer is a web application that collects data from Twitter Klout and Google Maps to display influence relationships between twitter users. Link to the lab source code is available at https://github.com/ibmjstart/bluemix-sample-tia-node The web app is constructed as a single-page-app using AngularJS. The web resources html, css, and js files are located in the [www] directory. Each 'page' in the app is designed as a separate html view, with a controller to go with, located in the [www/controllers] directory. The web app issues XHR requests back to the server to get dynamic data from klout and twitter. To make the system appear non-laggy, the data previously returned from an XHR request is shown on the web page before the more recent data is returned from the server. Often, the data won't change. The list of users that have been explored, and other not-frequently changing data is persisted to [localStorage], bypassing the need to store that personal data 'in the cloud.' Google maps are generated in the browser using the Google Static Maps API.

What you'll need to build this application 1. A basic familiarity with Node.js 2. A Node.js development environment 3. MongoDB installed only if you want to run the server locally. (But the value of

BlueMix is that you can just use the MongoDB service on the Cloud with nothing installed locally.)

4. A twitter account 5. This app uses the following cloud services:

o MongoDB

Setting up You will need node.js installed (version 0.8.x or greater), which comes with npm (version 1.1.x or greater)

If you want to run the server locally, you will also need MongoDB installed.

Lab A Node.js Twitter Influencer Analyzer application on BlueMix

Once you have that in order: Create a git clone of the TIA repository; e.g., git clone https://github.com/ibmjstart/bluemix-sample-tia-node.git run 'npm install' to install node pre-req modules

configuration You should create a config.json in the root directory. It's listed in .gitignore, so will not be stored in git. A sample is available in config.json.txt.

Set the Klout and Twitter keys as appropriate.

For Klout, you can obtain a developer key here: http://klout.com/s/developers/home

For Twitter, you can obtain a key and secret here: https://dev.twitter.com/

Note that you just need simple keys here; for neither klout nor twitter will the user ever "sign in" - this application only deals with public data.

To run locally, you will need a mongodb server running, at the URL: mongodb://localhost:27017. It will use a database named bluemix-sample-tia-node when run locally.

Option 1. Running on the Command Line Use one of the following:

node app.js node lib/cli.js npm start ./build.coffee serve (build serve on Windows) ./build.coffee watch (does not run on on Windows)

The first four commands all do the same thing.

./build.coffee watch is used at development time. It will watch the source directories, and restart the server when they change.

The server will print the URL at which it's available after it's started.

You should see something like this when you run:

Option 2. Running on Bluemix / Cloud Foundry o run the app on Bluemix, you will need to complete the following steps.

1. Login to Bluemix.

usage: $ cf login [-a API_URL] example: $ cf login -a https://api.ng.bluemix.net

2. Create an instance of the mongodb service.

usage: $ cf create-service SERVICE PLAN SERVICE_INSTANCE_NAME example: $ cf create-service mongodb 100 mongodbTIA

3. From the cloned Twitter Influencer App directory, push the app without starting it.

usage: $ cf push APP [--no-manifest] [--no-start] [-c COMMAND] example: $ cf push --no-manifest --no-start -c 'node app.js

4. Bind the mongodb service to the new app

usage: $ cf bind-service APP SERVICE_INSTANCE_NAME example: $ cf bind-service mongodbTIA

5. Start the app

usage: $ cf start APP example: $ cf start

(Note: the app has only been tested on node 0.8.x and above.)

That should be it! Head over to your app's URL to start exploring!

Conclusion: Exploring the app in the Browser Your application is now running on the Cloud on the BlueMix platform. You can explore the BlueMix User Interface at http://ng.bluemix.net to start and start your application.

bluemix-sample-tia-node: mongo: url: mongodb://localhost:27017/bluemix-sample-tia-node bluemix-sample-tia-node: connecting... bluemix-sample-tia-node: connected bluemix-sample-tia-node: --------------------------------------------------------------- bluemix-sample-tia-node: twitter bearer token retrieved bluemix-sample-tia-node: starting server on pid 82546 at http://localhost:8000

The app consists of 4 types of pages:

The home page, which lists all the twitter users you have explored

An individual's user page, displaying information about that user

The messages page, displaying error and informational messages

The help page, providing a legend of some of the symbols used

When you run the first time, there will be no users listed on the home page. Enter one in the prompter on the page, and press the Analyze button. That should take you to the individual's user page. When you traverse back to home (press the back button - or you can always click the 'Home' link at the top), you'll see that user in the list. As you explore more users, they will be pushed to the top of the list.

The list provides a "delete" button to remove the user from the list, a green badge showing their klout score, a search icon button which will display the individual's user page, and a twitter icon button which will take you to the user's twitter page.

The list of users is stored in your browsers local storage - it's not saved anywhere on the web.

The individual user page displays up to 4 things:

List of twitter users this user is influenced by

List of twitter users that are influenced by this user

Recent tweets

A Google map if any tweets are geo-coded

For each of the influenced by and influences users, their klout score badget, a search icon button, and twitter icon button are displayed. Click on the search icon button to display that user's individual user page.

For tweets which are geo-coded, a numeric badge link is displayed; click on that bad to display the referenced location in Google Maps.

The Java Twitter Influencer Analyzer is a web application that collects data from Twitter Klout and Google Maps to display influence relationships between twitter users. Link to the lab source code is available at https://github.com/ibmjstart/bluemix-java-sample-twitter-influence-app This app uses the following cloud services:

o MongoDB

Pushing the app using Eclipse

Step 1: Prerequisites

Download Source

The source for this app is at GitHub so, you can either download the zip file or clone the repository from the command line.

Download Zip

https://github.com/ibmjstart/bluemix-java-sample-twitter-influence-app/archive/master.zip

Git Clone: git clone https://github.com/ibmjstart/bluemix-java-sample-twitter-influence-app.git

Download Cloud Foundry Plug-in

You will also need to download the Cloud Foundry plug-in for Eclipse. To do this, go to Eclipse and follow the instructions below:

1. Click: Help > Eclipse Marketplace... 2. Search: "Cloud Foundry" 3. Look for the item titled: "Cloud Foundry Integration for Eclipse x.x.x" (It should be the first

listing) 4. Click: Install

Lab B Java Twitter Influencer Analyzer application on BlueMix

Step 2. Import the project into Eclipse

Next, you will need to import the project into Eclipse. There are two ways you can get the source into Eclipse:

Option A. Import the Eclipse project by following these instructions:

1. Start by cloning the repository, as described above

2. Open Eclipse 3. Select File->Import 4. Under the header labeled "General", click "Existing Projects Into Workspace" and click Next 5. Click "Browse" next to the first text field, and navigate to the cloned repository and find the

folder labeled "app" and click ok. 6. Under Projects you should now see a project called "twitter_influence_analyzer", make sure

the checkbox next to the "twitter_influence_analyzer" project is checked and then click Finish

7. You should now see the "twitter_influence_analyzer" project in your list of projects in Eclipse.

-OR-

Option B. Import the WAR File

1. Navigate to https://github.com/ibmjstart/bluemix-java-sample-twitter-influence-app/releases

2. Click the green button labeled "twitter_influence_analyzer.war" and that will download the WAR file.

3. Open Eclipse 4. Then File->Import 5. Scroll down to the "Web" section, expand that section and click WAR File then click Next. 6. Click next and then Finish and the project should be imported into Eclipse

Step 3. Acquiring External and Public APIs

This app uses some external APIs. You need to register the app with Twitter and Klout to get the keys and tokens.

Twitter v1.1 API

To access the Twitter API you need the consumer keys and access tokens, so you must register the app with Twitter. You can register your app here.

More information on how to register the app with Twitter

Klout API

You can register the app with Klout here. When you register with Klout, you'll get a Klout Key, which you can use to create a Klout Object as shown in the code.

Google Maps v3 API

This app uses the Google Maps v3 APIs. Google APIs are open for the developers and you do not need to register the app with Google. Here's the link for the Google Maps APIs.

Step 4. Configuring the Project Files

There are two files that need to be edited. You can do this directly in Eclipse or using your favorite text editor.

Filenames Path

twitter4j.properties klout.properties

Local: .../bluemix-java-sample-twitter-influence-app/app/src/

twitter4j.properties klout.properties Eclipse: Project_Name > Java Resources > src

The twitter credentials are entered in the file called twitter4j.properties. Simply copy and paste the credentials from your new app on twitter into the appropriate categories in the file. Additionally, the Klout API key is entered in the file called klout.properties.

Step 5. Deploying the app

Set up Bluemix Server

Make sure you are in the Java EE perspective in Eclipse.

1. In the bottom window section, select the Servers tab. (Alternatively, you can click: Window > Show View > Servers)

2. Right-Click inside the Servers panel and select New > Server 3. Select, Pivotal > Cloud Foundry and click Next. 4. Click Manage Cloud, then click Add 5. Enter: Bluemix as the name, and https://api.ng.bluemix.net as the URL 6. Click Finish, then click, OK 7. Enter your login information for Bluemix in the email and password sections. 8. From the URL dropdown menu, choose: Bluemix 9. Click: Validate Account 10. Click: Finish

Push the app

1. Right-Click on the Bluemix server and click: Connect 2. Right-Click on the Bluemix server and select: Add and Remove... 3. Select your Twitter Influence Analyzer project from the window on the left and click: Add > 4. Click: Finish 5. Enter a Name and select: Next 6. Enter a UNIQUE hostname and click: Finish

CONGRATS! Your app is now published to Bluemix. (Note: It can take a few minutes to upload everything and deploy all of the services.)

Step 6. Explore your app

1. In your web browser, go to: https://ace.ng.bluemix.net 2. Login and find your new app on the Dashboard. 3. Below the name of your app is a link that takes you to the running app. Click on that link.

The Python Twitter Influencer Analyzer is a web application that collects data from Twitter Klout and Google Maps to display influence relationships between twitter users. Link to the lab source code is available at https://github.com/ibmjstart/bluemix-python-sample-twitter-influence-app This app uses the following cloud services:

o MongoDB

Prerequisites Before we begin, we first need to install the cf command line tool that will be used to upload and manage your application. If you've previously installed an older version of the cf tool, make sure you are now using v6 of cf by passing it the -v flag:

cf -v

Download the App The source for this app is at GitHub so, for example, if you are using the command line you can clone the repository like this:

git clone https://github.com/ibmjstart/bluemix-python-sample-twitter-influence-app.git

External and Public APIs This app uses some external APIs. You need to register the app with Twitter and Klout to get the keys and tokens for the wsgi.py file.

Twitter v1.1 API

To access the Twitter API you need the consumer keys and access tokens, so you must register the app with Twitter. You can register your app here.

More information on how to register the app with Twitter

Klout API

You can register the app with Klout here. When you register with Klout, you'll get a Klout Key, which you can use to create a Klout Object as shown in the code.

Lab C Python Twitter Influencer Analyzer application on BlueMix

Google Maps v3 API

This app uses the Google Maps v3 APIs. Google APIs are open for the developers and you do not need to register the app with Google. Here's the link for the Google Maps APIs.

Screen-shot of the wsgi.py file that shows where the Twitter keys and access tokens and:

Klout developer key is entered:

Deploying the App After including the Twitter/Klout keys and tokens in the wsgi.py file (as shown above), you are ready to deploy the app. In the terminal, go in the directory of the app (where wsgi.py is located). You can deploy/push the app using these commands:

Method: Command-Line

In the terminal, go to the directory of the app, and follow these steps.

1. Login to Bluemix.

usage: $ cf login [-a API_URL] [-o ORG] [-s SPACE]

example: $ cf login -a https://api.ng.bluemix.net

2. Create an instance of the postgreSQL service, giving it a unique name in the last arguement.

usage: $ cf create-service SERVICE PLAN SERVICE_INSTANCE

example: $ cf create-service mongodb 100 mongodb_PTIA

3. From the directory that houses the wsgi.py file, push the app with the --no-start option so we can bind our required service before starting. Pass the -c flag to specify the start command that should be used by CloudFoundry to run your app. Pass the -b flag to specify the Python build pack to be used, https://github.com/joshuamckenty/heroku-buildpack-python is recommended. Be sure to give your app a unique app name to be used as its host; for example, the example below would result in https://nmu.ng.bluemix.net.

usage: $ cf push APP [--no-manifest] [--no-start] [-c COMMAND]

example: $ cf push ptia --no-manfiest --no-start -b https://github.com/joshuamckenty/heroku-buildpack-python -c "python ./wsgi.py"

4. Bind the MongoDB service instance to the new app

usage: $ cf bind-service APP SERVICE_INSTANCE

example: $ cf bind-service ptia mongodb_PTIA

5. Start the app

usage: $ cf start APP

usage: $ cf start APP

example: $ cf start ptia

requirements.txt

If your Python app requires any external dependencies (i.e. any modules that you install using 'pip install'), you need to include them in the requirements.txt file. Each module must be downloaded and put in the directory of the app (e.g. app), and the relative path to that module must be included in the requirements.txt file.

You should not need to do this to deploy this app because the dependencies are already included in the requirements.txt file, and the external modules are also included in the root directory of the app. While deploying the app, the requirements.txt file should be detected and automatically install the dependencies.

This is the home screen of the app. You can enter a twitter screen name in the text box and click the Analyze button to see their influence. You can also view any records saved in the database by clicking on the 'View Database' button.

After entering the twitter name and clicking the Analyze button, you'll be able to see the influence analysis of that person on the left side. You will also see their last 10 tweets and any recent mentions in the tweets plotted on Google Maps (if there is

Screenshots for both the Java and Python applications

geolocation data for a tweet).

These are the records of the Influencers in the database. The user can also delete the records.

Introduction to BlueMixconfigurationPushing the app using EclipseStep 1: Prerequisites Download Source Download Cloud Foundry Plug-in

Step 2. Import the project into EclipseStep 3. Acquiring External and Public APIs Twitter v1.1 API Klout API Google Maps v3 API

Step 4. Configuring the Project FilesStep 5. Deploying the app Set up Bluemix Server Push the app

Step 6. Explore your app

PrerequisitesDownload the AppExternal and Public APIsTwitter v1.1 APIKlout APIGoogle Maps v3 API

Deploying the AppMethod: Command-Linerequirements.txt

Screenshots for both the Java and Python applications