commit a6abbbafe63da776fbf5445f01292b1c41df6fe8 Author: Karsten Loesing karsten.loesing@gmx.net Date: Sun Aug 31 19:27:36 2014 +0200

Apply documentation tweaks by iwakeh.

Implements #12934. --- HOWTO-VAGRANT.md | 43 +++++++++++++++++++++++++++++++++++++------ INSTALL | 17 +++++++++++------ build.xml | 3 ++- vagrant/bootstrap.sh | 1 - 4 files changed, 50 insertions(+), 14 deletions(-)

diff --git a/HOWTO-VAGRANT.md b/HOWTO-VAGRANT.md index ae8783e..2cac164 100644 --- a/HOWTO-VAGRANT.md +++ b/HOWTO-VAGRANT.md @@ -1,7 +1,25 @@ How to use Vagrant to build and test Onionoo ============================================

-Before using Vagrant, make sure that Onionoo builds correctly on the host system. This may require running `git submodule init && git submodule update`, as well as providing all required libraries. +Before using Vagrant, make sure that Onionoo builds correctly on the host +system. +This may require running `git submodule init && git submodule update`, as +well as providing all required libraries. + +The given Vagrant file uses Version 2, i.e., a Vagrant installation +of version 1.1 or above is necessary. +The following was tested using 1.4.3 and VirtualBox 4.3.14. +(Wheezy stable only provides 1.0.3, Jessie provides 1.4.3) + +Local changes to the Vagrantfile: +Tell Vagrant how much memory the virtual machine may use, i.e., change + +``` +vb.memory = 4096 +``` + +to some value that makes sense on your machine. +Rule of thumb: less than half the RAM, but as much as you want to spare.

Create a Debian Wheezy 64 bit instance:

@@ -9,17 +27,24 @@ Create a Debian Wheezy 64 bit instance: vagrant up ```

-This command downloads the virtual machine imagine, unless it has been downloaded before, creates a new virtual machine, and runs the bootstrap script in `vagrant/bootstrap.sh`. This may take a few minutes. +This command downloads the virtual machine imagine, unless it has been +downloaded before, creates a new virtual machine, and runs the bootstrap +script in `vagrant/bootstrap.sh`. This may take a few minutes.

-Once this is all done, log into the virtual machine and change to the Onionoo working directory: +Once this is all done, log into the virtual machine and change to the +Onionoo working directory:

``` vagrant ssh cd /srv/onionoo.torproject.org/onionoo/ ```

-Important: better avoid runninng Ant in the `/vagrant/` directory (which is shared with the host), or the guest system will write directly to the host system, which performs not really well. +Important: better avoid runninng Ant in the `/vagrant/` directory (which +is shared with the host), or the guest system will write directly to the +host system, which performs not really well.

+Read the INSTALL file and make the appropriate changes to adapt everything +to your setup, e.g., memory settings. Compile Onionoo, run the unit tests and then the cron part of it:

``` @@ -28,7 +53,8 @@ ant test ant run ```

-This step may take an hour or more. Onionoo downloads the last three days of Tor descriptors, which is about 2 GiB, and processes them. +This step may take an hour or more. Onionoo downloads the last three days +of Tor descriptors, which is about 2 GiB, and processes them.

Once these steps are done, deploy the servlet to the local Tomcat server:

@@ -36,7 +62,12 @@ Once these steps are done, deploy the servlet to the local Tomcat server: ant war ```

-Test the Onionoo service using a browser on the host (port 8080 on the guest is forwarded to the host). Sample URL: +Test the Onionoo service using a browser on the host (port 8080 on the guest +is forwarded to the host). Sample URL:

http://localhost:8080/onionoo/summary?limit=2

+Note that Tomcat's default server.xml needs no changing for running in the +development environment. +See the INSTALL file for necessary changes in the production environment. + diff --git a/INSTALL b/INSTALL index 58bbc41..2d73b78 100644 --- a/INSTALL +++ b/INSTALL @@ -11,7 +11,7 @@ $ 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 +Install Java 1.6 or higher, ant 1.8 or higher, and Tomcat 6 -----------------------------------------------------------

$ javac -version @@ -109,6 +109,9 @@ Test the hourly data processing process ---------------------------------------

Run the data processing process that will afterwards be run once per hour. +Currently, memory is set to 4G. If you have more or less RAM to spare, +change the value for the maxmemory.value property near the top of the +build.xml file. The initial run may take a while:

$ ant run @@ -127,8 +130,10 @@ one: Configure Tomcat ----------------

-The following file may be a useful Tomcat configuration file. Put it in -/etc/tomcat6/server.xml: +The following file may be a useful Tomcat configuration file. +Make changes according to your server setup, i.e. replace ${your-host-ip} +with your ip address and the like (ports, lognames and paths). +Put it in /etc/tomcat6/server.xml:

<Server port="8005" shutdown="SHUTDOWN"> <Service name="Catalina"> @@ -139,11 +144,11 @@ The following file may be a useful Tomcat configuration file. Put it in 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" + <Engine name="Catalina" defaultHost="${your-host-ip}"> + <Host name="${your-host-ip}" appBase="webapps" unpackWARs="true" autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false"> - <Alias>85.214.195.203</Alias> + <Alias>${your-host-ip}</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"/> diff --git a/build.xml b/build.xml index 97bb207..0d04892 100644 --- a/build.xml +++ b/build.xml @@ -1,4 +1,5 @@ <project default="run" name="onionoo" basedir="."> + <property name="maxmemory.value" value="4g"/> <property name="javasources" value="src/main/java"/> <property name="tests" value="src/test/java"/> <property name="classes" value="classes"/> @@ -92,7 +93,7 @@ </target> <target name="run" depends="compile"> <java fork="true" - maxmemory="4g" + maxmemory="${maxmemory.value}" classname="org.torproject.onionoo.cron.Main" error="errors"> <classpath refid="classpath"/> diff --git a/vagrant/bootstrap.sh b/vagrant/bootstrap.sh index 78e48f3..f3f0118 100644 --- a/vagrant/bootstrap.sh +++ b/vagrant/bootstrap.sh @@ -21,7 +21,6 @@ ln -s /vagrant/etc ln -s /vagrant/geoip ln -s /vagrant/src ln -s /vagrant/web -ln -s /srv/o ln -s /srv/onionoo.torproject.org/onionoo/onionoo.war \ /var/lib/tomcat6/webapps/onionoo.war chown -R vagrant:vagrant /srv/onionoo.torproject.org/