http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/installation/ug1-deploy-to-tomcat.html ---------------------------------------------------------------------- diff --git a/content/docs/installation/ug1-deploy-to-tomcat.html b/content/docs/installation/ug1-deploy-to-tomcat.html new file mode 100644 index 0000000..5a13447 --- /dev/null +++ b/content/docs/installation/ug1-deploy-to-tomcat.html @@ -0,0 +1,506 @@ + + + + + + + + + + + Usegrid 1: Deploying to Tomcat — Apache Usergrid 1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+
+ +
+
+
+
+ +
+

Usegrid 1: Deploying to Tomcat

+

This is a guide that explains how to install and run Usergrid using +stock Tomcat and Cassandra on a single computer.

+

NOTE: running Cassandra on a single computer is something you should do +ONLY for testing purposes. You don’t want to run one node in production +even just to start out. To get the benefit of Cassandra’s architecture, +which is designed to support linear scalability. You should be running a +Cassandra cluster with at least three nodes.

+

For more information:

+ +
+

Requirements

+ +
+
+

Download

+

Use GitHub to clone the +apache/incubator-usergrid +repo.

+

Or you can start by downloading our latest +code +and extract it.

+
+
+

Building

+

From the command line, navigate to stack directory and type the +following:

+
mvn clean package -DskipTests=true
+
+
+

Once you are done the Usergrid application will be package as a Java EE +WAR file at the location stack/rest/target/ROOT.war.

+
+
+

Install and configure Cassandra

+

Install Cassandra, don’t edit configuration files as we just want +default values for this simple setup. Here are the instructions for +installing +Cassandra

+
+
+

Install and configure Tomcat

+

Follow instructions, don’t edit configuration files as we just want +default values for this simple setup. Here are the instructions for +installing Tomcat +7

+
+
+

Add Usergrid WAR to Tomcat

+

Remove the existing tomcat/webapps/ROOT directory.

+

Place the Usergrid ROOT.war file into the tomcat/webapps +directory

+
+
+

Add Usergrid configuration file to Tomcat

+

Create a ____usergrid-custom.properties____ file and place it in +Tomcat’s lib directory. You can find an example properties file +below that should work well for a local Tomcat & Cassandra setup. You +will probably only need to change the properties below to use your email +address and preferred password for the install.

+
usergrid.sysadmin.login.allowed=true
+usergrid.sysadmin.login.name=superuser
+usergrid.sysadmin.login.password=pw123
+usergrid.sysadmin.email=me@example.com
+usergrid.sysadmin.login.email=myself@example.com
+usergrid.management.mailer=Myself<myself@example.com>
+usergrid.test-account.admin-user.email=myself@example.com
+usergrid.test-account.admin-user.password=test
+
+
+
+
+

Run Usergrid Database & Super User Setup

+

Start Tomcat and use your web browser to visit the URLs below. While you +do this you might want to watch the logs under tomcat/logs for clues, +just in case anything goes wrong.

+

Database setup URL - http://localhost:8080/system/database/setup

+

When prompted to login use the sysadmin credentials that you specified +in your usergrid-custom.properties file. Based on the example above +that would be superuser and pw123. If the operation is successful you +should a message like the one below in your browser. If not, check your +logs for clues about what went wrong.

+
{
+  "action" : "cassandra setup",
+  "status" : "ok",
+  "timestamp" : 1379424622947,
+  "duration" : 76
+}
+
+
+

Superuser setup URL - http://localhost:8080/system/superuser/setup

+

You should not be prompted for login because you already logged into for +the Database Setup. If setup works, you should see a message like this:

+
{
+  "action" : "superuser setup",
+  "status" : "ok",
+  "timestamp" : 1379424667936,
+  "duration" : 2
+}
+
+
+
+
+

Build the Usergrid Console

+

The Usergrid Console is an admin interface written in JavaScript that +connects to your running Usergrid instance. For evaluation purposes, you +can run it within Tomcat. Build it by following the steps +here. +Once built, copy the directory portal/build/usergrid-portal to +tomcat/webapps.

+
+
+

Login to the Usergrid Console & get started

+

You should now be able to login to the Usergrid console and start +configuring applications, users and more.

+

You can use an static version of the portal to get started:

+

http://localhost:8080/usergrid-portal/(http://localhost:8080/usergrid-portal)

+
+
+

Example usergrid-custom.properties file

+

Here’s a complete example properties file to get you started.

+
# Minimal Usergrid configuration properties for local Tomcat and Cassandra
+#
+# The cassandra configuration options.
+
+# The cassandra host to use
+cassandra.url=localhost:9160
+
+# if your cassandra instance requires username/password
+cassandra.username=someuser
+cassandra.password=somepassword
+
+# The strategy to use when creating the keyspace. This is the default.
+# We recommend creating the keyspace with this default, then editing it
+# via the cassandra CLI to meet the client's needs.
+cassandra.keyspace.strategy=org.apache.cassandra.locator.SimpleStrategy
+
+# The default replication factor for the simple strategy. Again, leave the
+# default, create the app, then use the cassandra cli to set the replication
+# factor options. This can become complicated with different topologies and
+# is more a Cassandra administration issue than a UG issue.
+cassandra.keyspace.strategy.options.replication_factor=1
+
+######################################################
+# Custom mail transport. Not usually used for local testing
+
+#mail.transport.protocol=smtps
+#mail.smtps.host=email-smtp.us-east-1.amazonaws.com
+#mail.smtps.port=465
+#mail.smtps.auth=true
+#mail.smtps.quitwait=false
+#mail.smtps.username=
+#mail.smtps.password=
+
+######################################################
+# Admin and test user setup (change these to be their super user
+
+usergrid.sysadmin.login.name=superuser
+usergrid.sysadmin.login.email=myself@example.com     <--- Change this
+usergrid.sysadmin.login.password=pw123               <--- Change this
+usergrid.sysadmin.login.allowed=true
+usergrid.sysadmin.email=myself@example.com           <--- Change this
+
+# Enable or disable this to require superadmin approval of users
+usergrid.sysadmin.approve.users=false
+
+######################################################
+# Auto-confirm and sign-up notifications settings
+
+usergrid.management.admin_users_require_confirmation=false
+usergrid.management.admin_users_require_activation=false
+usergrid.management.organizations_require_activation=false
+usergrid.management.notify_sysadmin_of_new_organizations=false
+usergrid.management.notify_sysadmin_of_new_admin_users=false
+
+######################################################
+# URLs
+# Redirect path when request come in for TLD
+
+usergrid.redirect_root=https://localhost:8080/status
+usergrid.view.management.organizations.organization.activate=https://localhost:8080/accounts/welcome
+usergrid.view.management.organizations.organization.confirm=https://localhost:8080/accounts/welcome
+usergrid.view.management.users.user.activate=https://localhost:8080/accounts/welcome
+usergrid.view.management.users.user.confirm=https://localhost:8080/accounts/welcome
+usergrid.organization.activation.url=https://localhost:8080/management/organizations/%s/activate
+usergrid.admin.activation.url=https://localhost:8080/management/users/%s/activate
+usergrid.admin.resetpw.url=https://localhost:8080/management/users/%s/resetpw
+usergrid.admin.confirmation.url=https://localhost:8080/management/users/%s/confirm
+usergrid.user.activation.url=https://localhost:8080%s/%s/users/%s/activate
+usergrid.user.confirmation.url=https://localhost:8080/%s/%s/users/%s/confirm
+usergrid.user.resetpw.url=https://localhost:8080/%s/%s/users/%s/resetpw
+
+
+
+
+ + +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/installation/ug1-launcher-quick-start.html ---------------------------------------------------------------------- diff --git a/content/docs/installation/ug1-launcher-quick-start.html b/content/docs/installation/ug1-launcher-quick-start.html new file mode 100644 index 0000000..5ae2501 --- /dev/null +++ b/content/docs/installation/ug1-launcher-quick-start.html @@ -0,0 +1,388 @@ + + + + + + + + + + + Usegrid 1: Launcher Quick-start — Apache Usergrid 1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+
+ +
+
+
+
+ +
+

Usegrid 1: Launcher Quick-start

+
+

Requirements

+ +
+
+

Download

+
+

Download2

+

Start by downloading our latest +code +and extract it.

+
+

Building 3

+

From the command line, navigate to stack directory and type the +following:

+
mvn clean install -DskipTests=true
+
+
+
+
+
+
+

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
+
+
+

After startup, your instance will be available on localhost, port 8080. +To check it’s running properly, you can try loading our status page:

+
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.

+
+
+

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
+
+
+
+
+ + +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/installation/ug2-deploy-to-tomcat.html ---------------------------------------------------------------------- diff --git a/content/docs/installation/ug2-deploy-to-tomcat.html b/content/docs/installation/ug2-deploy-to-tomcat.html new file mode 100644 index 0000000..1557115 --- /dev/null +++ b/content/docs/installation/ug2-deploy-to-tomcat.html @@ -0,0 +1,509 @@ + + + + + + + + + + + Usergrid 2: Deploy to Tomcat — Apache Usergrid 1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+
+ +
+
+
+
+ +
+

Usergrid 2: Deploy to Tomcat

+

NOTE: Beware that Usergrid 2 is UNRELEASED SOFTWARE

+ +
+

Running

+
    +
  1. Start up Cassandra [1]
      +
    1. To do this you can navigate to the cassandra folder and run +./bin/cassandra
    2. +
    +
  2. +
  3. Start up Elasticsearch
      +
    1. To do this you can navigate to the folder where you extracted +elasticsearch and run /bin/elasticsearch
    2. +
    +
  4. +
+
+

Running Usergrid

+
+

Build The Java Sdk

+
    +
  1. Navigate to where you cloned the usergrid repo
  2. +
  3. Navigate to the sdks/java directory
  4. +
  5. Run mvn clean install
  6. +
+
+
+

Build The Stack Itself

+
    +
  1. Navigate to the stack directory.
  2. +
  3. Run mvn clean install -DskipTests
  4. +
  5. This will generate a war at rest/target/ROOT.war
  6. +
+
+
+

Deploying the Stack Locally

+
    +
  1. Take this war and deploy it on downloaded tomcat.
  2. +
  3. In the lib directory of the tomcat you must also put +usergrid-deployment.properties. ( An example file is provided below)
  4. +
  5. Start up Tomcat
      +
    1. To do this you can navigate to folder where Tomcat is install and +run ./bin/catalina.sh start
    2. +
    +
  6. +
  7. Go to a web browser and input the following to initilizing the +database localhost:8080/system/database/setup.
      +
    1. The credentials it asks for are the admin credentialls and +password as defined in the usergrid-deployment.properties.
    2. +
    3. You can also do a curl call with basic auth to automatically +authenticate the call instead of using the web browser.
    4. +
    +
  8. +
  9. Then using the same steps as before call +localhost:8080/system/superuser/setup
  10. +
+

The stack is now ready to be queried against, but to get the most out of +it you’ll need to initilize and use our portal!

+
+
+

Running The Portal Locally

+
+
Requirments
+

nodejs 0.10+

+
    +
  1. Make sure you’ve installed node.js above. Any version above .10 or +.10 should work fine.
  2. +
  3. Navigate to incubator-usergrid/portal.
  4. +
  5. Open config.js and make sure the override URL is pointing to your +local tomcat.
  6. +
  7. Now in the portal folder run the following command ./build.sh dev
  8. +
  9. The portal should automatically open ready for use!
  10. +
+

Now usergrid is fully ready to use! Feel free to query against it or use +it however you like!

+
+
+
+
+
+

Example usergrid-deployment.properties file

+
# core persistence properties
+
+cassandra.embedded=false
+cassandra.version=1.2.18
+cassandra.timeout=2000
+
+collections.keyspace=Usergrid_Applications
+collections.keyspace.strategy.options=replication_factor:1
+collections.keyspace.strategy.class=org.apache.cassandra.locator.SimpleStrategy
+
+collection.stage.transient.timeout=60
+
+hystrix.threadpool.graph_user.coreSize=40
+hystrix.threadpool.graph_async.coreSize=40
+
+elasticsearch.embedded=false
+elasticsearch.cluster_name=elasticsearch
+elasticsearch.index_prefix=usergrid
+elasticsearch.hosts=127.0.0.1
+elasticsearch.port=9300
+
+elasticsearch.force_refresh=true
+
+index.query.limit.default=100
+
+# Max Cassandra connections, applies to both CP and EM
+cassandra.connections=600
+
+######################################################
+# Minimal Usergrid configuration properties for local Tomcat and Cassandra
+#
+
+cassandra.url=127.0.0.1:9160
+
+cassandra.keyspace.strategy=org.apache.cassandra.locator.SimpleStrategy
+cassandra.keyspace.strategy.options.replication_factor=1
+
+######################################################
+# Custom mail transport
+
+mail.transport.protocol=smtps
+mail.smtps.host=smtp.gmail.com
+mail.smtps.port=465
+mail.smtps.auth=true
+mail.smtps.username=
+mail.smtps.password=
+mail.smtps.quitwait=false
+
+
+######################################################
+# Admin and test user setup
+
+usergrid.sysadmin.login.name=superuser
+usergrid.sysadmin.login.email=myself@example.com     <--- Change this
+usergrid.sysadmin.login.password=pwHERE               <--- Change this
+usergrid.sysadmin.login.allowed=true
+usergrid.sysadmin.email=myself@example.com           <--- Change this
+
+usergrid.sysadmin.approve.users=false
+usergrid.sysadmin.approve.organizations=false
+
+# Base mailer account - default for all outgoing messages
+usergrid.management.mailer=User <myself@example.com>    <--- Change this
+
+usergrid.setup-test-account=true
+
+usergrid.test-account.app=test-app
+usergrid.test-account.organization=test-organization
+usergrid.test-account.admin-user.username=test
+usergrid.test-account.admin-user.name=Test User
+usergrid.test-account.admin-user.email=myself@example.com    <---Change this
+usergrid.test-account.admin-user.password=test
+
+######################################################
+# Auto-confirm and sign-up notifications settings
+
+usergrid.management.admin_users_require_confirmation=false
+usergrid.management.admin_users_require_activation=false
+
+usergrid.management.organizations_require_activation=false
+usergrid.management.notify_sysadmin_of_new_organizations=true
+usergrid.management.notify_sysadmin_of_new_admin_users=true
+######################################################
+# URLs
+
+# Redirect path when request come in for TLD
+usergrid.redirect_root=http://localhost:8080/status
+
+usergrid.view.management.organizations.organization.activate=http://localhost:8080/accounts/welcome
+usergrid.view.management.organizations.organization.confirm=http://localhost:8080/accounts/welcome
+usergrid.view.management.users.user.activate=http://localhost:8080/accounts/welcome
+usergrid.view.management.users.user.confirm=http://localhost:8080/accounts/welcome
+
+usergrid.organization.activation.url=http://localhost:8080/management/organizations/%s/activate
+usergrid.admin.activation.url=http://localhost:8080/management/users/%s/activate
+usergrid.admin.resetpw.url=http://localhost:8080/management/users/%s/resetpw
+usergrid.admin.confirmation.url=http://localhost:8080/management/users/%s/confirm
+usergrid.user.activation.url=http://localhost:8080%s/%s/users/%s/activate
+usergrid.user.confirmation.url=http://localhost:8080/%s/%s/users/%s/confirm
+usergrid.user.resetpw.url=http://localhost:8080/%s/%s/users/%s/resetpw
+
+
+ + + + + +
[1]You can start up cassandra and elasticsearch in any order but for the +sake of ordered lists I put Cassandra first.
+
+
+ + +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/2a55601f/content/docs/introduction/async-vs-sync.html ---------------------------------------------------------------------- diff --git a/content/docs/introduction/async-vs-sync.html b/content/docs/introduction/async-vs-sync.html new file mode 100644 index 0000000..caf0163 --- /dev/null +++ b/content/docs/introduction/async-vs-sync.html @@ -0,0 +1,341 @@ + + + + + + + + + + + Async vs. sync calls — Apache Usergrid 1.0 documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + +
+
+
+ +
+
+
+
+ +
+

Async vs. sync calls

+

The Usergrid SDKs work by making RESTful API calls from your application +to the API. In some cases, both synchronous and asynchronous calls are +supported for most methods, as in the case of the Usergrid Android SDK, +while in others only asynchronous calls are supported, as in the +Usergrid JavaScript SDK. The following is a brief explanation of +synchronous vs. asynchronous API calls.

+
+

Synchronous

+

If an API call is synchronous, it means that code execution will block +(or wait) for the API call to return before continuing. This means that +until a response is returned by the API, your application will not +execute any further, which could be perceived by the user as latency or +performance lag in your app. Making an API call synchronously can be +beneficial, however, if there if code in your app that will only execute +properly once the API response is received.

+
+
+

Asynchronous

+

Asynchronous calls do not block (or wait) for the API call to return +from the server. Execution continues on in your program, and when the +call returns from the server, a “callback” function is executed. For +example, in the following code using the Usergrid JavScript SDK, the +function called dogCreateCallback will be called when the create dog API +call returns from the server. Meanwhile, execution will continue:

+
function dogCreateCallback(err, dog) {
+    alert('I will probably be called second');
+    if (err) {
+        //Error - Dog not created
+    } else {
+        //Success - Dog was created
+
+    }
+}
+
+client.createEntity({type:'dogs'}, dogCreateCallback);
+alert('I will probably be called first');
+
+
+

The result of this is that we cannot guarantee the order of the two +alert statements. Most likely, the alert right after the createEntity +function call will be called first since the API call will take a second +or so to complete.

+

The important point is that program execution will continue, and +asynchronously, the callback function will be called once program +execution completes.

+
+
+ + +
+
+ + +
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file