How to Contribute to Apache Usergrid

Dave Johnson Contributor

Who Cares?• Who cares how to contribute to Usergrid?

• At least three possibilities:

• Those who run Usergrid in production

• Those who want to get involved in open source

• ASF officers and directors

Topics

• Getting, building and running the Usergrid code

• Usergrid Internals

• Usergrid Contributor workflow

• Usergrid Roadmap

• Database and more, wrapped by a REST API

• Store and query JSON Entities & Files

• Authentication: Users, Roles & Permissions

• Comprehensive Admin Portal

• SDKs for JavaScript, iOS, Android, Java, Ruby…

First step

Get signed up…

Emailocracy• Seems old-fashioned but…

• Everything happens on the mailing lists

• dev@usergrid.incubator.org

• user@usergrid.incubator.org

• commits@usergrid.incubator.org

• If it did not happen on a list, then it did not happen

https://issues.apache.org/jira/browse/USERGRID/

https://github.com/

https://www.apache.org/licenses/icla.txt

Get the code!$  git  clone  https://github.com/usergrid/usergrid.git  Cloning  into  'usergrid'...  remote:  Reusing  existing  pack:  77027,  done.  remote:  Counting  objects:  43,  done.  remote:  Compressing  objects:  100%  (42/42),  done.  remote:  Total  77070  (delta  20),  reused  0  (delta  0)  Receiving  objects:  100%  (77070/77070),  215.67  MiB  |  259.00  KiB/s,  done.  Resolving  deltas:  100%  (31782/31782),  done.  Checking  connectivity...  done  $  ls  usergrid  LICENSE     NOTICE     README.md       portal/     sdks/    stack/     ugc/

The lay of the land

• The Stack

• The Portal

• The SDKs

• Documentation & Web site

Deployment Architecture

Cassandra

Cassandra

Cassandra

Stack

Tomcat

Stack

Tomcat

Load Balancer

Android SDK

iOS SDK

Portal

JS SDK

UGC

Ruby SDK

PHP SDK

The Usergrid Stack

Stack

Tomcat

Stack Overview• Java web application

• Jersey (JAX-RS) for REST, Jackson for JSON

• Spring for Dependency Injection

• Hector for Cassandra client access

• Composed of Maven modules

Building the Stack• Install Java 7 and Maven 3.0.5

• cd stack

• mvn clean install

• Or for a quicker build:

• mvn -DskipTests=true clean install

• Results are in:

• rest/target/ROOT.war

• launcher/target/usergrid-launcher-0.0.29-SNAPSHOT.jar

Running the Stack

• cd stack/launcher

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

Stack Internals

• Key Maven modules:

• Config

• Core

• Services

• REST

Stack Config Module

Stack Core ModuleEntity

DynamicEntity

ActivityEvent Asset

TypedEntity

DeviceUser Role

UUID Type Properties

Results EntityManager

QueueManager

Query

LockManager

SchedulerService

CounterStore

RelationManager

Hector SpringJacksonCommons Cassandra ANTLRConfig

Stack Services Module

AssetsService

GroupsService

AbstractPathBasedCollectionService

AbstractService

FollowingService

GenericConnectionService

AbstractConnectionService

UsersService

DevicesService

Service

RootCollectionService

RolesService

ActivitiesService

AbstractCollectionServiceService getServiceType() getEntityType() isRootService() invoke( action, request, results, payload ) getEntity( request, UUID uuid ) getEntity( request, String name ) importEntity(request, entity ) writeEntity( request, entity ) updateEntity( request, ref, payload )

ServiceManager

ServiceRequest

ServiceResult

ServiceContext

ServiceAction( POST, GET, PUT, DELETE, HEAD, OPTIONS )

ManagementService

SignInAsProvider TokenService

EncryptionService

RealmExportService

ShiroSpringConfig Core JClouds Amber

Stack REST Module

ManagementResource

EventsResource

AssetsResource

UsersResource

AuthResource

QueueResource

UserResource

ApplicationResource

OrganizationResource

RootResource

ServiceResourcesJAX-RS Resources

ShiroSpringConfig Core JerseyServices Jackson

Testing the stack• cd stack; mvn test

• Each module has tests, implemented via JUnit

• Unit tests *Test and Integration tests are *IT

• Core and Services tests start and stop Cassandra.

• See also: CassandraResource.java

• REST tests start Cassandra and Jetty (via Maven-Jetty plugin)

Other starting points• Install on Tomcat and Cassandra locally

• https://usergrid.incubator.apache.org/docs/deploy-local/!

• Launch N-node cluster via AWS Cloud Formation

• https://github.com/usergrid/usergrid/tree/two-dot-o/stack/awscluster !

• 1-node cluster via Vagrant and Chef

• https://github.com/r3b/usergrid-vagrant !

• 3-node cluster via Vagrant, bash and Groovy

• https://github.com/usergrid/usergrid/tree/vagrant-launcher/stack/launcher-vagrant

Experimental

Portal

JavaScript SDK

The Usergrid Portal

Portal Architecture• Portal is an Angular.js application

• Access to Usergrid via Usergrid JavaScript SDK

• Grunt used as build system

• Can be deployed to any web server (e.g. Apache HTTPD)

• Can be run locally Grunt and Node.js

Building the Portal• Install node.js from http://nodejs.org/download

• sudo npm install grunt-cli -g

• cd portal; ./build.sh

• Build is in dist/appsvc-ui.2.0.0.zip

• Ready for deployment to HTTPD, Tomcat, etc.

https://github.com/usergrid/usergrid/blob/master/portal/README.md

Running the Portal• Sign up for an Apigee App Services account:

• https://accounts.apigee.com/accounts/sign_in!

• Run the Portal via grunt and node.js:

• cd portal; grunt dev

• Navigate to http://localhost:3000

• Login with Apigee App Services credentials

Running against your own stack

• Build and deploy stack (via Launcher or local Tomcat and Cassandra)

• Run the Portal via grunt and node.js:

• cd portal; grunt dev

• Navigate to the Portal, login as superuser/superuser

• http://localhost:3000?api_url=http://localhost:8080

The SDKs• JavaScript / HTML5

• iOS

• Android

• Java

• Ruby

• Ruby On Rails

• PHP

Contributor Workflow• Discuss!

• Discuss your changes on the dev mailing list

• Create a JIRA issue for your changes

• Do the work!

• Fork the Github usergrid/usergrid repo

• Make your changes and add tests

• Push your changes!

• Submit a clean PR against the appropriate branch of usergrid/usergrid

• Update JIRA issue, announce PR on dev mailing list

https://github.com/usergrid/usergrid

Git repos workflow

usergrid / usergrid

!apache / incubator-usergrid

Apache GitYou work in !

your fork

Official Release!on Apache Mirrors

1

2

3

4

5

6

You fork the repo

You submit Pull Request

Auto-merge to official repo

Auto-merge to read-only mirror

All that for a tiny change?• Can’t be bothered?

• You have two options for small changes:

1. Submit Patch via JIRA

• (agreeing to license your change under ASL)

2. Submit Pull Request via GitHub

• (agreeing to license your change under ASL)

Contributing Docs• Web site and documentation in SVN:

http://svn.apache.org/viewvc/incubator/usergrid/site/!!

• Content authored in Markdown

• Build process requires Pandoc, Python & Ruby

• Contributors must submit patches via JIRA

• We need to fix this

http://svn.apache.org/viewvc/incubator/usergrid/site/README.md?view=markup

Roadmap• Get a first Apache release out

• Graduate!

• Usergrid “2.0” with new Persistence Engine

• Other ideas…

• https://issues.apache.org/jira/browse/USERGRID-8

First release• Team working slowly towards first release

• What’s needed?

• License headers everywhere

• Decide on release packaging

• Installation & getting started documentation

• A successful release vote

WIP: two-dot-o branch

• New Core Persistence Library

• New guts for the EntityManager

• Multi-Version Concurrency Control (MVCC)

• Astyanix, RxJava, Hystrix and Guice

• ElasticSearch Index & Query implementation

Questions?