Application development in the public cloud has come a long ways over the past few years. A while back, devs would simply get servers faster. There was still a lot of low-level infrastructure management that was required.

But now? Applications and database fabrics can be deployed globally in minutes.

Introduction to Orchestrate and AppFog

For our part, CenturyLink provides a powerful, multi-modal managed NoSQL database fabric Orchestrate that has a single API for key-value, geospatial, graph and time series data. In addition, CenturyLink's next generation AppFog service helps users create, scale and manage cloud-native applications.

Now, we've combined the power of these two services, to give developers more flexibility for their apps. This tutorial demonstrates how you can use Orchestrate and AppFog together to create an application with geolocation capabilities.

Tutorial Source Code

To access the code shown in this article, use Git and fork or clone the Where U Been? demo application Github repo. This application allows for adding multiple locations that get coordinates from Google's Geocode API, and then offers a search capability for which of those locations are near another location.

The application uses Node.js, so install node and verify that you are using v0.12+ in the local application environment:

$ node -v

We will use the source code in the tutorial to show how Orchestrate and AppFog can be used together for geolocation capabilities. The code should deploy successfully as is - please use it as a launching ground to learn more about Orchestrate's capabilities such as search, time-ordered events, and graph queries.

Provision an Orchestrate Service Instance

To use Orchestrate from an AppFog application, it's easiest to create an instance from the AppFog marketplace. In order to do this, install the Cloud Foundry CLI and able to login to the AppFog environment.

Once you're logged into AppFog from your terminal shell, create an Orchestrate service instance. To do this, use the Cloud Foundry CLI with an AppFog region as your target:

$ cf create-service orchestrate free wub-orchestrate

The name wub-orchestrate matches the name of the service to bind to in the Where U Been manifest.yml file that tells AppFog how to deploy your application. To find out the API key and host environment information, you must first bind the service to an application. To do this, we can push our Where U Been demo application to AppFog. Go to the top-level directory for the cloned repo in a terminal shell and execute the following command:

$ cf push

This will deploy the code on AppFog and provide a URL that can be used to see the application in a web browser.

Because the manifest.yml file in the Where U Been application source code has the wub-orchestrate service instance listed as a dependency, it is automatically bound during deployment.

Setup Local Development Environment

To do local development on the cloned application, pull the API key and host from the running application's environment variables on AppFog. Get these by running the following command:

$ cf env whereubeen
  "orchestrate": [
    "credentials": {
    "label": "orchestrate",
    "name": "wub-orchestrate",
    "plan": "free",

For local development we must setup two environment variables in our current terminal shell. Take the values from the cf env whereubeen output and export the new environment variables locally:

$ export

With a Node.js application you must install the module dependencies from NPM online repositories:

$ npm install

Now you can start up the application using npm that was part of your Node.js installation:

$ npm start

> [email protected] start /Users/csterling/projects/hack/whereubeen
> node index.js

Example app listening at http://:::5000

In a web browser, go to http://localhost:5000 to test if the application is running successfully and connecting to your Orchestrate service instance.

Important Code Samples from Demo Application

In this section we will go over the sample code from the Where U Been application source code to show how to integrate and use the Orchestrate service instance from an AppFog application that it is bound to.

Using Orchestrate Node.js Client

Orchestrate has clients for multiple languages. We are using the Node.js client in the Where U Been demo application. Here is how to install and bind into an application.

$ npm install orchestrate --save

This places the orchestrate module into your package.json configuration file. Now in the JavaScript server source, add the following to bind the module into an application.

var orchestrate = require('orchestrate');

Using Orchestrate Service Credentials from Environment

In order to use the Orchestrate service instance from the local development environment and the AppFog deployed instance, we must setup each from separate environment variable locations. To setup local development environment the Node.js server will pull the ORCHESTRATE_API_KEY and ORCHESTRATE_API_HOST values from environment variables.

NOTE: The following code samples are from file index.js

var orchestrate_api_key = process.env.ORCHESTRATE_API_KEY;
var orchestrate_api_url = process.env.ORCHESTRATE_API_ENDPOINT;

This will ensure that the application can startup for local development and connect to an existing Orchestrate service instance. To pull these values from the AppFog application instance environment, we need to override the local development values to use credentials from VCAP_SERVICES environment variable. The VCAP_SERVICES environment variables value is a JSON string that can be parsed and values pulled from with the following code:

if (process.env.VCAP_SERVICES) {
  var services = JSON.parse(process.env.VCAP_SERVICES);
  var orchestrateConfig = services["orchestrate"];
  if (orchestrateConfig) {
    var node = orchestrateConfig[0];
    orchestrate_api_key = node.credentials.ORCHESTRATE_API_KEY
    orchestrate_api_url = node.credentials.ORCHESTRATE_API_HOST

Now that we are able to run in either local or AppFog runtime environments, the Orchestrate client can be configured with the appropriate API key and host.

var db = orchestrate(orchestrate_api_key, orchestrate_api_url);

Saving Data to Orchestrate

Now that the Orchestrate client is configured we can save data in a Collection. To do this, we will setup Node.js server API endpoints that we can call from the web application in the browser. The Where U Been application uses the Express and Body Parser modules for Node.js to setup these endpoints. To install these modules and save them in the package.json configuration, run these commands:

$ npm install express --save
$ npm install body-parser --save

We can now use them in our Node.js server code:

var express = require('express');
var app = express();
var bodyParser = require('body-parser');

Now that Express and Body Parser are setup, we can implement a function to save location data into our Orchestrate service instance.'/location', function (req, res) {
    // validate taht the required JSON fields are present
    if (! || !req.body.latitude || !req.body.longitude) {
        res.send({'error': 'Must provide name, latitude and longitude in request body.'});

    // POST data record to Orchestrate database instance'location', {
        location: {
            latitude: req.body.latitude,
            longitude: req.body.longitude
    .then(function(result) {
        // on success respond with result
    .fail(function(err) {
        // on failure respond with error
        res.send({'error': err});

Retrieve Data from Orchestrate

To get data using the Orchestrate client there is a similar approach.

app.get('/location', function(req, res) {
    // GET all locations with option to pass in query
    db.list('location', req.query)
    .then(function(result) {
        // on success respond with result
    .fail(function(err) {
        // on failure respond with error
        res.send({'error': err});

Access API from Angular.js Client

From the client application code, in this case using Angular.js, we can setup saving and retrieving locations using the $resource service module.

angular.module('wubServices', ['ngResource'])
.factory('Location', ['$resource', function($resource) {
    return $resource('/location/:id', {}, {
      query: {method: 'GET', isArray: false},
      save:   {method:'POST'}

From an Angular.js controller we can use the Location resource to save and retrieve locations.

$scope.locations = [];

$scope.retrieveLocations = function() {
    Location.query(function(data) {
        $scope.locations = data.body.results;

$scope.saveLocation = function() {{
        name: $scope.locationName,
        latitude: $scope.locationLatitude,
        longitude: $scope.locationLongitude
    function(result) {
        // successfully saved
    function(err) {
        // fail on save

Now these functions can be bound to browser events using Angular.js directives to submit new locations to save and retrieve a list of locations from Orchestrate.

Retrieve Using Geolocation Query with Orchestrate

After we have location data saved into our Orchestrate service instance, we can run a location-based query from our Angular.js client.

$scope.findLocationNear = function(name) {
    // generate Google Geocode URL to find requested location to find other locations near
    var geocodeUrl = "" + encodeURIComponent(name) + "&sensor=false";

    // make Google Geocode URL request
    .success(function(data) {
        // create Orchestrate search query for locations within 100 miles
        var locationData = data.results[0].geometry.location;
        var locationQuery = "value.location:NEAR:{lat:" + + " lon:" + locationData.lng + " radius:100mi}";

        // send request for locations near to requested location
        Location.get({query: locationQuery},
            function(data) {
                // save locations into $scope
                $scope.foundLocations = data.body.results;
    .error(function(data) {
        // on failure respond with error
        console.log('find location error', data);


This tutorial focused on how to use Orchestrate, AppFog, Node.js and Angular.js to create an application with geolocation capabilities. We've just scratched the surface of what Orchestrate and AppFog provide. Please provide feedback at [email protected] and also let us know about the great applications you are developing with Orchestrate and AppFog.