# Usergrid 2.1.0 Deployment Guide 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. ## Intended audience 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. ## Prerequsites 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) * [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.x or 2.x](http://cassandra.apache.org/download/) * [ElasticSearch 1.4.x or 1.7.x](https://www.elastic.co/downloads/elasticsearch) Optional but helpful: * An HTTP or REST client, such as [curl](http://curl.haxx.se) * A web server such as [Apache HTTPD](https://httpd.apache.org) for running the Usergrid Portal ## Getting Started __Download the Apache Usergrid 2.1.0 binary release__ from the official Usergrid releases page: * [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 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. ### Stack STEP #1: Setup Cassandra 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. Usergrid uses Cassandra's Thrift protocol and on Cassandra 2.x releases you MUST enable Thrift by setting `start_rpc` in your `cassandra.yaml` file: # Whether to start the thrift rpc server. start_rpc: true __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 ### 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. __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: * The name of the ElasticSearch cluster * Hostname or IP address of each ElasticSearch node * Port number used for ElasticSearch protocol (the default is 9200) __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}}' ### 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 instructions on how to install__. Once Tomcat installed, you need to create and edit some configuration files. ### 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`. __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: * [The Default Usergrid Properties File](https://github.com/apache/usergrid/blob/master/stack/config/src/main/resources/usergrid-default.properties) 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}`. 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 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:__
Value | Description |
---|---|
__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 9160. The default for this property is `localhost:9160` |
__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` |
__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_PASSWORD__ | Password for the username 'test' account. |