Repository: usergrid Updated Branches: refs/heads/release 48b0c3b49 -> e90154132
Updating an improving getting started docs for 2.1 release. Project: http://git-wip-us.apache.org/repos/asf/usergrid/repo Commit: http://git-wip-us.apache.org/repos/asf/usergrid/commit/e9015413 Tree: http://git-wip-us.apache.org/repos/asf/usergrid/tree/e9015413 Diff: http://git-wip-us.apache.org/repos/asf/usergrid/diff/e9015413 Branch: refs/heads/release Commit: e901541328ec9327289a0feb228c4f7f41bc8b98 Parents: 48b0c3b Author: Dave Johnson <[email protected]> Authored: Tue Feb 9 15:01:23 2016 -0500 Committer: Dave Johnson <[email protected]> Committed: Tue Feb 9 15:01:23 2016 -0500 ---------------------------------------------------------------------- .../creating-a-new-application.md | 16 -- docs/getting-started/creating-account.md | 21 --- docs/getting-started/using-a-sandbox-app.md | 39 ----- docs/getting-started/using-the-api.md | 150 ------------------- docs/index.rst | 20 ++- docs/installation/deployment-guide.md | 132 ++++++++-------- docs/introduction/overview.md | 30 ++-- docs/introduction/usergrid-features.md | 4 +- docs/reference/contribute-code.md | 41 +++-- .../creating-a-new-application.md | 16 ++ docs/using-usergrid/creating-account.md | 21 +++ docs/using-usergrid/using-a-sandbox-app.md | 39 +++++ docs/using-usergrid/using-the-api.md | 150 +++++++++++++++++++ stack/README.md | 32 ++-- 14 files changed, 363 insertions(+), 348 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/getting-started/creating-a-new-application.md ---------------------------------------------------------------------- diff --git a/docs/getting-started/creating-a-new-application.md b/docs/getting-started/creating-a-new-application.md deleted file mode 100644 index ce5fb7a..0000000 --- a/docs/getting-started/creating-a-new-application.md +++ /dev/null @@ -1,16 +0,0 @@ -# Creating a new application - -## Creating an application -You can use the admin portal to create applications. An application represents the data associated with your app. Through an application, you handle the entities associated with your app, including users, devices, events, and so on. - -To create a new application with the admin portal: - -1. In the admin portal, from the dropdown menu at the far top left, select the organization to which you will add the new application. -1. Click the ADD NEW APP button, located at the top of the screen, next to the application drop-down. -1. In the dialog box, enter a new application name, then click the Create button. Your new application will automatically be selected in the applications drop-down menu. - -Applications can also be created programatically with a ``POST`` request to the API. For more, see [Application](../orgs-and-apps/application.html). - -## Securing an application -If this is going to be a production application, be sure to configure security roles that provide only the level of access your users will need. For more on security, see [Security Best Practices](../security-and-auth/securing-your-app.html) -. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/getting-started/creating-account.md ---------------------------------------------------------------------- diff --git a/docs/getting-started/creating-account.md b/docs/getting-started/creating-account.md deleted file mode 100644 index f4f542a..0000000 --- a/docs/getting-started/creating-account.md +++ /dev/null @@ -1,21 +0,0 @@ -# Creating an Usergrid Account -To get started using the Usergrid, you'll need an Usergrid account. (Before reading this, you should already be familiar with what Usergrid can do to support your apps. If you're still curious about that, you might want to read Usergrid features first.) - -With an account, you get the following useful things: - -* A sandbox application you can try things with (we automatically create one for you with your new account). The sandbox is a partitioned area of the data store where you can add example data and try out API calls. The sandbox isn't secure, but it's handy to play in. For more about the sandbox, see [Using Your Application Sandbox](../getting-started/using-a-sandbox-app.html). -* The ability to create more applications (in addition to the sandbox). You can (and should!) make these as secure as you need to. These are the applications that you'll have behind the apps you make available to your users. -* Access to the Admin Portal. In the portal, you can do the following: -** Create and manage applications. -** Manage your app's users, including access levels. -** Manage the data in your app. -** Manage app features, including push notifications, activities, analytics, and so on. -** Try out API calls with a shell command window. -** To create an Usergrid account and see a very short tutorial to get started with, go to the get started page of the Portal. - -## Next steps -Ready to learn and do more? - -* Install an SDK that will be most useful for your application environment. For more about Usergrid's SDKs, see [SDKs](../sdks/tbd.html). -* Review Usergrid features for information on concepts and features. -* Consult the API Reference for usage details. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/getting-started/using-a-sandbox-app.md ---------------------------------------------------------------------- diff --git a/docs/getting-started/using-a-sandbox-app.md b/docs/getting-started/using-a-sandbox-app.md deleted file mode 100644 index 75c296f..0000000 --- a/docs/getting-started/using-a-sandbox-app.md +++ /dev/null @@ -1,39 +0,0 @@ -# Using a Sandbox Application - -## What is the sandbox application? - -When you create a new Usergrid account (see [Creating an Usergrid Account](creating-account.html)) to use services for developers, Usergrid creates a new application for you on its servers. With the new application, called "sandbox," you can add your own example data and try out API calls that do things with the data. Be sure to see Using the API for suggestions. - -## Is the sandbox secure? - -To keep things simple and make it easier for you to try things out, the sandbox application has all authentication disabled. That way, it doesnât require an access token for application-level calls to the API. Permissions are so open on the sandbox application because its "guest" role offers full permissions for all access paths -- that is, GET, POST, PUT, and DELETE for /**. Learn more about roles and permissions in Managing access by defining permission rules. - -<!-- workaround a Sphinx bug --> -<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> -<p class="last">Never use a sandbox app for production. -Keep in mind that the lack of authentication means that a sandbox application is not secure enough for important or sensitive data. A sandbox is just for experimentation while you learn how the services work, and should never be used for a production application. As with other Usergrid applications you create, a sandbox application is an area of the data store where you can put your own data. You can create as many other applications as you like, including more sandbox applications. When it comes to production (secured) applications, a good rule of thumb is to create one application for each mobile app you develop. -</p> -</div> - -## Creating a New Sandbox Application - -You may want to create (or re-create) a sandbox application. For example, you may want to create a sandbox application for another organization or you may want to create another application for testing purposes. - -<!-- workaround a Sphinx bug --> -<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> -Guest Role should never be given full permissions. -Giving the guest role full permissions should be used only for testing and should not be used in production. Before you make your app âliveâ, you should remove the guest permissions for /**. -</p></div> - -Use the following steps to create a sandbox app: - -1. Create a new application using the admin portal. You can name the application whatever you like (including "sandbox"). -2. Set full access permissions for the guest role, as follows: - 1. In the admin portal, click Users, then click Roles. - 2. On the Roles page, in the list of roles, click Guest. - 3. For the Guest role, under Permissions, click Add Permission. - 4. In the New Permission dialog, enter the following in the Path box: ``/**`` - 5. Select the following check boxes: get, post, put, and delete. - 6. Click the Add button. - 7. If there are other permissions listed, delete them. - http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/getting-started/using-the-api.md ---------------------------------------------------------------------- diff --git a/docs/getting-started/using-the-api.md b/docs/getting-started/using-the-api.md deleted file mode 100644 index d85f86a..0000000 --- a/docs/getting-started/using-the-api.md +++ /dev/null @@ -1,150 +0,0 @@ -# Using the API -Usergrid uses a pure REST (Representational State Transfer) API built as a collection of resources. Resource locations are described by paths that are related intrinsically to collections and entities in collections. - -This section gives several examples of how to construct API requests. To focus on what's important, the examples use an abbreviated path that starts after the application UUID, or application name. For example, instead of giving a fully qualified path name as in: - - https://api.usergrid.com/your-org/your-app/users - -the example simply lists this: - - /users - -## Supported HTTP methods -When building a REST API, the challenge is to represent the data and the action upon the data as a path to a resource that can be created, retrieved, updated, or deleted. The HTTP methods POST, GET, PUT, and DELETE correspond to the actions that are applied to resources. - -## Base URL -The base url for all requests made to Usergrid depends on where you have Usergrid installed. If you are using Apigee's trial Usergrid service, the base URL is ``https://api.usergrid.com.`` - -## Request construction -Usergrid interprets the URL resource path as a list of names, UUIDs, or queries. The basic path format is: - - https://api.usergrid.com/<org-uuid|org-name>/<app-uuid|app-name>/<collection-name>/<entity-uuid|entity-name> - -Note: You cannot mix UUIDs and names in the URL resource path. For example, the following is incorrect: - - https://api.usergrid.com/your-org/62de5d97-d28c-11e1-8d5c-12313b01d5c1/users/john.doe - -## Accessing collections -To access all entities in a collection, specify the path as follows: - - /users - -Such a request retrieves the first 10 entities in the collection /users sorted by their entity UUID. - -## Accessing entities -To access an entity in a collection, specify the path as follows: - - /<collection>/<uuid|name> - -where ``<collection>`` is the collection name, and <uuid|name> is the entityâs uuid or name. - -To access a user in the users collection, specify the path as follows: - - /users/<uuid|username|email_address> - -where ``<uuid|username|email_address>`` is the userâs uuid, username, or email address. - -For example, the following request retrieves the entity named dino from the dogs collection: - - /dogs/dino - -## Issuing queries -You can issue a query in an API request that retrieves items from a collection. Here is the typical format for queries: - - /<collection>?ql=<query> - -where <query> is a query in the query language. - -For example, this request retrieves users whose Facebook first name is john: - - /users?ql=select * where facebook.first_name ='john' - -For further information about queries, see [Querying your Data](../data-queries/querying-your-data.html) - -## Authentication (OAuth) -Usergrid implements the OAuth 2.0 standard for authenticating users, clients and API requests. - -Generally, you will generate a token for every user of your app by providing the user's username and password. The token can then be sent with all API requests to ensure each user is only able to access and modify the resources you have granted them rights to. - -Note that by default access tokens are not needed to make requests to the default sandbox application in an organization. - -For more information on generating and using access tokens, see Authenticating users and application clients and Authenticating API requests. - -## Response format -All API methods return a response object that typically contains an array of entities: - - { - "entities" : [ - ... - ] - } - -Not everything can be included inside the entity, and some of the data that gets associated with specific entities isn't part of their persistent representation. This is metadata, and it can be part of the response as well as associated with a specific entity. Metadata is just an arbitrary key/value JSON structure. - -For example: - - { - "entities" : { - { - "name" : "ed", - "metadata" : { - "collections" : ["activities", "groups", "followers"] - } - } - }, - "metadata" : { - "foo" : ["bar", "baz"] - } - } - -For example, here is the response to a basic GET for a user entity: - - { - "action" : "get", - "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", - "params" : { }, - "path" : "/users", - "uri" : "https://api.usergrid.com/your-org/your-app/users";, - "entities" : [ { - "uuid" : "503f17da-ec39-11e3-a0dd-a554b7fbd57a", - "type" : "user", - "created" : 1401921665485, - "modified" : 1401921665485, - "username" : "someUser", - "email" : "[email protected]", - "activated" : true, - "picture" : "http://www.gravatar.com/avatar/dc5d478e9c029853fbd025bed0dc51f8";, - "metadata" : { - "path" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a", - "sets" : { - "rolenames" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", - "permissions" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/permissions" - }, - "collections" : { - "activities" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/activities", - "devices" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/devices", - "feed" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/feed", - "groups" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/groups", - "roles" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", - "following" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/following", - "followers" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/followers" - } - } - } ], - "timestamp" : 1401921673597, - "duration" : 12, - "organization" : "your-org", - "applicationName" : "your-app" - } - -## SDKs -To make the integration of Usergrid features into your application code quicker and easier, Usegrid offers SDKs in a variety of languages. The SDKs contain language-specific methods that allow you to issue API requests from your application code in your preferred language. SDKs are available for the following languages: - -* iOS -* Android -* JavaScript/HTML5 -* Node.js -* Ruby -* .NET - -For more information, see SDKs. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/index.rst ---------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 0003f26..f2bdb63 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,23 +6,23 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Introduction + :caption: Getting Started introduction/overview.md introduction/usergrid-features introduction/data-model introduction/async-vs-sync -.. _getting-started: +.. _using-usergrid: .. toctree:: :maxdepth: 2 - :caption: Getting Started + :caption: Using Usergrid - getting-started/creating-account - getting-started/creating-a-new-application - getting-started/using-a-sandbox-app - getting-started/using-the-api.md + using-usergrid/creating-account + using-usergrid/creating-a-new-application + using-usergrid/using-a-sandbox-app + using-usergrid/using-the-api.md .. _data-storage: @@ -161,11 +161,9 @@ Apache Usergrid Documentation .. toctree:: :maxdepth: 2 - :caption: Installing the Stack + :caption: Installing Usergrid - installation/ug1-deploy-to-tomcat - installation/ug1-launcher-quick-start - installation/ug2-deploy-to-tomcat + installation/deployment-guide .. _about: http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/installation/deployment-guide.md ---------------------------------------------------------------------- diff --git a/docs/installation/deployment-guide.md b/docs/installation/deployment-guide.md index 1a09c20..bdde848 100644 --- a/docs/installation/deployment-guide.md +++ b/docs/installation/deployment-guide.md @@ -1,7 +1,5 @@ # Usergrid 2.1.0 (unreleased) Deployment Guide -## DRAFT - This document explains how to deploy the Usergrid v2.1.0 Backend-as-a-Service (BaaS), which comprises the Usergrid Stack, a Java web application, and the Usergrid Portal, which is an HTML5/JavaScript application. @@ -43,15 +41,7 @@ Optional but helpful: ## Getting Started -Deploying Usergrid starts with downloaded the Apache Usergrid release. There are three ways to go: - -1. Clone the Usergrid Git repo, get the `usergrid-2.1.0` tag (not available yet) and build Usergrid yourself. -2. Download the official Apache Usergrid 2.1.0 source-code release (not available yet) and build Usergrid -3. Download the Apache Usergrid 2.1.0 binary release (not available). - -The easist way to go is option #3 and so that's what we will do in this document. - -__Get started by downloading the Apache Usergrid 2.1.0__ binary release from the Usergrid releases page: +__Download the Apache Usergrid 2.1.0 binary release__ from the official Usergrid releases page: * [Apache Usergrid Releases](https://usergrid.apache.org/releases) @@ -166,58 +156,7 @@ You should review the defaults in the above file. To get you started, let's look #### Example Usergrid Stack Properties File Below is an minimal example Usergrid properties file with the parts you need to change indicated like -shell variables, e.g. `${USERGRID_CLUSTER_NAME}`. Here's a guide to the things you need to set: - -__Table 1: Values to set in Example Properties file:__ - -<table class="usergrid-table"> -<tr> - <th>Value</th> - <th>Description</th> -</tr> -<tr> - <td>__BASEURL__</td> - <td>This is the base URL for the Usergrid installation, e.g. `https://api.example.com`. </td> -</tr> -<tr> - <td>__USERGRID_CLUSTER_NAME__</td> - <td>This is your name for your Usergrid installation. </td> -</tr> -<tr> - <td>__CASSANDRA_CLUSTER_NAME__</td> - <td>Name of Cassandra cluster, must match what's in Cassandra configuration. </td> -</tr> -<tr> - <td>__CASSANDRA_HOSTS__</td> - <td>Comma-separated lists of Cassandra hosts, with port numbers if you are not using the default 9160. The default for this property is `localhost:9160` </td> -</tr> -<tr> - <td>__ELASTICSEARCH_CLUSTER_NAME__</td> - <td>Name of ElasticSearch cluster, must match what's in ElasticSearch configuration. </td> -</tr> -<tr> - <td>__ELASTICSEARCH_HOSTS__</td> - <td>Comma-separated lists of ElasticSearch hosts, with port numbers if you are not using the default 9300. The default for this property is `localhost:9300` </td> -</tr> -<tr> - <td>__SUPER_USER_EMAIL__</td> - <td>Email address of person responsible for the superuser account. </td> -</tr> -<tr> - <td>__SUPER_USER_PASSWORD__</td> - <td>Password for the superuser account. </td> -</tr> -<tr> - <td>__TEST_ADMIN_USER_EMAIL__</td> - <td>If `usergrid.setup-test-account=true`, as shown below, Usergrid will create a test account and you should specify a valid email here. </td> -</tr> -<tr> - <td>__TEST_ADMIN_USER_PASSWORD__</td> - <td>Password for the username 'test' account. </td> -</tr> -</table> - -Make sure you set all of the above properties when you edit this example for your installation. +shell variables, e.g. `${USERGRID_CLUSTER_NAME}`. Example 1: usergrid-deployment.properties file @@ -284,20 +223,74 @@ Example 1: usergrid-deployment.properties file usergrid.user.resetpw.url=${BASEURL}/%s/%s/users/%s/resetpw +Here's a guide to the things you need to set in the above properties file. + +__Table 1: Values to set in Example Properties file:__ + +<table class="usergrid-table"> +<tr> + <th>Value</th> + <th>Description</th> +</tr> +<tr> + <td>__BASEURL__</td> + <td>This is the base URL for the Usergrid installation, e.g. `https://api.example.com`. </td> +</tr> +<tr> + <td>__USERGRID_CLUSTER_NAME__</td> + <td>This is your name for your Usergrid installation. </td> +</tr> +<tr> + <td>__CASSANDRA_CLUSTER_NAME__</td> + <td>Name of Cassandra cluster, must match what's in Cassandra configuration. </td> +</tr> +<tr> + <td>__CASSANDRA_HOSTS__</td> + <td>Comma-separated lists of Cassandra hosts, with port numbers if you are not using the default 9160. The default for this property is `localhost:9160` </td> +</tr> +<tr> + <td>__ELASTICSEARCH_CLUSTER_NAME__</td> + <td>Name of ElasticSearch cluster, must match what's in ElasticSearch configuration. </td> +</tr> +<tr> + <td>__ELASTICSEARCH_HOSTS__</td> + <td>Comma-separated lists of ElasticSearch hosts, with port numbers if you are not using the default 9300. The default for this property is `localhost:9300` </td> +</tr> +<tr> + <td>__SUPER_USER_EMAIL__</td> + <td>Email address of person responsible for the superuser account. </td> +</tr> +<tr> + <td>__SUPER_USER_PASSWORD__</td> + <td>Password for the superuser account. </td> +</tr> +<tr> + <td>__TEST_ADMIN_USER_EMAIL__</td> + <td>If `usergrid.setup-test-account=true`, as shown below, Usergrid will create a test account and you should specify a valid email here. </td> +</tr> +<tr> + <td>__TEST_ADMIN_USER_PASSWORD__</td> + <td>Password for the username 'test' account. </td> +</tr> +</table> + +Make sure you set all of the above properties when you edit this example for your installation. + + #### Configure Logging Usegrid includes the Apache Log4j logging system and you can control the levels of logs for each -Usergrid package and even down to the class level by providing your own __log4j.properties__ file. +Usergrid package and even down to the class level by providing your own `log4j.properties` file. To configure logging you need to: -1. Create a __log4j.properties__ file and place it on the computer where Tomcat is running -2. Add __-D__ system property to Tomcat so that Tomcat can find your Log4j properties file. +1. Create a `log4j.properties` file and place it on the computer where Tomcat is running +2. Add `-D` system property to Tomcat so that Tomcat can find your Log4j properties file. ##### Example Logging Configuration -The Log4j properties file below is a good starting point for Usergrid. It configures ERROR level +The Log4j properties file below is a good starting point for Usergrid. It configures `ERROR` level logging for the 3rd party libraries that Usergrid depends on, and INFO level logging for Usergrid. Plus, it configures some noisy parts of Usergrid to be quiet. @@ -425,7 +418,7 @@ When you issue each of those curl commands, you should see a success message lik } If you don't see a success message, then refer to the Tomcat logs for error message and -seek help from the Usergrid community. +seek help from the [Usergrid community](http://usergrid.apache.org/community). Now that you've gotten Usergrid up and running, you're ready to deploy the Usergrid Portal. @@ -457,7 +450,8 @@ this line: To set the hostname that you will be using for your Usergrid installation. -Start your web server and Portal should be up and running! +Start your web server and Portal should be up and running at http://localhost:8080/portal or wherever you deployed it. + ## Additional Resources http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/introduction/overview.md ---------------------------------------------------------------------- diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md index e9c6968..ec69c41 100644 --- a/docs/introduction/overview.md +++ b/docs/introduction/overview.md @@ -1,17 +1,29 @@ -# Documentation Overview +# Getting Started -The Usergrid documentation is written for a couple of distinctly different audiences: +The Usergrid documentation is written for a couple of distinctly different audiences. -* __Application Developer__: this is you if you are a Javascript, iOS, Android, Java or other developer who wants to build an app that uses the Usergrid APIs for data storage, user management, authentication, etc. __Most of our docs are written for application developers__ so browse the left side-bar and work your way down the topics list. +## For Application Developers -* __Deployment/Operations Engineer__: this is for you if you are the person who will be installing Usergrid, setting up the required Cassandra database and other things that Usergrid needs. Currently, we have limited docs for installation, deployment and maintenance of Usergrid: - * [Deploying to Tomcat](../ug1-deploy-to-tomacat): How to build and deploy Usergrid to Tomcat and Cassandra. - * [Launcher Quick Start](../ug1-launcher-quick-start): How to build and run Usergrid via the Usergrid Launcher. - +Most of the Usergrid docs are written for you. Browse the left side-bar and work your way down the topics list to learn how to get started using Usergrid for data storage, user management, authentication, push notifications and more. + +* A good place to start is [Using Usergrid](../using-usergrid/creating-account.html) + + +## For Deployment and Operations folks + +If you are the person who will be installing Usergrid, setting up the required Cassandra database, ElasticSearch and other things that Usergrid needs, then you should probably start here: + +* [Usergrid Deployment Guide](../installation/deployment-guide.html) + -* __Open Source Contributor__: How to "give back" and contribute to Usergrid. Usergrid welcomes code and documentation contributions, GitHub pull-requests, bug reports and suggestions for improvement. - * [How to Contribute Code & Docs](../reference/contribute-code): +## For Open Source contributoes + +If you want to build Usergrid from source-code then start at our [GitHub repo](http://github.com/apache/usergrid). You will find README files there that explain how to build the Stack, the Portal, SDKs and other components. + +If you want to contribute new code or documentation to the Usergrid project then this is a good place to start: + +* [How to Contribute Code & Docs](../reference/contribute-code.html) http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/introduction/usergrid-features.md ---------------------------------------------------------------------- diff --git a/docs/introduction/usergrid-features.md b/docs/introduction/usergrid-features.md index 1a2f0d6..4d73ec2 100644 --- a/docs/introduction/usergrid-features.md +++ b/docs/introduction/usergrid-features.md @@ -74,8 +74,8 @@ The device entity allows you to capture geolocation data from your users' GPS-en To learn more about geolocation, see [Geolocation](../geolocation/geolocation.html). -## Push notifications (Coming soon...) +## Push notifications -__(Coming Usergrid 2.0)__ Push notifications are the most effective way to engage your users with relevant content, and thanks to Usergrid, implementing them can be done in minutes. Simply register your app and your user's devices with a notification provider, such as Apple Push Notification Service or Google Cloud Messaging, then use the Usergrid notification entity to send millions of push notifications a month at no cost. When used in conjunction with queries of user and application data, push notifications become a powerful tool for leveraging user data, ensuring relevancy and driving engagement. +__(Introduced in Usergrid 2)__ Push notifications are the most effective way to engage your users with relevant content, and thanks to Usergrid, implementing them can be done in minutes. Simply register your app and your user's devices with a notification provider, such as Apple Push Notification Service or Google Cloud Messaging, then use the Usergrid notification entity to send millions of push notifications a month at no cost. When used in conjunction with queries of user and application data, push notifications become a powerful tool for leveraging user data, ensuring relevancy and driving engagement. To learn more about push notifications, see [Push notifications overview](../push-notifications/tbd.html). http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/reference/contribute-code.md ---------------------------------------------------------------------- diff --git a/docs/reference/contribute-code.md b/docs/reference/contribute-code.md index cfd3073..ef8e968 100644 --- a/docs/reference/contribute-code.md +++ b/docs/reference/contribute-code.md @@ -1,18 +1,37 @@ # How to Contribute Code & Docs -Code Contributions +Contribute via GitHub --- -The Usergrid project has adopted a policy for how code is to be contributed -by external contributors, and by those who are committers on the project. -You can read this policy here [Usergrid Contribution Workflow](https://cwiki.apache.org/confluence/display/usergrid/Usergrid+Contribution+Workflow). -Basically, we use GitHub as our code review system. So you should fork the -apache/usergrid repo and submit PRs back to the project. Here -are are step-by-step guide for both both external contributors and committers: +The Usergrid project uses GitHub as our code review system. If you want to contribute to Usergrid, then you should fork the apache/usergrid repo and submit PRs back to the project. +Here are step-by-step guides for both both external contributors and committers: -* [External Contributors Guide](https://cwiki.apache.org/confluence/display/usergrid/Usergrid+External+Contributors+Guide) -* [Usergrid Committers Guide](https://cwiki.apache.org/confluence/display/usergrid/Usergrid+Committers+Guide) +* How to contribute code to Usergrid: [External Contributors Guide](https://cwiki.apache.org/confluence/display/usergrid/Usergrid+External+Contributors+Guide) -Website and Documentation Contributions +* How to accept code contributions to Usergrid: [Usergrid Committers Guide](https://cwiki.apache.org/confluence/display/usergrid/Usergrid+Committers+Guide) + + +Building Usergrid --- -Documentation is in the /docs directory of our Git repo, written in Markdown format and managed by the Sphinx documentation system. See the README.md there for more information. + +Usergrid is made up of multiple components that are built separately: + +* __Stack__: The Usergrid Stack is a Java web application, built using Maven. + * Build instructions are in the [README](https://github.com/apache/usergrid/blob/master/stack/README.md). + +* __Portal__: The Usergrid Portal is an Angular.js application and builds with Grunt. + * Build instructions are in the [README](https://github.com/apache/usergrid/blob/master/portal/README.md). + +* SDKs: See the README files in the `/sdks` sub-directories for SDK build instructions. + + +Building the Website and Documentation +--- + +Usergrid documentation source is located in the `/docs` directory of our Git repo, written in [Markdown](https://daringfireball.net/projects/markdown/) format and managed by the [Sphinx](http://www.sphinx-doc.org) documentation system. For more information: + +* [Apache Usergrid Documentation build instructions](https://github.com/apache/usergrid/blob/master/docs/README.md) + +The Usergrid website source is managed in the `/website` directory. We use the [Nanoc](http://nanoc.ws) static-site generator to generate website content from source. For more information: + +* [Apache User Website build instructions](https://github.com/apache/usergrid/blob/master/website/README.md) http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/using-usergrid/creating-a-new-application.md ---------------------------------------------------------------------- diff --git a/docs/using-usergrid/creating-a-new-application.md b/docs/using-usergrid/creating-a-new-application.md new file mode 100644 index 0000000..ce5fb7a --- /dev/null +++ b/docs/using-usergrid/creating-a-new-application.md @@ -0,0 +1,16 @@ +# Creating a new application + +## Creating an application +You can use the admin portal to create applications. An application represents the data associated with your app. Through an application, you handle the entities associated with your app, including users, devices, events, and so on. + +To create a new application with the admin portal: + +1. In the admin portal, from the dropdown menu at the far top left, select the organization to which you will add the new application. +1. Click the ADD NEW APP button, located at the top of the screen, next to the application drop-down. +1. In the dialog box, enter a new application name, then click the Create button. Your new application will automatically be selected in the applications drop-down menu. + +Applications can also be created programatically with a ``POST`` request to the API. For more, see [Application](../orgs-and-apps/application.html). + +## Securing an application +If this is going to be a production application, be sure to configure security roles that provide only the level of access your users will need. For more on security, see [Security Best Practices](../security-and-auth/securing-your-app.html) +. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/using-usergrid/creating-account.md ---------------------------------------------------------------------- diff --git a/docs/using-usergrid/creating-account.md b/docs/using-usergrid/creating-account.md new file mode 100644 index 0000000..90fe0e1 --- /dev/null +++ b/docs/using-usergrid/creating-account.md @@ -0,0 +1,21 @@ +# Creating a Usergrid Account +To get started using the Usergrid, you'll need an Usergrid account. (Before reading this, you should already be familiar with what Usergrid can do to support your apps. If you're still curious about that, you might want to read Usergrid features first.) + +With an account, you get the following useful things: + +* A sandbox application you can try things with (we automatically create one for you with your new account). The sandbox is a partitioned area of the data store where you can add example data and try out API calls. The sandbox isn't secure, but it's handy to play in. For more about the sandbox, see [Using Your Application Sandbox](../getting-started/using-a-sandbox-app.html). +* The ability to create more applications (in addition to the sandbox). You can (and should!) make these as secure as you need to. These are the applications that you'll have behind the apps you make available to your users. +* Access to the Admin Portal. In the portal, you can do the following: + * Create and manage applications. + * Manage your app's users, including access levels. + * Manage the data in your app. + * Manage app features, including push notifications, activities, analytics, and so on. + * Try out API calls with a shell command window. + * To create an Usergrid account and see a very short tutorial to get started with, go to the get started page of the Portal. + +## Next steps +Ready to learn and do more? + +* Install an SDK that will be most useful for your application environment. For more about Usergrid's SDKs, see [SDKs](../sdks/tbd.html). +* Review Usergrid features for information on concepts and features. +* Consult the API Reference for usage details. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/using-usergrid/using-a-sandbox-app.md ---------------------------------------------------------------------- diff --git a/docs/using-usergrid/using-a-sandbox-app.md b/docs/using-usergrid/using-a-sandbox-app.md new file mode 100644 index 0000000..75c296f --- /dev/null +++ b/docs/using-usergrid/using-a-sandbox-app.md @@ -0,0 +1,39 @@ +# Using a Sandbox Application + +## What is the sandbox application? + +When you create a new Usergrid account (see [Creating an Usergrid Account](creating-account.html)) to use services for developers, Usergrid creates a new application for you on its servers. With the new application, called "sandbox," you can add your own example data and try out API calls that do things with the data. Be sure to see Using the API for suggestions. + +## Is the sandbox secure? + +To keep things simple and make it easier for you to try things out, the sandbox application has all authentication disabled. That way, it doesnât require an access token for application-level calls to the API. Permissions are so open on the sandbox application because its "guest" role offers full permissions for all access paths -- that is, GET, POST, PUT, and DELETE for /**. Learn more about roles and permissions in Managing access by defining permission rules. + +<!-- workaround a Sphinx bug --> +<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> +<p class="last">Never use a sandbox app for production. +Keep in mind that the lack of authentication means that a sandbox application is not secure enough for important or sensitive data. A sandbox is just for experimentation while you learn how the services work, and should never be used for a production application. As with other Usergrid applications you create, a sandbox application is an area of the data store where you can put your own data. You can create as many other applications as you like, including more sandbox applications. When it comes to production (secured) applications, a good rule of thumb is to create one application for each mobile app you develop. +</p> +</div> + +## Creating a New Sandbox Application + +You may want to create (or re-create) a sandbox application. For example, you may want to create a sandbox application for another organization or you may want to create another application for testing purposes. + +<!-- workaround a Sphinx bug --> +<div class="admonition warning"><p class="first admonition-title">Warning</p><p class="last"> +Guest Role should never be given full permissions. +Giving the guest role full permissions should be used only for testing and should not be used in production. Before you make your app âliveâ, you should remove the guest permissions for /**. +</p></div> + +Use the following steps to create a sandbox app: + +1. Create a new application using the admin portal. You can name the application whatever you like (including "sandbox"). +2. Set full access permissions for the guest role, as follows: + 1. In the admin portal, click Users, then click Roles. + 2. On the Roles page, in the list of roles, click Guest. + 3. For the Guest role, under Permissions, click Add Permission. + 4. In the New Permission dialog, enter the following in the Path box: ``/**`` + 5. Select the following check boxes: get, post, put, and delete. + 6. Click the Add button. + 7. If there are other permissions listed, delete them. + http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/docs/using-usergrid/using-the-api.md ---------------------------------------------------------------------- diff --git a/docs/using-usergrid/using-the-api.md b/docs/using-usergrid/using-the-api.md new file mode 100644 index 0000000..d85f86a --- /dev/null +++ b/docs/using-usergrid/using-the-api.md @@ -0,0 +1,150 @@ +# Using the API +Usergrid uses a pure REST (Representational State Transfer) API built as a collection of resources. Resource locations are described by paths that are related intrinsically to collections and entities in collections. + +This section gives several examples of how to construct API requests. To focus on what's important, the examples use an abbreviated path that starts after the application UUID, or application name. For example, instead of giving a fully qualified path name as in: + + https://api.usergrid.com/your-org/your-app/users + +the example simply lists this: + + /users + +## Supported HTTP methods +When building a REST API, the challenge is to represent the data and the action upon the data as a path to a resource that can be created, retrieved, updated, or deleted. The HTTP methods POST, GET, PUT, and DELETE correspond to the actions that are applied to resources. + +## Base URL +The base url for all requests made to Usergrid depends on where you have Usergrid installed. If you are using Apigee's trial Usergrid service, the base URL is ``https://api.usergrid.com.`` + +## Request construction +Usergrid interprets the URL resource path as a list of names, UUIDs, or queries. The basic path format is: + + https://api.usergrid.com/<org-uuid|org-name>/<app-uuid|app-name>/<collection-name>/<entity-uuid|entity-name> + +Note: You cannot mix UUIDs and names in the URL resource path. For example, the following is incorrect: + + https://api.usergrid.com/your-org/62de5d97-d28c-11e1-8d5c-12313b01d5c1/users/john.doe + +## Accessing collections +To access all entities in a collection, specify the path as follows: + + /users + +Such a request retrieves the first 10 entities in the collection /users sorted by their entity UUID. + +## Accessing entities +To access an entity in a collection, specify the path as follows: + + /<collection>/<uuid|name> + +where ``<collection>`` is the collection name, and <uuid|name> is the entityâs uuid or name. + +To access a user in the users collection, specify the path as follows: + + /users/<uuid|username|email_address> + +where ``<uuid|username|email_address>`` is the userâs uuid, username, or email address. + +For example, the following request retrieves the entity named dino from the dogs collection: + + /dogs/dino + +## Issuing queries +You can issue a query in an API request that retrieves items from a collection. Here is the typical format for queries: + + /<collection>?ql=<query> + +where <query> is a query in the query language. + +For example, this request retrieves users whose Facebook first name is john: + + /users?ql=select * where facebook.first_name ='john' + +For further information about queries, see [Querying your Data](../data-queries/querying-your-data.html) + +## Authentication (OAuth) +Usergrid implements the OAuth 2.0 standard for authenticating users, clients and API requests. + +Generally, you will generate a token for every user of your app by providing the user's username and password. The token can then be sent with all API requests to ensure each user is only able to access and modify the resources you have granted them rights to. + +Note that by default access tokens are not needed to make requests to the default sandbox application in an organization. + +For more information on generating and using access tokens, see Authenticating users and application clients and Authenticating API requests. + +## Response format +All API methods return a response object that typically contains an array of entities: + + { + "entities" : [ + ... + ] + } + +Not everything can be included inside the entity, and some of the data that gets associated with specific entities isn't part of their persistent representation. This is metadata, and it can be part of the response as well as associated with a specific entity. Metadata is just an arbitrary key/value JSON structure. + +For example: + + { + "entities" : { + { + "name" : "ed", + "metadata" : { + "collections" : ["activities", "groups", "followers"] + } + } + }, + "metadata" : { + "foo" : ["bar", "baz"] + } + } + +For example, here is the response to a basic GET for a user entity: + + { + "action" : "get", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/users", + "uri" : "https://api.usergrid.com/your-org/your-app/users";, + "entities" : [ { + "uuid" : "503f17da-ec39-11e3-a0dd-a554b7fbd57a", + "type" : "user", + "created" : 1401921665485, + "modified" : 1401921665485, + "username" : "someUser", + "email" : "[email protected]", + "activated" : true, + "picture" : "http://www.gravatar.com/avatar/dc5d478e9c029853fbd025bed0dc51f8";, + "metadata" : { + "path" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a", + "sets" : { + "rolenames" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", + "permissions" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/permissions" + }, + "collections" : { + "activities" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/activities", + "devices" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/devices", + "feed" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/feed", + "groups" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/groups", + "roles" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles", + "following" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/following", + "followers" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/followers" + } + } + } ], + "timestamp" : 1401921673597, + "duration" : 12, + "organization" : "your-org", + "applicationName" : "your-app" + } + +## SDKs +To make the integration of Usergrid features into your application code quicker and easier, Usegrid offers SDKs in a variety of languages. The SDKs contain language-specific methods that allow you to issue API requests from your application code in your preferred language. SDKs are available for the following languages: + +* iOS +* Android +* JavaScript/HTML5 +* Node.js +* Ruby +* .NET + +For more information, see SDKs. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/usergrid/blob/e9015413/stack/README.md ---------------------------------------------------------------------- diff --git a/stack/README.md b/stack/README.md index d2c8123..407b9e5 100644 --- a/stack/README.md +++ b/stack/README.md @@ -1,13 +1,18 @@ -# Usergrid +# Apache Usergrid + A highly-scalable data platform for mobile applications. * **Documentation**: http://usergrid.apache.org/docs/ * **Homepage**: http://http://usergrid.apache.org/ + ## Requirements -* JDK 1.6 (http://www.oracle.com/technetwork/java/javase/downloads/index.html) +* 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.4+ + ## Building @@ -17,30 +22,16 @@ From the command line, go to the usergrid directory and type the following: ## Running -Usergrid-core contains the persistence layer and shared utilities for powering the Usergrid service. The services layer is contained in usergrid-services and exposes a higher-level API that's used by the usergrid-rest web services tier. - -You can run Usergrid from the command-line from the -jar in the usergrid/standalone project: - - cd launcher; java -jar target/usergrid-launcher-*.jar +The build process will package the Usergrid Stack into one file `stack/rest/target/ROOT.war` -After startup, your instance will be available on localhost, port 8080. -To check itâs running properly, you can try loading our status page: +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). - curl http://localhost:8080/status - -You can also run it as a webapp in Tomcat, by deploying the ROOT.war file generated in the usergrid/rest project. ## Upgrading from Previous Versions -If you built and used a previous version of Usergrid, that may be using a different schema, we have an easy built-in tool to audit your Cassandra column family structure and upgrade the dataset as necessary. Once you have pulled, built and launched the new version of Usergrid, just hit [http://localhost:8080/system/database/setup](http://localhost:8080/system/database/setup) to run the upgrade tool. - -## Getting Started with the Admin Portal +There is currently no upgrade path for a Usergrid 1 database to Usergrid 2.x. -By default, the [Usergrid admin portal](https://github.com/apigee/usergrid-portal) points to production servers at `api.usergrid.com`. However, by specifying an api_url argument in the query string, you can have it point to your local instance instead. For example, you could reuse the version of the admin portal we host on github and have that point to your local cluster by opening the following URL in your browser: -[http://apigee.github.com/usergrid-portal/?api_url=http://localhost:8080](http://apigee.github.com/usergrid-portal/?api_url=http://localhost:8080) - -The same trick would work if you used a local copy of the portal code served from your own machine or servers. ## Getting Started with the HTTP API @@ -84,6 +75,7 @@ Letâs use it to create a collection with some data in it: We welcome all contributions, including via pull requests on GitHub! If you want to submit code, please read more about our [contribution workflow](https://cwiki.apache.org/confluence/display/usergrid/GitHub+Based+Contribution+Workflow) + ## Licenses Usergrid is licensed under the Apache License, Version 2.
