You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2016/02/05 00:00:47 UTC
[09/42] usergrid git commit: On-going development of new deployment
guide.
On-going development of new deployment guide.
Project: http://git-wip-us.apache.org/repos/asf/usergrid/repo
Commit: http://git-wip-us.apache.org/repos/asf/usergrid/commit/83dd2ff9
Tree: http://git-wip-us.apache.org/repos/asf/usergrid/tree/83dd2ff9
Diff: http://git-wip-us.apache.org/repos/asf/usergrid/diff/83dd2ff9
Branch: refs/heads/master
Commit: 83dd2ff96dc954e85d0e1ab61558dce2e872fa5e
Parents: 9eaff0d
Author: Dave Johnson <sn...@apache.org>
Authored: Fri Jan 29 17:32:29 2016 -0500
Committer: Dave Johnson <sn...@apache.org>
Committed: Fri Jan 29 17:32:29 2016 -0500
----------------------------------------------------------------------
docs/installation/deployment-guide.md | 291 +++++++++++++++++++++++------
1 file changed, 236 insertions(+), 55 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/usergrid/blob/83dd2ff9/docs/installation/deployment-guide.md
----------------------------------------------------------------------
diff --git a/docs/installation/deployment-guide.md b/docs/installation/deployment-guide.md
index bb3d05c..9f7919b 100644
--- a/docs/installation/deployment-guide.md
+++ b/docs/installation/deployment-guide.md
@@ -1,13 +1,68 @@
# Usergrid 2.1.0 Deployment Guide
-
-__NOTE__: DRAFT VERSION
-
-This document covers these two topics:
-
- * Deploying the Usergrid Stack
- * Deploying the Usergrid Portal
-
+David M. Johnson, January 2016
+
+## DRAFT
+
+This document explains how to deploy the Usergrid Backend-as-a-Service (BaaS),
+which comprises the Usergrid Stack, a Java web application, and the Usergrid Portal,
+which is an HTML5/JavaScript application.
+
+* Getting Started
+
+* Deploying the Usergrid Stack
+ * Setup Cassandra
+ * Setup ElasticSearch
+ * Setup Tomcat and deploy Usergrid
+ * Configure Usergrid Stack
+ * Configure Logging
+ * Deploy ROOT.war to Tomcat
+ * Initialize Database
+
+* Deploying the Usergrid Portal
+
+
+## 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: download the Apache Usergrid 2.1.0 binary release from
+the Usergrid releases page here:
+
+* [Apache Usergrid Releases](https://usergrid.apache.org/releases)
+
+When you un-tar the Usergrid binary release, you will see a directory layout like this:
+
+ +-- apache-usergrid-2.1.0
+ |
+ +-- LICENSE
+ |
+ +-- NOTICE
+ |
+ +-- CHANGELOG
+ |
+ +-- stack
+ | |
+ | + ROOT.war
+ |
+ +-- portal
+ | |
+ | +-- dist
+ | |
+ | + usergrid-portal.tar
+ |
+ +-- sdks
+ | |
+ | +-- html5-javascript (JavaScript SDK and source)
+ | |
+ | +-- java (Java SDK and source)
+
+The files that you need for deploying Usergrid Stack and Portal are `ROOT.war` and `usergrid-portal.tar`.
+
## Deploying the Usergrid Stack
@@ -17,71 +72,80 @@ Below are the software requirements for the Stack. You can install them all on
one computer for development purposes, and for deployment you can deploy them
separately using clustering.
+ * Linux or a UNIX-like system (Usergrid may run on Windows, but we haven't tried it)
* [Java SE 8 JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* [Apache Tomcat 7+](https://tomcat.apache.org/download-70.cgi)
* [Apache Cassandra 1.2.1+](http://cassandra.apache.org/download/)
* [ElasticSearch 1.4+](https://www.elastic.co/downloads/elasticsearch)
+
+And highly recommended:
+
+ * An HTTP or REST client, such as [curl](http://curl.haxx.se), is helpful when working with Usergrid
+
+Before installing the Usegrid Stack into Tomcat, you'll start by setting up the
+required database and search engine nodes.
-Before installing the Usegrid Stack into Tomcat, start by setting up your databases.
-### Setup Cassandra
+### Stack STEP #1: Setup Cassandra
-Usergrid needs access to at least one Cassandra node. You can setup a single node of
+Usergrid needs access to at least one Apache Cassandra node. You can setup a single node of
Cassandra on your computer for development and testing. For production deployment,
a three or more node cluster is recommended.
-Cassandra requires Java and we recommend that you use the same version of Java
+__Use the right Java.__ Cassandra requires Java and we recommend that you use the same version of Java
for Cassandra as you use to run Tomcat and ElasticSearch.
-Refer to the [Apache Cassandra documentation](http://wiki.apache.org/cassandra/GettingStarted)
-for instructions on how to install Cassandra. The [Datastax documentation for Cassandra 1.2](http://docs.datastax.com/en/cassandra/1.2/cassandra/features/featuresTOC.html) is also helpful.
+__Refer to the [Apache Cassandra documentation](http://wiki.apache.org/cassandra/GettingStarted)
+for instructions on how to install Cassandra__. The [Datastax documentation for Cassandra 1.2](http://docs.datastax.com/en/cassandra/1.2/cassandra/features/featuresTOC.html) is also helpful.
Once you are up and running make a note of these things:
* The name of the Cassandra cluster
* Hostname or IP address of each Cassandra node
* Port number used for Cassandra RPC (the default is 9160)
* Replication factor of Cassandra cluster
+
-### Setup ElasticSearch
+### Stack STEP #2: Setup ElasticSearch
Usergrid also needs access to at least one ElasticSearch node. As with Cassandra,
you can setup single ElasticSearch node on your computer, and you should run
a cluster in production.
-ElasticSearch requires Java and you MUST ensure that you use the same version of Java
-for ElasticSearch as you do for running Tomcat.
+__Use the right Java__. ElasticSearch requires Java and you *must* ensure that you use the
+same version of Java for ElasticSearch as you do for running Tomcat.
-Refer to the [ElasticSearch 1.4 documentation](https://www.elastic.co/guide/en/elasticsearch/reference/1.4/index.html)
-for instructions on how to install.
-Once you are up and running make a note of these things:
+__Refer to the
+[ElasticSearch 1.4 documentation](https://www.elastic.co/guide/en/elasticsearch/reference/1.4/index.html)
+for instructions on how to install__. Once you are up and running make a note of these things:
* The name of the ElasticSearch cluster
* Hostname or IP address of each ElasticSearch node
* Port number used for ElasticSearch protocol (the default is 9200)
-If you are running a single-node ElasticSearch cluster then you should
-set the number of replicas to zero, otherwise it will appear to be unhealthy.
+__Running a single-node?__ If you are running a single-node ElasticSearch cluster then
+you should set the number of replicas to zero, otherwise the cluster will report status YELLOW.
curl -XPUT 'localhost:9200/_settings' -d '{"index" : { "number_of_replicas" : 0}}'
+
-### Setup Tomcat and deploy the Usergrid Stack
+### Stack STEP #3: Setup Tomcat
The Usergrid Stack is contained in a file named ROOT.war, a standard Java EE WAR
ready for deployment to Tomcat. On each machine that will run the Usergrid Stack
you must install the Java SE 8 JDK and Tomcat 7+.
-Refer to the [Apache Tomcat 7](https://tomcat.apache.org/tomcat-7.0-doc/setup.html) documentation for installation instructions.
-Once Tomcat installed, you need to create and edit some configuration files.
+__Refer to the [Apache Tomcat 7](https://tomcat.apache.org/tomcat-7.0-doc/setup.html) documentation for instructions on how to install__. Once Tomcat installed, you need to create and edit some configuration files.
-### Configure Usergrid Stack
-You must create a Usergrid properties file called __usergrid-deployment.properties__.
+### Stack STEP #4: Configure Usergrid Stack & Logging
+
+You must create a Usergrid properties file called `usergrid-deployment.properties`.
The properties in this file tell Usergrid how to communicate with Cassandra and
ElasticSearch, and how to form URLs using the hostname you wish to use for Usegrid.
There are many properties that you can set to configure Usergrid.
Once you have created your Usergrid properties file, place it in the Tomcat lib directory.
-On a Linux system, that directory is probably located at __/usr/share/tomcat7/lib__.
+On a Linux system, that directory is probably located at `/usr/share/tomcat7/lib`.
__What goes in a properties file?__
@@ -91,29 +155,31 @@ The default properties file that is built into Usergrid contains the full list o
You should review the defaults in the above file. To get you started, let's look at a minimal example properties file that you can edit and use as your own.
+
#### 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:
+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:__
| Value | Description |
|-------------|-------------|
-| __BASEURL__ | This is the base URL for the Usergrid installation, e.g. __https://api.example.com__. |
+| __BASEURL__ | This is the base URL for the Usergrid installation, e.g. `https://api.example.com`. |
| __USERGRID_CLUSTER_NAME__ | This is your name for your Usergrid installation. |
| __CASSANDRA_CLUSTER_NAME__ | Name of Cassandra cluster, must match what's in Cassandra configuration. |
-| __CASSANDRA_HOSTS__ | Comma-separated lists of Cassandra hosts, with port numbers if you are not using the default 9120. The default for this property is __localhost:9120__ |
+| __CASSANDRA_HOSTS__ | Comma-separated lists of Cassandra hosts, with port numbers if you are not using the default 9120. The default for this property is `localhost:9120` |
| __ELASTICSEARCH_CLUSTER_NAME__ | Name of ElasticSearch cluster, must match what's in ElasticSearch configuration. |
-| __ELASTICSEARCH_HOSTS__ | 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__ |
+| __ELASTICSEARCH_HOSTS__ | 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` |
| __SUPER_USER_EMAIL__ | Email address of person responsible for the superuser account. |
| __SUPER_USER_PASSWORD__ | Password for the superuser account. |
-| __TEST_ADMIN_USER_EMAIL__ | If __usergrid.setup-test-account=true__, as shown below, Usergrid will create a test account and you should specify a valid email here. |
+| __TEST_ADMIN_USER_EMAIL__ | If `usergrid.setup-test-account=true`, as shown below, Usergrid will create a test account and you should specify a valid email here. |
| __TEST_ADMIN_USER_PASSWORD__ | Password for the username 'test' account. |
+
Make sure you set all of the above properties when you edit this example for your installation.
-__Example 1: usergrid-deployment.properties file__
+Example 1: usergrid-deployment.properties file
usergrid.cluster_name=${USERGRID_CLUSTER_NAME}
@@ -178,7 +244,7 @@ __Example 1: usergrid-deployment.properties file__
usergrid.user.resetpw.url=${BASEURL}/%s/%s/users/%s/resetpw
-### Configure Logging
+#### 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.
@@ -188,13 +254,14 @@ 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.
-#### Example Logging Configuration
+
+##### Example Logging Configuration
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.
-__Example 2: log4.properties file__
+Example 2: log4.properties file
# output messages into a rolling log file as well as stdout
log4j.rootLogger=ERROR,stdout
@@ -211,32 +278,116 @@ __Example 2: log4.properties file__
log4j.logger.me.prettyprint.hector.api.beans.AbstractComposite=ERROR
-#### Add Logging Configuration to Tomcat
+##### Add Logging Configuration to Tomcat
+
+You can configure Tomcat to use your Log4j properties file but adding a system property to Tomcat
+named `log4j.configuration` which must be set to a `file:/` URL that points to your
+properties file. One way to add the above property to the Tomcat start-up is to add a line to a
+Tomcat `setenv.sh` script in Tomcat's bin directory. If that file does not exist, then create it.
+
+For example, if your property file is in `/usr/share/tomcat7/lib/log4j.properties`, then you
+would add the following line to `setenv.sh`:
+
+ export JAVA_OPTS="-Dlog4j.configuration=file:///usr/share/tomcat7/lib/log4j.properties"
+
+If the file already exists and already sets the JAVA_OPTS variable, then you'll have to
+add your `-D` option to ones already there. Also note, you might want set other `-D` and `-X`
+options in that setenv file, e.g. Java heap size.
-You can configure Tomcat to use your Log4j properties file but adding a __-D__ system property to Tomcat.
-The property is __log4j.configuration__ and you must set it to be a "file:/" URL that points to your
-properties file.
-For example, if your property file is in /usr/share/tomcat7/lib/log4j.properties, then the variable would be set like this: __-Dlog4j.configuration=file:///usr/share/tomcat7/lib/log4j.properties__
+### Stack STEP #5: Deploy ROOT.war to Tomcat
-There are a variety of ways for you to set that property in the Tomcat startup, one way is to create
-a Tomcat setenv script in Tomcat's bin directory that sets the property in the JAVA_OPTS environment variable. For example on a Linux system you might do something like this to create the file:
+The next step is to deploy the Usergrid Stack software to Tomcat. There are a variey of ways
+of doing this and the simplest is probably to place the Usergrid Stack `ROOT.war` file into
+the Tomcat `webapps` directory, then restart Tomcat.
-__Example 3: Creating a Tomcat setenv.sh file on Linux__
- cat >> /usr/share/tomcat7/bin/setenv.sh << EOF
- export JAVA_OPTS="-Dlog4j.configuration=file:///usr/share/tomcat7/lib/log4j.properties"
- EOF
- chmod +x /usr/share/tomcat7/bin/setenv.sh
+__For example, on Linux...__
-You might want set other __-D__ and __-X__ options in that setenv file, e.g. Java heap size.
+You would probabaly copy the ROOT.war file like so:
+ cp ROOT.war /usr/share/tomcat7/webapps
+
+And you would restart Tomcat 7 like so:
-### Deploy ROOT.war to Tomcat
+ /etc/init.d/tomcat7 restart
+
+You can watch the Tomcat log in `/var/log/tomcat7/catalina.out` for errors:
-The next step is to deploy the Usergrid Stack software to Tomcat. There are a variey of ways
-of doing this and the simplest is probably to place the Usergrid Stack ROOT.war file into
-the Tomcat webapps directory, then restart Tomcat.
+ tail -f /var/log/tomcat7/catalina.out
+
+ Look for messages like this, which indicate that the ROOT.war file was deployed:
+
+ INFO: Starting service Catalina
+ Jan 29, 2016 1:00:32 PM org.apache.catalina.core.StandardEngine startInternal
+ INFO: Starting Servlet Engine: Apache Tomcat/7.0.59
+ Jan 29, 2016 1:00:32 PM org.apache.catalina.startup.HostConfig deployWAR
+ INFO: Deploying web application archive /usr/share/tomcat7/webapps/ROOT.war
+
+
+__Does it work?__
+
+Check to see if Usergrid is up and running by calling the status end-point.
+If your web browser is running on the same computer as Tomcat (and Tomcat is on port 8080),
+then you can browse to [http://localhost:8080/status](http://localhost:8080/status)
+to view the Usergrid status page.
+
+Or you can use curl:
+
+ curl http://localhost:8080/status
+
+If you get a JSON file of status data, then you're ready to move to the next step.
+You should see a response that begins like this:
+
+ {
+ "timestamp" : 1454090178953,
+ "duration" : 10,
+ "status" : {
+ "started" : 1453957327516,
+ "uptime" : 132851437,
+ "version" : "201601240200-595955dff9ee4a706de9d97b86c5f0636fe24b43",
+ "cassandraAvailable" : true,
+ "cassandraStatus" : "GREEN",
+ "managementAppIndexStatus" : "GREEN",
+ "queueDepth" : 0,
+ "org.apache.usergrid.count.AbstractBatcher" : {
+ "add_invocation" : {
+ "type" : "timer",
+ "unit" : "microseconds",
+
+ ... etc. ...
+
+
+#### Initialize the Usergrid Database
+
+Next, you must initialize the Usergrid database, index and query systems.
+
+To do this you must issue a series of HTTP operations using the superuser credentials.
+You can only do this if Usergrid is configured to allow superused login via
+this property `usergrid.sysadmin.login.allowed=true` and if you used the
+above example properties file, it is allowed.
+
+The three operation you must perform are expressed by the curl commands below and,
+of course, you will have ot change the password 'test' to match the superuser password
+that you set in your Usergrid properties file.
+
+ curl -X PUT http://localhost:8080/system/database/setup -u superuser:test
+ curl -X PUT http://localhost:8080/system/database/bootstrap -u superuser:test
+ curl -X GET http://localhost:8080/system/superuser/setup -u superuser:test
+
+When you issue each of those curl commands, you should see a success message like this:
+
+ {
+ "action" : "cassandra setup",
+ "status" : "ok",
+ "timestamp" : 1454100922067,
+ "duration" : 374
+ }
+
+If you don't see a success message, then refer to the Tomcat logs for error message and
+seek help from the Usergrid community.
+
+Now that you've gotten Usergrid up and running, you're ready to deploy the Usergrid Portal.
## Deploying the Usergrid Portal
@@ -244,4 +395,34 @@ the Tomcat webapps directory, then restart Tomcat.
The Usergrid Portal is an HTML5/JavaScript application, a bunch of static files that
can be deployed to any web server, e.g. Apache HTTPD or Tomcat.
-Configuration File
+To deploy the Portal to a web server, you will un-tar the `usergrid-portal.tar` file into
+directory that serves as the root directory of your web pages.
+
+For example, with Tomcat on Linux you might do something like this:
+
+ cp usergrid-portal.tar /usr/share/tomcat7/webapps
+ cd /usr/share/tomcat7/webapps
+ tar xf usergrid-portal.tar
+
+Then you will probably want to rename the Portal directory to something that will work
+well in a URL. For example, if you want your Portal to exist at the path `/portal` then:
+
+ mv usergrid-portal.2.0.18 portal
+
+Once you have done that there is one more step. You need to configure the portal so that
+it can find the Usergrid stack. You do that by editing the `portal/config.js` and changing
+this line:
+
+ Usergrid.overrideUrl = 'http://localhost:8080/';
+
+To set the hostname that you will be using for your Usergrid installation.
+
+
+
+
+
+
+
+
+
+