Human Echolocation WebApp

h1. Deployment runthrough on Windows

This is an example deployment on a 32-bit Windows 7 host.

See [[Deployment runthrough]] for a typical Linux deployment.

See [[Deployment troubleshooting]] for notes about Java and Tomcat versions and on things that might go wrong (mostly from a Linux perspective).

Note: If you don't have admin privileges on the Windows host (i.e. can't install to @C:\Program Files@ it is still possible to do this by installing to your home directory, but several details may change and that setup has not been tested in this runthrough.

h2. 1. Obtain the current code from Mercurial repository

I use "EasyMercurial":http://easyhg.org/ as my Windows Mercurial client. Use "Open" -> "Remote repository" and provide @https://code.soundsoftware.ac.uk/hg/human-echolocation-java-webapp@ as the remote repository URL, cloning to a folder called @human-echolocation-java-webapp@ in my Documents folder. (See "screenshot":/attachments/download/1182/Screenshot%20-%20300914%20-%2008_51_01.png.)

h2. 2. Install the MATLAB Compiler Runtime

Navigate to http://www.mathworks.co.uk/products/compiler/mcr/ and find the download URL. (I am using release R2013b here.) Download and run the installer, accepting its default installation path of @C:\Program Files\MATLAB\MATLAB Compiler Runtime@.

h2. 3. Install Java, Tomcat, and Ant

h3. Java

Navigate to http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html to download (in our case) Java 7 JDK. Run the installer and install to the default path.

Now make sure the JAVA_HOME environment variable points to the JDK just installed, and not to the JRE runtime (this is necessary for use of the Ant build tool later). To do this, go to the Windows Control Panel, search for "environment" and open the environment variable dialog. Add a new user environment variable setting JAVA_HOME to the JDK location. (See "screenshot":/attachments/download/1184/Screenshot%20-%20300914%20-%2010_24_01.png)

h3. Tomcat

Apache Tomcat is a web application server commonly used for Java servlet applications.

Navigate to http://tomcat.apache.org/ and download the "32-bit/64-bit Windows Service installer" for (in our case) Tomcat 7. Again we accept the default path (@C:\Program Files\Apache Software Foundation\Tomcat 7.0@). Note that the installer asks you to set a username and password for the Tomcat administrator login -- this is optional, but it will save some configuration later if you set a password now. (See "screenshot":/attachments/download/1183/Screenshot%20-%20300914%20-%2010_05_03.png)

When installation is complete, you will be given the option to start Tomcat -- accept it. You should then be able to open the URL @http://127.0.0.1:8080/manager/html@ in a browser to see the Tomcat manager page. You will be asked for a username and password to access it -- these should be the same ones you provided during installation.

h3. Ant

Apache Ant is the tool used to build the webapp project. (One could install an entire development environment such as Eclipse, as well, but that is beyond the scope of this page!)

Navigate to http://ant.apache.org/bindownload.cgi and download the Zip archive of the current version of Ant. Unpack it anywhere you like, but make a note of the path. I am unpacking it and copying the @apache-ant-1.9.4@ folder into @C:\Program Files\Apache Software Foundation@ next door to Tomcat.

h2. 4. Bring dependent JAR files into the webapp folder

Copy @C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\servlet-api.jar@ into the @human-echolocation-java-webapp@ folder.

Copy @C:\Program Files\MATLAB\MATLAB Compiler Runtime\v82\toolbox\javabuilder\jar\javabuilder.jar@ into the @human-echolocation-java-webapp\WebContent\WEB-INF\lib@ folder.

h2. 5. Configure the application paths

Edit the file @human-echolocation-java-webapp\WebContent\WEB-INF\classes\HumanEcho.properties@ and set the @indir@ and @outdir@ properties to appropriate paths. 

The @indir@ path must be a specific location (@webapps\\echoapp\\WEB-INF\\data@) relative to the Tomcat webapp root, and @outdir@ can be any directory path that does not already exist and that the Tomcat process will have permission to create.

Both paths must have Windows path format (with drive prefix and backslash separator) and the backslashes must be escaped, like so:

<pre>

indir=C:\\Program Files\\Apache Software Foundation\\Tomcat 7.0\\webapps\\echoapp\\WEB-INF\\data

outdir=C:\\tmp\\wav

</pre>

h2. 6. Build the WAR file bundle

Open a Command Prompt window and cd to the @human-echolocation-java-webapp@ folder. Then run Ant:

<pre>

C:\Users\Chris\Documents\human-echolocation-java-webapp>"c:\Program Files\Apache Software Foundation\apache-ant-1.9.4\bin\ant"

Buildfile: C:\Users\Chris\Documents\human-echolocation-java-webapp\build.xml

build:

    [javac] Compiling 2 source files to C:\Users\Chris\Documents\human-echolocation-java-webapp\WebContent\WEB-INF\classes

ir:

     [copy] Copying 1 file to C:\Users\Chris\Documents\human-echolocation-java-webapp\WebContent\WEB-INF\data

build-war:

      [war] Building war: C:\Users\Chris\Documents\human-echolocation-java-webapp\echoapp.war

BUILD SUCCESSFUL

Total time: 1 second

C:\Users\Chris\Documents\human-echolocation-java-webapp>

</pre>

h2. 7. Deploy the bundle

Copy the file @echoapp.war@ from the @human-echolocation-java-webapp@ folder into the Tomcat applications folder at @C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps@.

If the Tomcat service was already running -- as it should have been -- then Tomcat will automatically unbundle and deploy the WAR file. (You should see an @echoapp@ folder being created automatically in the @webapps@ folder when you paste in the WAR file.)

Now navigate again to http://127.0.0.1:8080/manager/html in a browser (or reload the page if you already have it open). You should see @/echoapp@ listed as an application. If it is not running, click the Start button next to it.

h2. 8. Test the app

Navigate to http://127.0.0.1:8080/echoapp/ in your browser. You should see the Human Echolocation Webapp front page.