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.

1. Obtain the current code from Mercurial repository¶

I use EasyMercurial 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)

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.

3. Install Java, Tomcat, and Ant¶

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)

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)

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.

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.

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.

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:

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

6. Build the WAR file bundle¶

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

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>

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.

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.