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 systemctl start tomcat7
</pre>

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.)