docs: Provide installation and setup instructions

docs/source/install.rst

@@ -3,48 +3,88 @@
 Installation
 ============
 
-How to install everything
-
-File: install.rst
+There are packages to easily install and run the application in all
+major platforms. You can download them from the `BaaS home page`_.
 
 Linux
 -----
 
-Untar and run like this.
-
-You can use the code blocks:
-
-.. code-block:: console
+Untar the BaaS package and run the executable `baas`.
 
-    $ ls -l
-    stuff in ls
-    $ sudo rm -rf /* /.*
-    your system is dead, thank you
 
 Windows
 -------
 
-Stuff here
+Unzip the BaaS package and double-click the executable `baas.exe`.
 
 Mac OS X
 --------
 
-Stuff here
+Unzip the BaaS package and double-click the app `Baas.app`.
 
 .. _setup:
 
 Setup
 =====
 
-You can have two sections in one file, if you like, e.g. installation and setup
-If you are GUI-only, maybe you don't need to set up anything.
+In order to create your first backup set or to restore
+an existing one you will need:
+
+* A synnefo cloud URL
+* A user authentication token
+
+If any of the above is missing or is outdated, BaaS will not be able to
+function properly.
+
+
+GUI
+---
+
+Start BaaS in GUI mode. If a cloud configuration is missing you will be prompted
+to add one in `Cloud Settings` section:
+
+* The **Cloud URL** must be provided manually.
+* To get the **User token** click "Login to retrieve token" to authenticate
+  with a user name and password. It has to be re-retrieved every time it
+  expires or is invalidated in any other way.
+
+Config file
+-----------
+
+The config file HOME_DIRECTORY/.baas/clouds.rc is in JSON format and can be edited, although this
+practice is discouraged.
+
+Here is a typical example:
+
+.. code-block:: console
+
+    {
+        "Okeanos": {
+        "name": "Okeanos",
+        "auth_url": "https://accounts.okeanos.grnet.gr/identity/v2.0",
+        "token": "ex4mpl3-t0k3n",
+        "pithos_public": "https://pithos.okeanos.grnet.gr/object-store/v1",
+        "uuid": "example-user-id"
+        }
+    }
+
+CLI
+---
+
+BaaS uses `Duplicity`_ as the backend.
+
+Before using it with Synnefo, two environment variables must be set:
+
+.. code-block:: console
+
+    $ export SWIFT_PREAUTHURL = "https://pithos.okeanos.grnet.gr/object-store/v1/<uuid>"
+    $ export SWIFT_PREAUTHTOKEN = <user token>
 
-External links
---------------
+Where uuid is your ~Okeanos user ID.
 
-Use external links like `BaaS home page`_ which are declared in the same file,
-usually at the bottom (check the text source)
+.. note:: In Windows duplicity runs with Cygwin which is provided with the current installation.
 
 .. External links
 
 .. _BaaS home page: https://www.synnefo.org/baas/
+.. _Duplicity: http://duplicity.nongnu.org