Deploying to local Tomcat & Cassandra¶

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
[email protected]
[email protected]
usergrid.management.mailer=Myself<[email protected]>
[email protected]
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.

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
[email protected]     <--- Change this
usergrid.sysadmin.login.password=pw123               <--- Change this
usergrid.sysadmin.login.allowed=true
[email protected]           <--- 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