[tor-commits] [onionoo/master] Apply documentation tweaks by iwakeh.
karsten at torproject.org
karsten at torproject.org
Mon Sep 1 09:26:38 UTC 2014
commit a6abbbafe63da776fbf5445f01292b1c41df6fe8
Author: Karsten Loesing <karsten.loesing at 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/
More information about the tor-commits
mailing list