The instructions below document the steps to using the Rumm Usergrid provisioning commands now part of the the Rumm command line tool.

The CL tool works in conjunction with the iOS sample app to demonstrate how easily a Usergrid server can be setup and how a simple iOS can send to and receive data from it.

Using the Rumm Usergrid plug-in

The Rumm Usergrid plugin is designed to quickly and easily spin up a backend server for a mobile app.

The install usergrind on server :id command sets up a node with everything you need to run Apigee's Usergrid service.

Then organization, user, application and objects can be setup through the command-line tool. Apigee also provides SDKs for many popular platforms, including Android and iOS, that talk to the Usergrid service.

##Installation

First we'll create a new Rackspace server instance:

####Note: Usergrid needs a bit more memory than your average rails server, so we'll need to pass a flavor_id to the command

rumm create server --name usergrid-server --flavor_id 3

  --> bootstrapping server usergrid-server
      done.
  created server: usergrid-server
    id: 09cdb2a2-0266-41be-bbb-2b031d258b5b, password: iLbUhhh8F98D

Then we'll setup usergrid on the server:

rumm install usergrid on server usergrid-server

  Setting up a chef kitchen in order to install usergrid on your server.
  This could take a while....

  etc..
  usergrid installed on server usergrid-server: 192.237.240.111

This process will take about 10 minutes.

##Setup

The next step is to initialize the Cassandra database:

rumm initialize db on usergrid server usergrid-server
  Initializing cassandra database...
  {
    "action" : "cassandra setup",
    "status" : "ok",
    "timestamp" : 1384362059196,
    "duration" : 170
  }
  cassandra database initialized on Usergrid server usergrid-server: 192.237.240.111

At this point, you can login to the admin portal, reached at this URL:

http://apigee.github.com/usergrid-portal/?api_url=http://<your IP address>:8080

  http://apigee.github.com/usergrid-portal/?api_url=http://192.237.240.111:8080

You can login with either the default Usergrid credentials (user:admin pw:admin_pass) or the user created by the create organization command below.

Then Usergrid requires us to create an Organization on the server. This is the top of the hierarchical tree. Organizations can have many Applications. This action also creates an admin user for this Organization. None of the fields can accept spaces so all parameters should be written in CamelCase or snake_case.

rumm create organization on usergrid server usergrid-server --org_name my_organization --admin_username myuser --admin_name MyUser --admin_email [email protected] --admin_password admin_pass
  Creating organization on Usergrid server...
  {
    "action" : "new organization",
    "status" : "ok",
    "data" : {
      "owner" : {
        "applicationId" : "00000000-0000-0000-0000-000000000001",
        "username" : "myuser",
        "name" : "MyUser",
        "email" : "[email protected]",
        "activated" : true,
        "confirmed" : true,
        "disabled" : false,
        "properties" : { },
        "uuid" : "50baaf2a-4c85-11e3-bfb6-bdb84c8fb54e",
        "adminUser" : true,
        "displayEmailAddress" : "MyUser <[email protected]>",
        "htmldisplayEmailAddress" : "MyUser &lt;<a href=\"mailto:[email protected]\">[email protected]</a>&gt;"
      },
      "organization" : {
        "name" : "my_organization",
        "properties" : null,
        "uuid" : "50f8546a-4c85-11e3-ba73-9f97e1961322",
        "passwordHistorySize" : 0
      }
    },
    "timestamp" : 1384362121997,
    "duration" : 1150
  }
  Organization: my_organization
  Admin Name: MyUser
  Admin Username: myuser
  Admin Email: [email protected]
  Admin Password: admin_pass
  Something went wrong:  Response code: 200
  organization created on usergrid server usergrid-server: 192.237.240.111

The default values for this command are:

--org_name my_organization
--admin_username my_org_admin
--admin_name MyOrgAdmin
--admin_email [email protected]
--admin_password admin_pass

These values largely don't matter. One strategy might be to only pass a custom password and leave the other fields as their defaults.

Now setup an application on the server. An Organization can have multiple Applications, but in our case we only need one. The Usergrid APIs use the organization and application as parameters to reference the selected application. You will need to re-enter your org_name, admin_username and admin_password here (if you didn't use the default values) and enter an app_name.

rumm create application on usergrid server usergrid-server --app_name my_application --org_name my_organization --admin_username myuser --admin_password admin_pass
  Creating application on Usergrid server...
  D, [2013-11-13T11:03:02.427162 #25213] DEBUG -- : response.body = {
    "action" : "new application for organization",
    "uri" : "http://localhost:8080/null/null",
    "entities" : [ {
      "uuid" : "73b32b10-4c85-11e3-96a3-9f53c8fea97a",
      "type" : "application",
      "name" : "my_organization/my_application",
      "created" : 1384362180681,
      "modified" : 1384362180681,
      "accesstokenttl" : null,
      "applicationName" : "my_application",
      "organizationName" : "my_organization",
      "metadata" : {
        etc..etc..etc..
      }
    } ],
    "data" : {
      "my_organization/my_application" : "73b32b10-4c85-11e3-96a3-9f53c8fea97a"
    },
    "timestamp" : 1384362180666,
    "duration" : 1135
  }
  Organization name: my_organization
  Application name: my_application
  application created on usergrid server usergrid-server: 192.237.240.111

If you refresh the admin portal, you'll see your Organization and Application have been created.

Now we'll move onto the iOS app.

##Setup iOS App

Clone to repository:

git clone [email protected]:hayesmp/usergrid-sample-app.git

In order to talk to your new server, we need to set 3 parameters in AppDelegate.h

NSString* const orgName = @"my_organization"; //YOUR-ORG
NSString* const appName = @"my_application"; //YOUR-APP
NSString* const nodeUrl = @"http://192.237.240.111:8080"; //BASE-URL

And that's it. On the login/register screen, fill in your Name, Email and Password and click register.

####Note: for some reason, this app won't run in the simulator, so you'll have to replace the development provisioning profile with your own.

The way the app works is that it simpy sends your location with your name as the label to your usergrid server and marks the location on your current map view.

If you click the refresh button, the app will download all the locations on the servers created by other users or you during other sessions.

####A note about Usergrid: Even though you haven't actually create this location object on the server, the model is created the first time the data object is sent to the server. Assuming data conformity, all subsequent data can be queried as a group.