[doc] improve server doc

2 files changed, 24 insertions, 68 deletions

diff --git a/docs/index.rst b/docs/index.rst
index ea723307..9e992835 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,12 @@ Soledad is an acronym for Synchronization of Locally Encrypted Data Among
 Devices. It is LEAP's solution for synchronizing client-encrypted data among
 all user's devices that access a LEAP provider.
 
+The application is written in Python and the `source code
+<https://0xacab.org/leap/soledad>`_ is available and licensed as free software.
+Both client and server are `distributed through pypi
+<https://pypi.python.org/pypi/leap.soledad>`_, and `Debian packages
+<https://deb.leap.se/>`_ are also provided for the server-side component.
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/docs/server.rst b/docs/server.rst
index 88bf909f..a0eb8181 100644
--- a/docs/server.rst
+++ b/docs/server.rst
@@ -1,77 +1,13 @@
 Soledad Server
 ==============
 
-A U1DB server that stores data using CouchDB as its persistence layer.
-
-.. contents::
-   :local:
-
-General information
--------------------
-
-This is written as a Twisted application and intended to be run using the
-twistd command. To start the soledad server, run:
-
-.. code-block:: bash
-
-    twistd -n --python /path/to/leap/soledad/server/server.tac
-
-An systemd script is included and will be installed system wide to make it
-feasible to start and stop the Soledad server service using a standard
-interface.
-
-Server database organization
-----------------------------
-
-Soledad Server works with one database per user and one shared database in
-which user's encrypted secrets might be stored.
-
-User database
-~~~~~~~~~~~~~
-
-Users' databases in the server are named 'user-<uuid>' and Soledad Client
-may perform synchronization between its local replicas and the user's
-database in the server. Authorization for creating, updating, deleting and
-retrieving information about the user database as well as performing
-synchronization is handled by the `leap.soledad.server.auth` module.
-
-Shared database
-~~~~~~~~~~~~~~~
-
-Each user may store password-encrypted recovery data in the shared database.
-
-Recovery documents are stored in the database without any information that
-may identify the user. In order to achieve this, the doc_id of recovery
-documents are obtained as a hash of the user's uid and the user's password.
-User's must have a valid token to interact with recovery documents, but the
-server does not perform further authentication because it has no way to know
-which recovery document belongs to each user.
-
-This has some implications:
-
-  * The security of the recovery document doc_id, and thus of access to the
-    recovery document (encrypted) content, as well as tampering with the
-    stored data, all rely on the difficulty of obtaining the user's password
-    (supposing the user's uid is somewhat public) and the security of the hash
-    function used to calculate the doc_id.
-
-  * The security of the content of a recovery document relies on the
-    difficulty of obtaining the user's password.
-
-  * If the user looses his/her password, he/she will not be able to obtain the
-    recovery document.
-
-  * Because of the above, it is recommended that recovery documents expire
-    (not implemented yet) to prevent excess storage.
-
-The authorization for creating, updating, deleting and retrieving recovery
-documents on the shared database is handled by `leap.soledad.server.auth`
-module.
+Soledad Server is a document store and a blobs server that can synchronize data
+with a Soledad Client.
 
 .. _server-config-file:
 
-Server Configuration File
--------------------------
+Configuring
+-----------
 
 Soledad Server looks for a configuration file in
 ``/etc/soledad/soledad-server.conf`` and will read the following configuration
@@ -93,3 +29,17 @@ blobs_path           The path for blobs storage in the server's file ``/var/lib/
 services_tokens_file The file containing authentication tokens for   ``/etc/soledad/services.tokens``
                      services provided through the Services API.
 ==================== =============================================== ================================
+
+Running
+-------
+
+This is written as a Twisted application and intended to be run using the
+twistd command. To start the soledad server, run:
+
+.. code-block:: bash
+
+    twistd -n --python /path/to/leap/soledad/server/server.tac
+
+An systemd script is included in the `Debian packages
+<http://deb.leap.se/repository/>`_ to make it feasible to start and stop the
+Soledad server service using a standard interface.