Build from source

Build Usergrid from source

Assuming you have already done:

  1. initial Ubuntu Trusty server setup
  2. Cassandra cluster installation on Ubuntu Trusty
  3. Tomcat installation on Ubuntu Trusty

Building the app (/stack)

So, Usergrid’s repository is here:

As you can see, the code is divided into 4 major components:

  1. The server-side stack, a Java 7 + Cassandra codebase that powers all of the features, is located under /stack. You can install dependencies and compile it with maven. See stack/ for instructions.
  2. The admin portal is a pure HTML5+JavaScript app allowing you to register developers and let them manage their apps in a multi-tenant cluster. Located under /portal
  3. SDKs for iOSAndroidHTML5/JavaScriptnode.jsRuby on Railspure RubyPHP, (server-side) Java.Net / Windows, and Perl, located in their respective subdirectories under /sdks.
  4. a command-line client “ugc” allowing you to complete most maintenance tasks, as well as queries in a manner similar to the mysql or the mongo shell, located under /ugc. You can install it on your machine with a simple sudo gem install ugc

The “stack” part is the most important one.

We will build it using Maven.

mkdir ~/usergrid/ && cd ~/usergrid/

To unzip the code:

sudo apt-get install unzip -y

Then, navigate to the stack folder:

cd ~/usergrid/incubator-usergrid-master/stack/


The configure files for production installs are in ~/usergrid/incubator-usergrid-master/stack/config/src/main/resources/, which I’m told is a standard Maven setup.

I’m loosely following the “Example file” from (of course, changing settings according to my setup, see below), as I couldn’t get how the config READ ME at ~/usergrid/incubator-usergrid-master/stack/config/README.txt worked.

I was able to run everything successfully, by editing ~/usergrid/incubator-usergrid-master/stack/config/src/main/resources/ (NOT, and changing/adding the stuff below.

As a note, my Cassandra installation is a cluster distributed across different machines, I’m using one of the seeds’ public ip address (<CLUSTER_IP>). The IP where I have Tomcat installed is <TOMCAT_IP>.

Here is what I changed:


I added this right after cassandra.url=localhost:9160:


Then, I replaced all occurrences of localhost and replaced them with <TOMCAT_IP>

Placing the config file in Tomcat’s lib folder or renaming it caused it to not get picked up. For sure I’m doing something wrong at how I configure this, but it’s the only way I could get it to work for me.

If someone could shed some light in the comments I’d love to do it the right way. :-)


Building with Maven is pretty straightforward. It takes a little while, and then a WAR file called ROOT.war file is placed in ~/usergrid/incubator-usergrid-master/stack/rest/target/

Install Maven:

sudo apt-get install maven -y


cd ~/usergrid/incubator-usergrid-master/stack/
sudo mvn clean install -DskipTests=true -debug

Add WAR to Tomcat

Stop Tomcat:

sudo /etc/init.d/tomcat7 stop

Then, move the app to Tomcat (this will destroy whatever is in Tomcat, if anything):

sudo rm -rfv /var/lib/tomcat7/webapps/ROOT/
sudo mv -v ~/usergrid/incubator-usergrid-master/stack/rest/target/ROOT.war /var/lib/tomcat7/webapps/

Restart Tomcat:

sudo /etc/init.d/tomcat7 start

Run Usergrid Database & Super User Setup

Usergrid is installed, and just needs to be set up.

At this point, I’m going back to following the instructions on

Perhaps obviously, I’m using <TOMCAT_ID> instead of localhost in the examples:

Everything worked smoothly here. You can visit and make sure that everything looks OK. In particular, look for "cassandraAvailable" : true

Usergrid admin portal (/portal)

This component is simple HTML+JS, and offers a GUI to easily manage a few aspects of the system:

Use the admin portal for administrative operations, including:

  • Create new organizations and applications.
  • View information about the current organization, such as its applications, administrators, and credentials.
  • Display information about an application, such as its users, groups, collections, and roles.
  • Create and modify roles to manage access to your data.
  • View and modify your data, with full support for users, groups, and custom entities and collections.
  • Generate and access credentials for API access.

You can find more info here: The instructions seem a lot better compared to /stack.

I wasn’t interested in this component (I just needed to call the API directly), so I haven’t looked into it just yet.

One thought on “Build from source

  1. hi, i am using windows and i have followed all the steps given in the readme file. i am trying to build and deploy usergrid on my machine. After building the /portal/ file a file gets created /dist/user-portal.tar and i am copy pasting the file in my apache tomcart/webapps folder as mention in the readme file. but i am still unable to open the login portal.
    can u please help me out.

Leave a Reply

Your email address will not be published. Required fields are marked *