<?xml version="1.0"?>
<document xmlns="http://maven.apache.org/XDOC/2.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
        <title>Building</title>
        <author email="help@eurekaclinical.org">
            The Eureka! Clinical Analytics Team
        </author>
    </properties>

    <body>
        <section name="Building ${project.name} from Source">
            <p>${project.name} uses <a href="http://maven.apache.org">Maven</a>
            as its build and management tool.</p>
            
            <subsection name="Prerequisites">
                <p>Required:</p>
                <ul>
					<li>Download and install <a href="http://www.oracle.com/technetwork/java/index.html">Java 1.7</a>, if you don't already have it.</li>
                    <li>Download and install <a href="http://maven.apache.org">Maven</a> (Version 3 is required), if you don't already have it.</li>
                    <li>Get the <a href="index.html">latest ${project.name} source</a>.</li>
					<li>For deployment, download and install <a href="http://tomcat.apache.org">Apache Tomcat</a> version 7.</li>
                </ul>
            </subsection>
			<subsection name="Maven options">
				<p>To build ${project.name}, Maven has to be configured to use 
					more memory:
				</p>
				<source>set MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"</source>
			</subsection>
            <subsection name="A normal build (runs tests)">
                <source>mvn clean install</source>
				<p>If successful, you will find the following warfiles:</p>
				<ul>
					<li>
						<code>eureka-webapp/target/eureka-webapp.war</code>
					</li>
					<li>
						<code>eureka-services/target/eureka-services.war</code>
					</li>
					<li>
						<code>eureka-protempa-etl/target/eureka-protempa-etl.war</code>
					</li>
				</ul>
				<p>Next, you can deploy the warfiles into your servlet 
					container.
				</p>
				<h4>Deploying Eureka! for the first time</h4>
				<p>You will need to go an extra step and compile a binary
					distribution package. The distribution package contains
					configuration files for Eureka. A
					separate project, <code>eureka-package</code>, builds the binary
					distribution. Download the source code
					(<a href="http://maven.cci.emory.edu/nexus/service/local/artifact/maven/redirect?r=${project.distributionManagementArtifactRepository.id}&amp;g=${project.groupId}&amp;a=eureka-package&amp;v=${project.version}&amp;c=src&amp;e=zip">eureka-package-${project.version}-src.zip</a>).
					Then run:</p>
					<source>mvn clean install</source>
					<p>If successful, you will find the distribution in the
					<code>target</code> directory. Then, follow the 
					<a href="../../install.html">installation instructions</a> 
					on the main Eureka! website.
				</p>
            </subsection>
			<subsection name="Deployment from source">
				<h4>Configuration</h4>
				<p>You may copy the three warfiles above 
					into your Tomcat deployment's <code>$CATALINA_HOME/webapps</code> 
					directory. Alternatively, if you have the 
					<a href="http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html">Tomcat manager app</a> 
					deployed, you may deploy with a maven command. Execute a 
					build as above, and then execute one of the 
					following deployment commands. Each executes in a specified
					Maven profile (local, dev and prd). For each profile you 
					want to use, specify a server in your 
					<code>$HOME/.m2/settings.xml</code> file (see 
					<a href="http://maven.apache.org/settings.html">Settings Reference</a>
					for more information). For example:
				</p>
				<source>&lt;profile&gt;
					&lt;id&gt;eureka-tomcat-local&lt;/id&gt;
					&lt;properties&gt;
						&lt;local.url&gt;http://tomcathostname:tomcatport/manager/text&lt;/local.url&gt;
					&lt;/properties&gt;
				&lt;/profile&gt;</source>
				<p>Replace the URL in the <code>local.url</code> property with your own.
				</p>
				<p>These profiles also support properties for specifying 
					connection information for the services and backend 
					database schemas, similarly starting with 
					<code>local</code>, 
					<code>dev</code>, or 
					<code>prd</code> depending on the profile you want to use
					(<code>local</code> properties are shown):
				</p>
				<dl>
					<dt>
						<code>local.services.db.jdbc.driver</code>
					</dt>
					<dd>JDBC driver classname for the services schema.</dd>
					<dt>
						<code>local.services.db.jdbc.url</code>
					</dt>
					<dd>The JDBC URL for the services schema.</dd>
					<dt>
						<code>local.services.username</code>
					</dt>
					<dd>Database username for the services schema.</dd>
					<dt>
						<code>local.services.password</code>
					</dt>
					<dd>Database password for the services schema.</dd>
					<dt>
						<code>local.protempaetl.db.jdbc.driver</code>
					</dt>
					<dd>JDBC driver classname for the backend schema.</dd>
					<dt>
						<code>local.protempaetl.db.jdbc.url</code>
					</dt>
					<dd>The JDBC URL for the backend schema.</dd>
					<dt>
						<code>local.protempaetl.username</code>
					</dt>
					<dd>Database username for the backend schema.</dd>
					<dt>
						<code>local.protempaetl.password</code>
					</dt>
					<dd>Database password for the backend schema.</dd>
				</dl>

				<p>These properties may be used to update the schema via
					maven as described in the next section.
				</p>

				<h4>Updating the database schema from Maven</h4>
				<p>In the eureka-services directory, execute the following to
					to make the services schema in your local development 
					environment up-to-date.
				</p>
				<source>mvn liquibase:update -Peureka-tomcat-local</source>

				<p>This command will also create the schema from scratch if
					you have not done so already. The same command works to 
					update the backend schema if you run it from the 
					eureka-protempa-etl directory.
				</p>

				<p>To find out whether your schema needs updating, run the
					following command:
				</p>
				<source>mvn liquibase:status -Peureka-tomcat-local</source>

				<h4>Deploy to Tomcat (local installation)</h4>
				<source>mvn tomcat:deploy -Peureka-tomcat-local</source>

				<h4>Deploy to Tomcat (dev installation)</h4>
				<source>mvn tomcat:deploy -Peureka-tomcat-dev</source>

				<h4>Deploy to Tomcat (production installation)</h4>
				<source>mvn tomcat:deploy -Peureka-tomcat-prd</source>
				
				<h4>Redeploy to Tomcat</h4>
				<source>mvn tomcat:redeploy -Peureka-tomcat-{local|dev|prd}</source>
				
				<h4>Undeploy from Tomcat</h4>
				<source>mvn tomcat:undeploy -Peureka-tomcat-{local|dev|prd}</source>
			</subsection>
			<subsection name="Run Eureka! in embedded tomcat server">
				<p>This is for testing purposes during software development
					only. After building Eureka!, run:
				</p>
				<source>mvn tomcat:run</source>
			</subsection>
        </section>
    </body>
</document>