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:
Use GitHub to clone the apache/usergrid repo.
Or you can start by downloading our latest code and extract it.
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 Cassandra, don't edit configuration files as we just want default values for this simple setup. Here are the instructions for installing Cassandra
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
Remove the existing tomcat/webapps/ROOT
directory.
Place the Usergrid ROOT.war
file into the tomcat/webapps
directory
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
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 }
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.
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)
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