README

ExoneraTor
==========

This README describes the steps for installing ExoneraTor on Debian
GNU/Linux Jessie.  Instructions for other operating systems may vary.

In the following it is assumed that root privileges are available via
sudo.

Start by installing Git, Java, Ant, PostgreSQL, and a couple packages
containing .jar files:

$ sudo apt-get install openjdk-7-jdk ant postgresql \
  libcommons-codec-java libcommons-lang-java libpostgresql-jdbc-java \
  libservlet3.0-java

Check the versions of the newly installed tools:

$ java -version
java version "1.7.0_101"
OpenJDK Runtime Environment (IcedTea 2.6.6) (7u101-2.6.6-2~deb8u1)
OpenJDK 64-Bit Server VM (build 24.95-b01, mixed mode)

$ ant -version
Apache Ant(TM) version 1.9.4 compiled on October 7 2014

$ psql --version
psql (PostgreSQL) 9.4.8

Add an exonerator user that will be used to import descriptors into the
database once per hour:

$ sudo adduser exonerator

The database importer and website sources will be installed in
/srv/exonerator.torproject.org/ that is created as follows:

$ sudo mkdir /srv/exonerator.torproject.org/
$ sudo chmod g+ws /srv/exonerator.torproject.org/
$ sudo chown exonerator:exonerator /srv/exonerator.torproject.org/

Clone the exonerator Git repository:

$ cd /srv/exonerator.torproject.org/
$ git clone https://git.torproject.org/exonerator.git

Create a libraries directory /srv/exonerator.torproject.org/lib/ and copy
all required .jar files from /usr/share/java/ there, including:

 - /srv/exonerator.torproject.org/exonerator/lib/commons-codec-1.9.jar
 - /srv/exonerator.torproject.org/exonerator/lib/commons-lang-2.6.jar
 - /srv/exonerator.torproject.org/exonerator/lib/postgresql-jdbc3-9.2.jar
 - /srv/exonerator.torproject.org/exonerator/lib/servlet-api-3.0.jar

Obtain the DescripTor library from https://dist.torproject.org/descriptor/
and also place it in the lib/ directory:

 - /srv/exonerator.torproject.org/exonerator/lib/descriptor-1.2.0.jar

Attempt to compile the sources to see if all requirements are provided:

$ ant compile

Create a new exonerator database user.  There is no need to give the
exonerator user superuser privileges or allow it to create databases or
new roles.

$ sudo -u postgres createuser -P exonerator

Create a new database exonerator owned by user exonerator.

$ sudo -u postgres createdb -O exonerator exonerator

Import the exonerator database schema.

$ psql -f /srv/exonerator.torproject.org/exonerator/src/main/resources/db/exonerator.sql \
  exonerator

Confirm that the database now contains tables to hold ExoneraTor data.  In
the following, => will be used as the database prompt.

$ psql exonerator
=> \dt+
=> \q

Run the Java database importer.

$ ./run-exonerator.sh

The database import will take a while.  Once it's complete, check that the
database tables now contain data:

$ psql exonerator
=> \dt+
=> \q

Add a crontab entry for the database importer to run once per hour:

20 * * * * cd /srv/exonerator.torproject.org/exonerator/ && \
  ./run-exonerator.sh

The Apache HTTP Server is used as the front-end web server that serves
static resources itself and forwards requests for dynamic resources to
Apache Tomcat.

Start by installing Apache:

$ sudo apt-get install apache2

Disable Apache's default site.

$ sudo a2dissite default

Enable mod_proxy to forward requests to Tomcat.

$ sudo a2enmod proxy_http

Create a new virtual host configuration and store it in a new file
/etc/apache2/sites-available/exonerator.torproject.org with the following
content:

<VirtualHost *:80>
  ServerName exonerator.torproject.org
  ServerAdmin torproject-admin@torproject.org
  ErrorLog /var/log/apache2/error.log
  CustomLog /var/log/apache2/access.log combined
  ServerSignature On
  <IfModule mod_proxy.c>
    <Proxy *>
      Order deny,allow
      Allow from all
    </Proxy>
    ProxyPass / http://127.0.0.1:8080/exonerator/ retry=15
    ProxyPassReverse / http://127.0.0.1:8080/exonerator/
    ProxyPreserveHost on
  </IfModule>
</VirtualHost>

Enable the new virtual host.

$ sudo a2ensite exonerator.torproject.org

Restart Apache just to be sure that all changes are effective.

$ sudo service apache2 restart

Apache Tomcat will process requests for dynamic resources.

Install Tomcat:

$ sudo apt-get install tomcat8

Replace Tomcat's default configuration in /etc/tomcat8/server.xml with the
following configuration:

<Server port="8005" shutdown="SHUTDOWN">
  <Service name="Catalina">
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true"
               compression="off" compressionMinSize="2048"
               noCompressionUserAgents="gozilla, traviata"
               compressableMimeType="text/html,text/xml,text/plain" />
    <Engine name="Catalina" defaultHost="exonerator.torproject.org">
      <Host name="exonerator.torproject.org" appBase="webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false"
            copyXML="true">
        <Alias>exonerator.torproject.org</Alias>
        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs" prefix="exonerator_access_log."
               suffix=".txt" pattern="%l %u %t %r %s %b"
               resolveHosts="false"/>
      </Host>
    </Engine>
  </Service>
</Server>

Update the database password in
/srv/exonerator.torproject.org/exonerator/etc/context.xml.

Now generate the web application.

$ ant war

Add a symbolic link to the PostgreSQL JDBC library to Tomcat's lib/
folder:

$ sudo ln -s /usr/share/java/postgresql-jdbc4.jar /var/lib/tomcat8/lib/

Create a symbolic link to the exonerator.war file:

$ sudo ln -s /srv/exonerator.torproject.org/exonerator/exonerator.war \
  /var/lib/tomcat8/webapps/

Tomcat will now attempt to deploy the web application automatically.

Whenever the ExoneraTor website needs to be redeployed, generate a new
.war file and Tomcat will reload the web application automatically.

Restart Tomcat to make all configuration changes effective:

$ sudo service tomcat8 restart

The ExoneraTor website should now work.