Apache Usergrid is a multi-tenant Backend-as-a-Service stack for web & mobile applications, based on RESTful APIs. It is currently incubating at the Apache Software Foundation.

This repository contains all the code for Apache Usergrid, including the server stack, portal, client and SDKs. Each of them have their own, much more detailed README in the corresponding subdirectories.

• 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/README.md for instructions.
• 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 admin portal and the many SDKs. A pure HTML5+JavaScript app allowing you to register developers and let them manage their apps in a multi-tenant cluster. Located under /portal
• SDKs for iOS, Android, HTML5/JavaScript, node.js, Ruby on Rails, pure Ruby, PHP, (server-side) Java and .Net / Windows, located in their respective subdirectories under /sdks.

It's easy to build and run Usergrid locally. All you need is the Java JDK 1.7 and Maven 3.0.5 installed and on your path. Here's how you do it. First you get the source code like this:

git clone [email protected]:usergrid/usergrid.git

Next, you change directories into the Java SDK package and build the SDK:

cd usergrid/sdks/java
mvn clean install

Next, you change directory into the stack directory and build the Usergrid WAR and launcher:

cd ../..
cd stack
mvn clean install

Finally, you can run Usergrid locally by using the all-in-one launcher, which includes a web server (Grizzly) and the database (Cassandra):

cd launcher
java -jar target/usergrid-launcher-0.0.29-SNAPSHOT.jar

(you might have to substitute 0.0.29-SNAPSHOT with something newer)

You should see the Usergrid launcher UI and from there you can start Usergrid and access the admin console.

If not, subscribe to the user mailing list and we can help you out.

If you previously developed with Apache Usergrid, you know our code used to be structured into separate repositories: usergrid-stack, usergrid-portal, etc. We are now using a merged repository.

You just need to clone this repository, and use git subtree (usually requires git 1.8+) to merge your changes under the new structure. Here’s an example for a portal fork. Adjust the prefix, repository address and branch you want to pull from as necessary.

git clone [email protected]:usergrid/usergrid.git
cd usergrid
git subtree pull --prefix=portal [email protected]:my-github-account/my-usergrid-portal-fork.git master

This will pull (i.e. merge) the changes you made from the master branch of github.com/my-github-account/my-usergrid-portal-fork into the portal/ subfolder. It should ask you to provide a commit message for the merge. There’s lot of flexibility on how to fetch and merge, please see the git subtree manual for details. Then please do consider sending us a pull request with these changes ;)

You should really update your old repositories to the new structure with the instructions above, but the following may work for you, although we make no guarantee they will work in the future.

You can produce a branch compatible with the old repos by using git subtree (usually requires git 1.8+). Then from this repository you can

git clone [email protected]:usergrid/usergrid.git
cd usergrid
git checkout master
git subtree split --prefix=portal -b portal
git checkout portal

This will create a “portal” branch that is compatible with the old usergrid-portal repository, from the code under the portal/ directory. You can pull from that branch (or push changes to it, although we will not accept pull requests sent thusly).

The git subtree split above should function for portal, ugc, and any of the SDKs, but will not work for the stack, due to some anonymous comments left in the tree that prevent a split, and cannot be corrected lest we break the history and force a rebase on all forks.

Please update your code setup as soon as possible and ask the dev list if you have any questions!