Update installation documentation

Document that virtual environments are now the preferred installation
option and how that works.

Closes #55.

3 files changed, 65 insertions, 33 deletions

diff --git a/README.md b/README.md
index d7cfded..6a4d6f1 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,8 @@ Install PeekabooAV
 /path/to/venv/bin/pip install .
 ```
 
+This will pull in all required packages and install them into the virtualenv.
+
 ### Configuration ###
 Take a look at ``peekaboo.conf.sample`` and ``ruleset.conf.sample``.
 
@@ -74,7 +76,7 @@ peekaboo --help
 
 ### Usage without Installation ###
 
-You can now run PeekabooAV without installing it using the ``peekaboo_debug.py`` script.
+You can also run PeekabooAV without installing it using the ``peekaboo_debug.py`` script.
 ```shell
 python peekaboo_debug.py -c /path/to/your/peekaboo.conf
 ```
diff --git a/docs/source/config.rst b/docs/source/config.rst
index 1a2907b..60bef17 100644
--- a/docs/source/config.rst
+++ b/docs/source/config.rst
@@ -27,17 +27,6 @@ You may choose VirtualBox as hypervisor. If so, you must add the Peekaboo user t
     $ sudo usermod -a -G vboxusers peekaboo
 
 
-Virtualenv
-==========
-
-You may run Peekaboo in a virtualenv. The setup is done by typing the following command:
-
-.. code-block:: shell
-
-   sudo -u peekaboo mkdir /opt/peekaboo/virtualenv
-   sudo -u peekaboo virtualenv /opt/peekaboo/virtualenv
-
-
 Configuration File
 ==================
 Peekaboo requires a configuration file to be supplied on startup.
diff --git a/docs/source/install.rst b/docs/source/install.rst
index dbcd389..d33e09b 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -7,6 +7,11 @@ In this chapter we assume that you want to use Peekaboo's extended capabilities
 files and directores with Cuckoo. Further, we assume that you want to install AMaViSd to run
 analysis of email attachments. Also, we assume that you use a Debian based Linux distribution.
 
+We are going to use python virtual environments to install cuckoo and Peekaboo
+together with their respective dependencies, because they might conflict with
+each other when trying to install all of them in the same environment
+(virtual or host).
+
 
 Packages
 ========
@@ -42,59 +47,95 @@ Depending on which DBMS you choose, there are additional packages to install.
 SQLite
 ------
 
+.. code-block:: shell
+
     $ sudo apt-get install python-sqlite sqlite3
 
 MySQL
 -----
 
+.. code-block:: shell
+
     $ sudo apt-get install mysql-server mysql-client python-mysqldb
 
 PostgreSQL
 ----------
 
+.. code-block:: shell
+
     $ sudo apt-get install postgresql python-psycopg2
 
 
 Cuckoo
 ======
-Download Cuckoo 2.0.0 from https://github.com/cuckoosandbox/cuckoo/archive/2.0.0.tar.gz
+Create a new python virtual environment and install cuckoo into it using pip:
 
 .. code-block:: shell
 
-    mkdir /opt/cuckoo
-    tar xvfz 2.0.0.tar.gz -C /opt/cuckoo
-
-Obtain Cuckoo's monitoring binaries 
-
-    $ python stuff/monitor.py
+    $ sudo virtualenv --python=/usr/bin/python2.7 /opt/cuckoo
+    $ sudo /opt/cuckoo/bin/pip install cuckoo
 
-Now, install cuckoo
+In order to test your new Cuckoo installation you should run it once:
 
-    $ cd /opt/cuckoo/cuckoo-2.0.0/
-    $ python setup.py install
+.. code-block:: shell
 
-In order to test your new Cuckoo installation you should run it once
+    $ /opt/cuckoo/bin/cuckoo
 
-    $ cuckoo
+**Note**: We're assuming these actions to be executed by the user the tools
+will be running as.
+If doing more than testing and development, a separate run user should be
+created for Peekaboo.
 
 
 Peekaboo
 ========
 
-Get Peekaboo
-------------
+Using pip
+---------
+
+A released version of Peekaboo can be installed directly via pip as follows:
+
+.. code-block:: shell
+
+    $ sudo virtualenv --python=/usr/bin/python2.7 /opt/peekaboo
+    $ sudo /opt/peekaboo/bin/pip install peekabooav
+
+Peekaboo can also be installed from the source directory which is useful in
+development or when trying out unreleased versions.
+
+Using the source code
+---------------------
+
+Start with either an unpacked tarball of the source or check it out using git:
+
+.. code-block:: shell
 
     $ git clone https://github.com/scVENUS/PeekabooAV.git
+    $ cd PeekabooAV
 
+Optionally a specific release, commit or branch can be found and checkout out:
 
-Install Dependencies
---------------------
+.. code-block:: shell
 
-    $ pip install -r requirements.txt
+    $ git tag
+    $ git branch
+    $ git checkout v1.x.x
 
-Install
--------
+The below commands again create a virtual environment and install Peekaboo
+together with all its dependencies into it:
 
-    $ python setup.py install
+.. code-block:: shell
 
-**Note**: If you want to install Peekaboo for your system wide Python, you must run this command as ``root``.
+    $ sudo virtualenv --python=/usr/bin/python2.7 /opt/peekaboo
+    $ sudo /opt/peekaboo/bin/pip install .
+
+**Note**: If you want to install Peekaboo for your system wide Python, leave
+out the virtualenv command and just run the system pip as ``root``.
+Dependencies can and will be provided by distribution packages if installed
+before running pip.
+It will however install additional dependencies into ``/usr/local``.
+This might include updates of already installed system packages and
+pip will remove the old versions from the system python directories.
+This can get very confusing and complicated over time, leading to unexpected
+behaviour.
+Again, virtual environments are recommended here.