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.
You should be able to follow this guide if you are a developer, system admin or operations person with some knowledge of Java application deployment and good knowledge of Linux and the bash shell.
This guide is a starting point and does NOT explain everything you need to know to run Usergrid at-scale and in production. To do that you will need some additional skills and knowledge around running, monitoring and trouble-shooting Tomcat applications, multi-node Cassandra & ElasticSearch clusters and more.
Below are the software requirements for Usergrid 2.1.0 Stack and Portal. 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)
Optional but helpful:
Deploying Usergrid starts with downloaded the Apache Usergrid release. There are three ways to go:
usergrid-2.1.0
tag (not available yet) and build Usergrid yourself.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:
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
.
The Usergrid Stack is a Java EE web application that runs on Tomcat, uses the Cassandra database for storage and the ElasticSearch search-engine for queries.
Before installing the Usegrid Stack into Tomcat, you'll start by setting up the required database and search engine nodes.
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.
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 for instructions on how to install Cassandra. The Datastax documentation for Cassandra 1.2 is also helpful. Once you are up and running make a note of these things:
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.
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 for instructions on how to install. Once you are up and running make a note of these things:
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}}'
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 documentation for instructions on how to install. Once Tomcat installed, you need to create and edit some configuration files.
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
.
What goes in a properties file?
The default properties file that is built into Usergrid contains the full list of properties, defaults and some documentation:
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.
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:
Make sure you set all of the above properties when you edit this example for your installation.
Example 1: usergrid-deployment.properties file
usergrid.cluster_name=${USERGRID_CLUSTER_NAME} cassandra.url=${CASSANDRA_HOSTS} cassanrda.cluster=${CASSANDRA_CLUSTER_NAME} elasticsearch.cluster_name=${ELASTICSEARCH_CLUSTER_NAME} elasticsearch.hosts=${ELASTIC_SEARCH_HOSTS} ###################################################### # Admin and test user setup usergrid.sysadmin.login.allowed=true usergrid.sysadmin.login.name=superuser usergrid.sysadmin.login.password=${SUPER_USER_PASSWORD} usergrid.sysadmin.login.email=${SUPER_USER_EMAIL} usergrid.sysadmin.email=${SUPER_USER_EMAIL} usergrid.sysadmin.approve.users=true usergrid.sysadmin.approve.organizations=true # Base mailer account - default for all outgoing messages usergrid.management.mailer=Admin <${SUPER_USER_EMAIL}> 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=${TEST_ADMIN_USER_EMAIL} usergrid.test-account.admin-user.password=${TEST_ADMIN_USER_PASSWORD} ###################################################### # 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=${BASEURL}/status usergrid.view.management.organizations.organization.activate=${BASEURL}/accounts/welcome usergrid.view.management.organizations.organization.confirm=${BASEURL}/accounts/welcome usergrid.view.management.users.user.activate=${BASEURL}/accounts/welcome usergrid.view.management.users.user.confirm=${BASEURL}/accounts/welcome usergrid.admin.confirmation.url=${BASEURL}/management/users/%s/confirm usergrid.user.confirmation.url=${BASEURL}/%s/%s/users/%s/confirm usergrid.organization.activation.url=${BASEURL}/management/organizations/%s/activate usergrid.admin.activation.url=${BASEURL}/management/users/%s/activate usergrid.user.activation.url=${BASEURL}%s/%s/users/%s/activate usergrid.admin.resetpw.url=${BASEURL}/management/users/%s/resetpw usergrid.user.resetpw.url=${BASEURL}/%s/%s/users/%s/resetpw
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.
To configure logging you need to:
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
# output messages into a rolling log file as well as stdout log4j.rootLogger=ERROR,stdout # stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d %p (%t) [%c] - %m%n log4j.logger.org.apache.usergrid=INFO log4j.logger.me.prettyprint.cassandra.hector.TimingLogger=WARN log4j.logger.org.apache.usergrid.rest.security.AllowAjaxFilter=WARN log4j.logger.me.prettyprint.hector.api.beans.AbstractComposite=ERROR
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.
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.
For example, on Linux...
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:
/etc/init.d/tomcat7 restart
You can watch the Tomcat log in /var/log/tomcat7/catalina.out
for errors:
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 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. ...
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.
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.
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.
Start your web server and Portal should be up and running!
Resources that might be useful to those deploying Usergrid:
Usergrid-Vagrant: A VagrantFile and set of bash scripts that will launch a Linux Virtual Machine running Cassandra, ElasticSearch, Tomcat and the Usergrid 2.1 Stack and Portal.
Usergrid AWS Cluster: An AWS Cloud Formation template and supporting scripts that create a set of multiple EC2 instances running Usergrid Stack/Portal and a set of EC2 instances running Cassandra and ElasticSearch.
That's all folks.