[tor-commits] [ooni-probe/master] Improvements to the installation and usage guide

[art at torproject.org]

commit 8a2e53b5b3387b3cfd5ca98de009f6a83c62342b
Author: Arturo Filastò <art at fuffa.org>
Date:   Tue Aug 12 22:20:23 2014 +0200

    Improvements to the installation and usage guide
    
    * Add section describing how to generate decks
    * Add usage information for ooniresources
    * Add a guide on getting up and running with ooniprobe in 5 minutes
    * Move the development environment setup guide down
---
 README.rst |   93 +++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 83 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index 12d3fff..d85e352 100644
--- a/README.rst
+++ b/README.rst
@@ -44,6 +44,42 @@ Futhermore, ooniprobe takes no precautions to protect the install target machine
 from forensics analysis.  If the fact that you have installed or used ooni
 probe is a liability for you, please be aware of this risk.
 
+OONI in 5 minutes
+=================
+
+On debian testing or unstable::
+
+    sudo apt-get install ooniprobe
+
+If you are running debian stable you can get it from backports via::
+
+    sudo sh -c 'echo "deb http://http.debian.net/debian wheezy-backports main" >> /etc/apt/sources.list'
+    sudo apt-get update && sudo apt-get install ooniprobe
+
+On unix systems::
+
+    sudo pip install ooniprobe
+
+The run::
+
+    YOUR_COUNTRY_CODE="it"
+    PATH_TO_MY_DECK=`pwd`
+    mkdir my_decks
+    sudo ooniresource --update-inputs --update-geoip
+    oonideckgen --country-code $YOUR_COUNTRY_CODE -o my_decks/
+    ooniprobe -i my_decks/deck-$YOUR_COUNTRY_CODE/0.0.1-$YOUR_COUNTRY_CODE-user.deck
+
+The output from oonideckgen should give you the full path to the test deck.
+
+If you would like to contribute measurements to OONI daily you can also add
+this to your crontab::
+
+    @daily ooni /usr/bin/ooniprobe -i REPLACE_WITH_PATH_TO_THE_DECK
+
+This command should automatically do it if you did not quit the shell::
+
+      (crontab -l 2>/dev/null; echo "@daily ooni /usr/bin/ooniprobe -i $PATH_TO_MY_DECK/my_decks/$YOUR_COUNTRY_CODE/0.0.1-$YOUR_COUNTRY_CODE-user.deck") | crontab -
+
 Installation
 ============
 
@@ -80,15 +116,6 @@ without installing it is supported with the following commands::
     ./setup-dependencies.sh
     python setup.py install
 
-Setting up development environment
-----------------------------------
-
-On debian based systems this can be done with::
-
-    sudo apt-get install libgeoip-dev python-virtualenv virtualenvwrapper
-    mkvirtualenv ooniprobe
-    python setup.py install
-    pip install -r requirements-dev.txt
 
 Other platforms (with Vagrant)
 ------------------------------
@@ -143,6 +170,43 @@ found inside of ``~/.ooni/ooniprobe.conf``.
 By default ooniprobe will not include personal identifying information in the
 test result, nor create a pcap file. This behavior can be personalized.
 
+
+Updating resources
+------------------
+
+To generate decks you will have to update the input resources of ooniprobe.
+
+This can be done with::
+
+    ooniresource --update-inputs
+
+If you get a permission error, you may have to run the command as root or
+change the ooniprobe data directory inside of `ooniprobe.conf`.
+
+On some platforms, for example debian contrib, you will not get all the geoip
+related files needed. In that case it is possible to manually download them
+with ``ooniresources``::
+
+    ooniresource --update-geoip
+
+Generating decks
+----------------
+
+You can generate decks for your country thanks to the oonideckgen command.
+
+If you wish, for example, to generate a deck to be run in the country of Italy,
+you can do so (be sure to have updated the input resources first) by running::
+
+    oonideck --country-code IT --output ~/
+
+You will now have in your home a folder called `deck-it`, containing the ooni
+deck (ends with .deck) and the inputs.
+Note: that you should not move the `deck-*` directory once it has been
+generated as the paths to the inputs referenced by the test in the deck are
+absolute. If you want your deck to live in another directory you must
+regenerated it.
+
+
 Running decks
 -------------
 
@@ -244,7 +308,6 @@ If your distributation supports capabilities you can avoid needing to run OONI a
     setcap cap_net_admin,cap_net_raw+eip /path/to/your/virtualenv's/python
 
 
-
 Reporting bugs
 ==============
 
@@ -280,3 +343,13 @@ that is different from master) with::
 
     git format-patch master --stdout > my_first_ooniprobe.patch
 
+
+Setting up development environment
+----------------------------------
+
+On debian based systems this can be done with::
+
+    sudo apt-get install libgeoip-dev python-virtualenv virtualenvwrapper
+    mkvirtualenv ooniprobe
+    python setup.py install
+    pip install -r requirements-dev.txt