Human Echolocation WebApp

h1. Deployment runthrough

This is an example deployment, on a 64-bit Linux host. There are various different ways to do this and the details will vary from one platform to another.

h2. 1. Obtain the current code from Mercurial repository

<pre>
$ hg clone https://code.soundsoftware.ac.uk/hg/human-echolocation-java-webapp
http authorization required for https://code.soundsoftware.ac.uk/hg/human-echolocation-java-webapp
realm: Mercurial repository for Human Echolocation WebApp
user: chrisca
password:
destination directory: human-echolocation-java-webapp
requesting all changes
adding changesets
adding manifests
adding file changes
added 41 changesets with 93 changes to 40 files
updating to branch default
23 files updated, 0 files merged, 0 files removed, 0 files unresolved
$
</pre>

h2. 2. Install the MATLAB Compiler Runtime

Navigate to http://www.mathworks.co.uk/products/compiler/mcr/ and find the download URL, then use as follows.

<pre>
$ mkdir mcr
$ cd mcr
$ wget 'http://www.mathworks.co.uk/supportfiles/downloads/R2013b/deployment_files/R2013b/installers/glnxa64/MCR_R2013b_glnxa64_installer.zip'
--2014-02-24 10:00:10-- http://www.mathworks.co.uk/supportfiles/downloads/R2013b/deployment_files/R2013b/installers/glnxa64/MCR_R2013b_glnxa64_installer.zip
Resolving www.mathworks.co.uk (www.mathworks.co.uk)... 23.214.117.160
Connecting to www.mathworks.co.uk (www.mathworks.co.uk)|23.214.117.160|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 488473010 (466M) [application/zip]
Saving to: ‘MCR_R2013b_glnxa64_installer.zip’

100%[======================================>] 488,473,010 7.81MB/s in 60s

2014-02-24 10:01:11 (7.71 MB/s) - ‘MCR_R2013b_glnxa64_installer.zip’ saved [488473010/488473010]
$ unzip MCR_R2013b_glnxa64_installer.zip
Archive: MCR_R2013b_glnxa64_installer.zip
inflating: archives/mpc_resources_common_1348598029.enc
inflating: archives/cgir_mi_core_glnxa64_1375749553.xml
[etc]
$ ./install
</pre>

The installer window then pops up (X server connection required for graphical interaction here).

The default installation folder is @/usr/local/MATLAB/MATLAB_Compiler_Runtime@. I'm going to accept that.

The installer runs, and then prints out the following:

<pre>
On the target computer, append the following to your LD_LIBRARY_PATH environment variable:

/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/runtime/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/bin/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/os/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64/native_threads:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64/server:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64

Next, set the XAPPLRESDIR environment variable to the following value:

/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/X11/app-defaults
</pre>

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

Make sure we're back in the webapp folder (the one we cloned from Mercurial earlier)

<pre>
$ cd ../human-echolocation-java-webapp
</pre>

Copy in the Servlet API library from our application server (in this case Tomcat):

<pre>
$ cp /usr/share/java/tomcat7/servlet-api.jar .
</pre>

And the MATLAB MCR JavaBuilder library:

<pre>
$ cp /usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/toolbox/javabuilder/jar/javabuilder.jar ./WebContent/WEB-INF/lib/
</pre>

h2. 4. Build the WAR file bundle

Simple enough:

<pre>
$ ant
Buildfile: /work/human-echolocation-java-webapp/build.xml

build:
[javac] Compiling 2 source files to /work/human-echolocation-java-webapp/WebContent/WEB-INF/classes

build-war:
[war] Building war: /work/human-echolocation-java-webapp/echoapp.war

BUILD SUCCESSFUL
Total time: 1 second
$
</pre>

h2. 5. Deploy the bundle and start the app server

<pre>
$ sudo cp echoapp.war /var/lib/tomcat7/webapps/
$ sudo /usr/share/tomcat7/bin/catalina.sh start
</pre>

_Note: on many Linux distros you can start Tomcat as a system service, e.g. using "systemctl start tomcat7". I tried this initially but later on found that logs weren't being written where I expected and my config changes weren't taking effect, so I started running it directly from the script in the Tomcat directory install instead_

Then navigate to the Tomcat manager URL http://localhost:8080/manager/html in a browser. (This URL may vary. The default admin username and password are admin/admin; of course these must be changed and the manager port firewalled in any real deployment.)

Because the WAR file was present when Tomcat was started, it should be listed as running in the manager interface. If it isn't, we can hit the Start button on the line listing echoapp (and if we have redeployed it since last time, we should hit Reload).

h2. 6. Test the app (spoiler: It doesn't work yet)

Now the app has been deployed, we can run it by going to the http://localhost:8080/echoapp URL linked in the Tomcat manager page. This should display the basic Human Echolocation Webapp page. If I enter a value into the Distance field and hit Generate... nothing happens.

I can debug this by trying to retrieve the result from the HumanEchoServlet directly, through the URL http://localhost:8080/echoapp/HumanEcho. http://localhost:8080/HumanEcho. This shows a stack trace, of which the pertinent lines are:

<pre>
java.lang.NoClassDefFoundError: Could not initialize class com.mathworks.toolbox.javabuilder.internal.MWMCR
uk.ac.soton.isvr.IsvrMCRFactory.newInstance(IsvrMCRFactory.java:47)
uk.ac.soton.isvr.IsvrMCRFactory.newInstance(IsvrMCRFactory.java:58)
uk.ac.soton.isvr.HumanEcho.<init>(HumanEcho.java:62)
</pre>

OK, so this is probably where the library path from the MCR comes into play. We can set environment variables for Tomcat in a @setenv.sh@ script in the directory where the other Tomcat shell scripts are found. In my case that is @/usr/share/tomcat7/bin@, so I create a file in there called @setenv.sh@ with the following content

<pre>
export LD_LIBRARY_PATH=/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/runtime/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/bin/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/os/glnxa64:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64/native_threads:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64/server:/usr/local/MATLAB/MATLAB_Compiler_Runtime/v82/sys/java/jre/glnxa64/jre/lib/amd64
</pre>

and run

<pre>
$ sudo chmod +x setenv.sh
$ sudo ./catalina.sh stop systemctl restart tomcat7
$ sudo ./catalina.sh start
</pre>

On reloading the app and re-requesting the servlet, the error message has disappeared and instead we see changed:

<pre>
java.lang.NumberFormatException: null java.lang.UnsatisfiedLinkError: Failed to find the library libmwmclmcrrt.so.8.2, required by MATLAB Builder JA, on java.library.path.
This library is typically installed along with MATLAB or the MCR, its absence may indicate an issue with that installation or the current path configuration.
The MCR version that this component is trying to use is: 8.2.

com.mathworks.toolbox.javabuilder.internal.MCRConfiguration$ProxyLibraryDir.get(MCRConfiguration.java:239)
java.lang.Integer.parseInt(Integer.java:454) com.mathworks.toolbox.javabuilder.internal.MCRConfiguration$ProxyLibraryDir.&lt;clinit&gt;(MCRConfiguration.java:245)
java.lang.Integer.parseInt(Integer.java:527) com.mathworks.toolbox.javabuilder.internal.MCRConfiguration.getProxyLibraryDir(MCRConfiguration.java:250)
HumanEchoServlet.doGet(Unknown Source)
javax.servlet.http.HttpServlet.service(HttpServlet.java:620) com.mathworks.toolbox.javabuilder.internal.MCRConfiguration$MCRRoot.get(MCRConfiguration.java:71)
</pre>

OK, Hitting Reload, however, we get the first error message back again -- so this is just (!) probably a bug in our servlet -- it isn't handling the absent dist red herring, and azim parameters correctly. If I add some random values by retrieving http://localhost:8080/echoapp/HumanEcho?dist=8&azim=4 instead, then I get served a WAV file. Hurrah! nothing has changed.