blob: 916990f27115eb8b562b350975322e7a7425a5d3 [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Usegrid 1: Deploying to Tomcat &mdash; Apache Usergrid 2.x documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="top" title="Apache Usergrid 2.x documentation" href="../index.html"/>
<script src="../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="../index.html" class="icon icon-home"> Apache Usergrid
</a>
<div class="version">
2.x
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../introduction/overview.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/usergrid-features.html">Usergrid Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/data-model.html">Usergrid Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/async-vs-sync.html">Async vs. sync calls</a></li>
</ul>
<p class="caption"><span class="caption-text">Using Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-account.html">Creating a Usergrid Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/creating-a-new-application.html">Creating a new application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-a-sandbox-app.html">Using a Sandbox Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../using-usergrid/using-the-api.html">Using the API</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Storage</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/data-store-dbms.html">The Usergrid Data Store</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/optimizing-access.html">Data Store Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/collections.html">Collections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/entities.html">Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Queries</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/querying-your-data.html">Querying your data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/query-parameters.html">Query parameters &amp; clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/operators-and-types.html">Query operators &amp; data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/advanced-query-usage.html">Advanced query usage</a></li>
</ul>
<p class="caption"><span class="caption-text">Entity Connections</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/connecting-entities.html">Connecting entities</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/retrieving-entities.html">Retrieving connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/disconnecting-entities.html">Disconnecting entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Push Notifications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/overview.html">Push notifications overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/adding-push-support.html">Adding push notifications support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/getting-started.html">Getting started with push notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/tutorial.html">Tutorial: Push notifications sample app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/registering.html">Registering with a notification service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-notifiers.html">Creating notifiers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/managing-users-and-devices.html">Managing users and devices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-and-managing-notifications.html">Creating and managing notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption"><span class="caption-text">Security &amp; Authentication</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/app-security.html">Security &amp; token authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-permissions.html">Using permissions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-roles.html">Using roles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users &amp; app clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/user-authentication-types.html">Authentication levels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/changing-token-time-live-ttl.html">Changing token expiration (time-to-live)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-api-requests.html">Authenticating API requests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/revoking-tokens-logout.html">Revoking tokens (logout)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/facebook-sign.html">Facebook sign in</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/securing-your-app.html">Security best practices</a></li>
</ul>
<p class="caption"><span class="caption-text">User Management &amp; Social Graph</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-management.html">User management &amp; social graph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/working-user-data.html">Working with User Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/group.html">Working with group data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/activity.html">Activity</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html">Social Graph Connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html#creating-other-connections">Creating other connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/messagee-example.html">App Example - Messagee</a></li>
</ul>
<p class="caption"><span class="caption-text">Geo-location</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../geolocation/geolocation.html">Geolocating your Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Assets &amp; Files</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/uploading-assets.html">Uploading assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/retrieving-assets.html">Retrieving assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/folders.html">Folders</a></li>
</ul>
<p class="caption"><span class="caption-text">Counters &amp; Events</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/events-and-counters.html">Counters &amp; events</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html">Creating &amp; incrementing counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#decrementing-resetting-counters">Decrementing/resetting counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/creating-and-incrementing-counters.html#using-counters-hierarchically">Using counters hierarchically</a></li>
<li class="toctree-l1"><a class="reference internal" href="../counters-and-events/retrieving-counters.html">Retrieving counters</a></li>
</ul>
<p class="caption"><span class="caption-text">Organizations &amp; Applications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization &amp; application management</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/organization.html">Organization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/application.html">Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/admin-user.html">Admin user</a></li>
</ul>
<p class="caption"><span class="caption-text">API Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html">Methods</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#models">Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#sub-types">Sub-Types</a></li>
</ul>
<p class="caption"><span class="caption-text">Client SDKs</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../sdks/tbd.html">COMING SOON...</a></li>
</ul>
<p class="caption"><span class="caption-text">Installing Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="deployment-guide.html">Usergrid 2.1.0 Deployment Guide</a></li>
</ul>
<p class="caption"><span class="caption-text">More about Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/presos-and-videos.html">Presentations &amp; Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code &amp; Docs</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Apache Usergrid</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li>Usegrid 1: Deploying to Tomcat</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/installation/ug1-deploy-to-tomcat.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="usegrid-1-deploying-to-tomcat">
<h1>Usegrid 1: Deploying to Tomcat<a class="headerlink" href="#usegrid-1-deploying-to-tomcat" title="Permalink to this headline"></a></h1>
<p>This is a guide that explains how to install and run Usergrid using
stock Tomcat and Cassandra on a single computer.</p>
<p>NOTE: running Cassandra on a single computer is something you should do
ONLY for testing purposes. You don&#8217;t want to run one node in production
even just to start out. To get the benefit of Cassandra&#8217;s architecture,
which is designed to support linear scalability. You should be running a
Cassandra cluster with at least three nodes.</p>
<p>For more information:</p>
<ul class="simple">
<li><a class="reference external" href="http://planetcassandra.org/blog/post/cassandra-faq-can-i-start-with-a-single-node/">Cassandra FAQ: Can I Start With a Single
Node?</a></li>
<li><a class="reference external" href="http://stackoverflow.com/questions/18462530/why-dont-you-start-off-with-a-single-small-cassandra-server-as-you-usually">Why don&#8217;t you start off with a “single &amp; small” Cassandra
server</a></li>
</ul>
<div class="section" id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><a class="reference external" href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK
1.7</a></li>
<li><a class="reference external" href="http://maven.apache.org/">Maven</a></li>
</ul>
</div>
<div class="section" id="download">
<h2>Download<a class="headerlink" href="#download" title="Permalink to this headline"></a></h2>
<p>Use GitHub to clone the
<a class="reference external" href="https://github.com/apache/usergrid">apache/usergrid</a> repo.</p>
<p>Or you can start by <a class="reference external" href="https://github.com/apache/usergrid/archive/master.zip">downloading our latest
code</a> and
extract it.</p>
</div>
<div class="section" id="building">
<h2>Building<a class="headerlink" href="#building" title="Permalink to this headline"></a></h2>
<p>From the command line, navigate to <code class="docutils literal"><span class="pre">stack</span></code> directory and type the
following:</p>
<div class="highlight-python"><div class="highlight"><pre>mvn clean package -DskipTests=true
</pre></div>
</div>
<p>Once you are done the Usergrid application will be package as a Java EE
WAR file at the location <strong>stack/rest/target/ROOT.war</strong>.</p>
</div>
<div class="section" id="install-and-configure-cassandra">
<h2>Install and configure Cassandra<a class="headerlink" href="#install-and-configure-cassandra" title="Permalink to this headline"></a></h2>
<p>Install Cassandra, don&#8217;t edit configuration files as we just want
default values for this simple setup. Here are the <a class="reference external" href="http://wiki.apache.org/cassandra/GettingStarted">instructions for
installing
Cassandra</a></p>
</div>
<div class="section" id="install-and-configure-tomcat">
<h2>Install and configure Tomcat<a class="headerlink" href="#install-and-configure-tomcat" title="Permalink to this headline"></a></h2>
<p>Follow instructions, don&#8217;t edit configuration files as we just want
default values for this simple setup. Here are the <a class="reference external" href="http://tomcat.apache.org/tomcat-7.0-doc/setup.html">instructions for
installing Tomcat
7</a></p>
</div>
<div class="section" id="add-usergrid-war-to-tomcat">
<h2>Add Usergrid WAR to Tomcat<a class="headerlink" href="#add-usergrid-war-to-tomcat" title="Permalink to this headline"></a></h2>
<p>Remove the existing <code class="docutils literal"><span class="pre">tomcat/webapps/ROOT</span></code> directory.</p>
<p>Place the Usergrid <code class="docutils literal"><span class="pre">ROOT.war</span></code> file into the <code class="docutils literal"><span class="pre">tomcat/webapps</span></code>
directory</p>
</div>
<div class="section" id="add-usergrid-configuration-file-to-tomcat">
<h2>Add Usergrid configuration file to Tomcat<a class="headerlink" href="#add-usergrid-configuration-file-to-tomcat" title="Permalink to this headline"></a></h2>
<p>Create a ____usergrid-custom.properties____ file and place it in
Tomcat&#8217;s <strong>lib</strong> directory. You can find an example properties file
below that should work well for a local Tomcat &amp; Cassandra setup. You
will probably only need to change the properties below to use your email
address and preferred password for the install.</p>
<div class="highlight-python"><div class="highlight"><pre>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&lt;myself@example.com&gt;
usergrid.test-account.admin-user.email=myself@example.com
usergrid.test-account.admin-user.password=test
</pre></div>
</div>
</div>
<div class="section" id="run-usergrid-database-super-user-setup">
<h2>Run Usergrid Database &amp; Super User Setup<a class="headerlink" href="#run-usergrid-database-super-user-setup" title="Permalink to this headline"></a></h2>
<p>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.</p>
<p>Database setup URL - <a class="reference external" href="http://localhost:8080/system/database/setup">http://localhost:8080/system/database/setup</a></p>
<p>When prompted to login use the sysadmin credentials that you specified
in your <strong>usergrid-custom.properties</strong> 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.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;cassandra setup&quot;</span><span class="p">,</span>
<span class="s">&quot;status&quot;</span> <span class="p">:</span> <span class="s">&quot;ok&quot;</span><span class="p">,</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1379424622947</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">76</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Superuser setup URL - <a class="reference external" href="http://localhost:8080/system/superuser/setup">http://localhost:8080/system/superuser/setup</a></p>
<p>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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;superuser setup&quot;</span><span class="p">,</span>
<span class="s">&quot;status&quot;</span> <span class="p">:</span> <span class="s">&quot;ok&quot;</span><span class="p">,</span>
<span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1379424667936</span><span class="p">,</span>
<span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">2</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="build-the-usergrid-console">
<h2>Build the Usergrid Console<a class="headerlink" href="#build-the-usergrid-console" title="Permalink to this headline"></a></h2>
<p>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
<a class="reference external" href="https://github.com/apache/usergrid/blob/master/portal/README.md">here</a>.
Once built, copy the directory <em>portal/build/usergrid-portal</em> to
<em>tomcat/webapps</em>.</p>
</div>
<div class="section" id="login-to-the-usergrid-console-get-started">
<h2>Login to the Usergrid Console &amp; get started<a class="headerlink" href="#login-to-the-usergrid-console-get-started" title="Permalink to this headline"></a></h2>
<p>You should now be able to login to the Usergrid console and start
configuring applications, users and more.</p>
<p>You can use an static version of the portal to get started:</p>
<p><a class="reference external" href="http://localhost:8080/usergrid-portal/(http://localhost:8080/usergrid-portal">http://localhost:8080/usergrid-portal/(http://localhost:8080/usergrid-portal</a>)</p>
</div>
<div class="section" id="example-usergrid-custom-properties-file">
<h2>Example <strong>usergrid-custom.properties</strong> file<a class="headerlink" href="#example-usergrid-custom-properties-file" title="Permalink to this headline"></a></h2>
<p>Here&#8217;s a complete example properties file to get you started.</p>
<div class="highlight-python"><div class="highlight"><pre># 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&#39;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 &lt;--- Change this
usergrid.sysadmin.login.password=pw123 &lt;--- Change this
usergrid.sysadmin.login.allowed=true
usergrid.sysadmin.email=myself@example.com &lt;--- 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
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013-2015, Apache Usergrid.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.x',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>