Human Echolocation WebApp

h1. Deployment troubleshooting

h4. What versions of Java and Tomcat do I need?

The current MATLAB Compiler Runtime needs Java 7. The MCR version needs to match the MATLAB version used to compile the MATLAB code, so this ultimately depends on what version of MATLAB you have a licence for. We have MATLAB R2013b and that's what these instructions are based on.

We also used Tomcat 7 in our testing. You'll need to make sure that Tomcat is using Java 7 if there is more than one version installed -- e.g. on Ubuntu that means editing JAVA_HOME in /etc/default/tomcat7.

h4. Can't find servlet-api.jar

This should appear in a Tomcat installation directory -- you need to make sure you build the webapp against the same version of the servlet API as you will be deploying it against (i.e the same Tomcat installation).

Sometimes this file is installed with a different name, e.g. on Ubuntu you may find it in /usr/share/java/tomcat-servlet-api-3.0.jar. You should rename it when you copy it.

h4. Tomcat manager URL asks for username and password, but I don't know what they are

The default roles are set up in a Tomcat config file, something like /etc/tomcat7/tomcat-users.xml. If no user is defined with the manager-gui role, you will need to add one, e.g. by adding to the middle of the file:

<pre>

 <role rolename="manager-gui"/>

 <role rolename="manager-script"/>

 <user username="admin" password="admin" roles="manager-gui,manager-script"/>

</pre>

But note that you should give the role a sensible password, not just admin.

h4. Tomcat manager refuses to start application

Showing a message such as

<pre>

FAIL - Application at context path /echoapp could not be started

</pre>

with very little extra information. Try searching the Tomcat log (catalina.out) for the text "Unsupported major.minor version" -- if you see this, then that means your application was compiled with a newer version of Java than the one Tomcat is using. Best to make sure you have only one version of Java (6 or 7) installed.

h4. Could not initialize class com.mathworks.toolbox.javabuilder.internal.MWMCR

This message in the Tomcat logs probably means that the LD_LIBRARY_PATH variable hasn't been set correctly. You need to copy the LD_LIBRARY_PATH as shown at the end of the MCR installation process into the Tomcat initialisation scripts.

On Linux this usually means you will have a file called setenv.sh in the same directory as the Tomcat startup.sh, catalina.sh and so on, and it will contain

<pre>

export LD_LIBRARY_PATH=<the full path as indicated by the MCR installer>

</pre>

h4. Could not access the MCR component cache

This error in the Tomcat logs means that the MATLAB compiler runtime is trying to write to a cache directory it doesn't have access to. This may mean that the MCR was installed for use by a different user from the Tomcat one rather than in a global installation.

To fix this, you can set a dedicated cache directory: add a line to the Tomcat setenv.sh script saying something like

<pre>

export MCR_CACHE_ROOT=/tmp/mcr-cache

</pre>

Make sure the path you specify exists and is writable by the Tomcat user.