Armin's blog - Random posts mainly for me to remember things

This is a quick overview of how I install ODK on our servers mainly to document this process internally and make it easier to reproduce. This is not a detailed documentation nor do I talk about system requirments since this is described better by the ODK site for Tomcat and AWS instances.

ODK installer

First off, I run the ODK installer, which I downloaded into the home folder of the root user (this is on a Linux box).

cd /root/
./ODK_Aggregate_v1.3.1.run

First thing is to accept all the licenses, which are a longish list of open source licenses for software used by ODK.

After that select the directory where you want the WAR file and SQL setup file to be put. I use the instance name as a sub-folder in the root direcotry.

/root/<instance name>

Next, you will have to choose the platform. Since I have MySQL installed as a database I choose option 2.

Say n to the Tomcat download (already installed and covered by another documentation) and skip the SSL instructions by saying n, and say you have no SSL certificate by choosing option 1 (we do have a certificate but SSL is handled by nginx).

When asked about "Apache Tomcat Port Configuration", skip by saying no, then leave the HTTP connector as is (port 8080).

Important: Change the DNS name to the correct sudomain:

odk.lmbutler-ssa.net

Since we have the database up and running say n to downloading MySQL, as well as, n to the SQL connector.

When asked about the database portnumber either enter the port. Since we use the standard MySQL port we just keep the default (port 3306), as well as, the localhost ip default offered (127.0.0.1).

When asked about the database user I tend to use the prefix odk_ with the instance name. Like so:

odk_<instance name>

And since I want to keep things easy and since my MySQL instance is not reachable from the internet (I block the MySql port and offer no webinterface) I choose the same as above for the password and database name.

DO NOT do this if you are unsure about your own situation. If in doubt pick a secure password.

Now you will have to choose an instance name (just type it into the prompt).

Then enter a valid Gmail address. Use a Gmail address that you have control over since this will be the only way to login after installing.

Having answered all the questions you see a prompt stating Setup is now ready to begin configuring ODK Aggregate. Answer Y and for additional deployment answer n. Now you are down and you should find data in the folder you chose earlier on (/root/instance_name).

Database setup

In the folder that was created for you by the installer you will find 3 files:

create_db_and_user.sql
ODKAggregate.war
README.html

To set up the database just get the content of the createdbanduser.sql file printed out in the shell by issuing `cat createdbanduser.sql`. This will show the following SQL statements:

create database `odk_instancename`;
create user 'odk_instancename'@'localhost' identified by 'odk_instancename';
grant all on `odk_instancename`.* to 'odk_instancename'@'localhost' identified by 'odk_instancename';
flush privileges;

Login to MySql as the root user (myslq -u root -p and then type your password) and then run the commands from above to setup the database for your new ODK instance.

Congratulations you have a brand new database for your now ODK instance. Next step will be to install ODK on the tomcat server.

Installing ODK

ODK provides a Tomcat installation file called a WAR file (ODKAggregate.war). In order to install ODK you have to stop Tomcat, move this file into the webapps folder, and restart Tomcat.

Since Tomcat will use the name of the WAR file to name the URL path we will rename the WAR file with the instance name:

cp ODKAggregate.war instance_name.war

Now we will stop Tomcat, move the WAR file into place, restart Tomcat, and check everything is working.

/path/to/tomcat/bin/shutdown.sh
mv instance_name.war /path/to/tomcat/webapps/.
/path/to/tomcat/bin/shutdown.sh ; tail -f /path/to/tomcat/logs/catalina.out

You will see a lot of logging information. You are looking for this line: INFO: Server startup in 30687 ms. This means your server is up and running (use ctrl+c to stop the logging output).

If you look in webapps folder you whould see the war file and a folder with the same name, e.g. chat.war and a chat folder. This means that Tomcat expanded the war file correctly. Now you should be able to view your new ODK installation under http://your.domain.com:8080/instance_name. If you are like me you might have to lower the firewall for that port. I do this by issuing ufw allow 8080.

I do see a ODK site stating Awaiting Redirect but nothing else happens. One of the problems seems to be that the site tries to switch to https on port 8443, but opening this port doesn't solve the problem for me. So now comes an odd bit that I described in a previous post in a bit more detail. Here I will just show how I fix this. My goal is to not having to open ports 8080 and 8433, but use the standard http and https ports via ngninx.

The solutions lies within a ODK specific jar-file called ODKAggregate-settings.jar. You find this file in the following folder: /path/to/tomcat/webapps/instance_name/WEB-INF/lib.

Copy this file to your local machine in a new directory (I am hosting on a remote linux box and use a Mac). For exampel:

mkdir ~/instance_name
scp user@your.machine.com:/path/to/tomcat/webapps/instance_name/WEB-INF/lib/ODKAggregate-settings.jar ~/instance_name/.

Maybe you have to provide your password if you don't use SSH keys!

Now you should find the ODKAggregate-settings.jar file in your newly created local folder.

Manipulating the jar file

We will have to make a small change to one of the files within the jar, repackage the jar and upload the jar back to the server.

The file we want to change within the jar is called security.properties and you can check that it is there by listing the jar content with jar tf ODKAggregate-settings.jar.

Now we extract the security.properties file with the following command:

jar xf ODKAggregate-settings.jar security.properties

Now open the file with our favourite editor and go to line 32 where you see

#security.server.port=80
#security.server.securePort=443
security.server.port=8080
security.server.securePort=8443

change it to:

security.server.port=80
security.server.securePort=443
#security.server.port=8080
#security.server.securePort=8443

and save the file. Now we put the security.properties file back into the jar file:

jar uf ODKAggregate-settings.jar security.properties

You have now updated the jar with the new settings file and you can copy it back to your server. Stop Tomcat before you do this

scp ODKAggregate-settings.jar user@your.machine.com:/path/to/tomcat/webapps/instance_name/WEB-INF/lib/.

Now restart Tomcat and you should be able to reach your new ODK instance http://your.server.com/instance_name

Important notes

Please be aware that this documentation is specific to how we have setup our ODK servers. I am using ufw to block all ports except for 80 and 443 and on both ports I have nginx listening. This setup reverse proxies a certain subdomain to Tomcat, which in turn serves several ODK instances.