stack/README.md

# Apache Usergrid

A highly-scalable data platform for mobile applications.

* **Documentation**: http://usergrid.apache.org/docs/
* **Homepage**: http://usergrid.apache.org/


## Requirements

* JDK 1.8 (http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* 3.0.0 <= Maven (http://maven.apache.org/)
* Cassandra 1.2.1+
* ElasticSearch 1.4.x - 1.7.x


## Building

First, build the [Java SDK](https://github.com/apache/usergrid-java) as the stack uses this as a dependency for some modules:

    mvn clean install -DskipTests=true

From the command line, go to the usergrid `stack/` directory and type the following:

    mvn clean install -DskipTests=true

If you want to run tests you will need to have Cassandra and ElasticSearch running on your computer and on the default ports. The following command will do the build and run all JUnit tests:

    mvn clean install


## Running

The build process will package the Usergrid Stack into one file `stack/rest/target/ROOT.war`

To run Usergrid Stack you will need to deploy it to Tomcat. You can find instructions for
doing that in the [Usergrid Deployment Guide](http://usergrid.apache.org/docs/installation/deployment-guide.html).


## Upgrading from Previous Versions

There is currently no upgrade path for a Usergrid 1 database to Usergrid 2.x.


## Getting Started with the HTTP API

Start by creating an Organization. It’s the top-level structure in Usergrid:
all Apps and Administrators must belong to an Organization. Here’s how you create one:

    curl -X POST  \
         -d 'organization=myfirstorg&username=myadmin&name=Admin&email=admin@example.com&password=password' \
         http://localhost:8080/management/organizations

You can see that creating an Organization creates an Administrator in the process. Let’s authenticate as him:

    curl 'http://localhost:8080/management/token?grant_type=password&username=myadmin&password=password'

This will return an access\_token. We’ll use this to authenticate the next two calls.
Next, let’s create an Application:

    curl -H "Authorization: Bearer [the management token from above]" \
         -H "Content-Type: application/json" \
         -X POST -d '{ "name":"myapp" }' \
         http://localhost:8080/management/orgs/myfirstorg/apps

… And a User for the Application:

    curl -H "Authorization: Bearer [the management token from above]" \
         -X POST "http://localhost:8080/myfirstorg/myapp/users" \
         -d '{ "username":"myuser", "password":"mypassword", "email":"user@example.com" }'

Let’s now generate an access token for this Application User:

    curl 'http://localhost:8080/myfirstorg/myapp/token?grant_type=password&username=myuser&password=mypassword'

This will also send back an access\_token, but limited in scope.
Let’s use it to create a collection with some data in it:

    curl -H "Authorization: Bearer [the user token]" \
         -X POST -d '[ { "cat":"fluffy" }, { "fish": { "gold":2, "oscar":1 } } ]' \
         http://localhost:8080/myfirstorg/myapp/pets

## Contributing

We welcome all contributions, including via pull requests on GitHub! For more information see [How to Contribute Code & Docs](http://usergrid.apache.org/docs/reference/contribute-code.html).


## Licenses

Usergrid is licensed under the Apache License, Version 2.