Clone the Onionoo server repository
-----------------------------------

Create working directory /srv/onionoo/, make it writable for the metrics
user, and clone the Onionoo server repository into it.  Commands prefixed
with # are meant to be run by root, commands with $ by user metrics:

# mkdir /srv/onionoo
# chown metrics:metrics /srv/onionoo
$ git clone https://git.torproject.org/onionoo.git /srv/onionoo/
$ cd /srv/onionoo


Install Java 1.5 or higher, ant 1.8 or higher, and Tomcat 6
-----------------------------------------------------------

$ javac -version
javac 1.6.0_26

$ ant -version
Apache Ant version 1.8.0 compiled on March 11 2010


Provide required .jar files
---------------------------

Download or build the following .jar files and put them in the lib/
directory:

- Apache Commons Codec 1.4
- Apache Commons Compress 1.4.1
- Apache Commons Lang 2.6
- Servlet API, e.g., from Tomcat 6
- Tor Metrics Descriptor Library, metrics-lib
- Gson 2.2.3

Attempt to compile the Java sources to make sure that everything works
correctly:

$ ant compile


Download GeoIP and ASN database files
-------------------------------------

Onionoo uses an IP-to-city database and an IP-to-ASN database to provide
additional information about a relay's location.

The IP-to-city database to be deployed with Onionoo needs to have its "A1"
("Anonymous Proxy") entries fixed just like Tor's IP-to-country file.  See
Tor's src/config/README.geoip for detailed information.

First, change to the geoip/ directory:

$ cd geoip/

Download the most recent MaxMind GeoLite City database and unzip it in the
current directory, junking paths:

$ wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity_CSV/GeoLiteCity-latest.zip
$ unzip -j GeoLiteCity-latest.zip

Run deanonymind.py in the local directory:

$ python deanonymind.py

Review the output to learn about applied automatic/manual changes and
watch out for any warnings.  Possibly edit geoip-manual to make
more/fewer/different manual changes and re-run deanonymind.py.  To look at
automatic and manual changes, run:

$ diff -U1 GeoLiteCity-Blocks.csv Automatic-GeoLiteCity-Blocks.csv
$ diff -U1 Automatic-GeoLiteCity-Blocks.csv Manual-GeoLiteCity-Blocks.csv

Download MaxMind's country and region codes files to the current
directory:

$ wget http://dev.maxmind.com/static/csv/codes/iso3166.csv
$ wget http://dev.maxmind.com/static/csv/codes/maxmind/region.csv

Download the most recent MaxMind ASN database file and unzip it in the
current directory:

$ wget http://www.maxmind.com/download/geoip/database/asnum/GeoIPASNum2.zip
$ unzip GeoIPASNum2.zip

Change back to the root working directory:

$ cd ../


Test the rsync of descriptors from metrics.torproject.org
---------------------------------------------------------

Run the initial rsync:

$ rsync -arz metrics.torproject.org::metrics-recent in

The result should be around 1G of data in the in/ directory, as of January
2012.

(If you want to pre-populate bandwidth and weights data with archived
data, download the tarballs from https://metrics.torproject.org/data.html
and process them one after the other.  There is no requirement to process
data in any given order.)


Test the hourly data processing process
---------------------------------------

Run the data processing process that will afterwards be run once per hour.
The initial run may take a while:

$ ant run


Set up an hourly cronjob
------------------------

Check the contents of bin/update.sh and whether they match the commands
that worked for you.  Once they do, add a crontab line similar to this
one:

15 * * * * cd /srv/onionoo/ && bin/update.sh


Configure Tomcat
----------------

The following file may be a useful Tomcat configuration file.  Put it in
/etc/tomcat6/server.xml:

<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="on" compressionMinSize="2048"
               noCompressionUserAgents="gozilla, traviata"
               compressableMimeType="text/html,application/json" />
    <Engine name="Catalina" defaultHost="85.214.195.203">
      <Host name="84.214.195.203" appBase="webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false">
        <Alias>85.214.195.203</Alias>
        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs" prefix="onionoo_access_log." suffix=".txt"
               pattern="%l %u %t %r %s %b" resolveHosts="false"/>
      </Host>
    </Engine>
  </Service>
</Server>

It may also be necessary to increase Tomcat's maximum heap space.  Do this
by editing JAVA_OPTS in /etc/default/tomcat6 and change "-Xmx128m" to
"-Xmx512m".


Deploy the Tomcat application
-----------------------------

Create a .war file:

$ ant war

Create a symbolic link to the .war file, so that non-root users can
re-deploy the application in the future.  Run the following commands as
root:

# cd /var/lib/tomcat6/webapps/
# ln -s /srv/onionoo/onionoo.war onionoo.war

The Onionoo server should now be available at
http://localhost:8080/onionoo/.