summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordrebs <drebs@riseup.net>2017-09-28 14:38:33 -0300
committerdrebs <drebs@riseup.net>2017-09-28 14:48:07 -0300
commitfba9c274f21e593a3d041949d873435abe922dc9 (patch)
tree1108f66e38fd0bf3dfcd8200c108792e7fede238
parent6464c0461f82844389fd6ced7c0e992920c29d87 (diff)
[doc] improve client doc
-rw-r--r--docs/client.rst75
-rw-r--r--docs/index.rst20
2 files changed, 84 insertions, 11 deletions
diff --git a/docs/client.rst b/docs/client.rst
index 3befd69c..bbbc1dec 100644
--- a/docs/client.rst
+++ b/docs/client.rst
@@ -1,9 +1,74 @@
Soledad Client
==============
-Current reasoning about Soledad can be found `here
-<https://leap.se/en/docs/design/soledad>`_. That will be cleaned up and
-migrated here in the future.
+The Soledad Client is a Python library aimed to provide access to a document
+store that can be synchronized securelly with other deviced through the Soledad
+Server. Key aspects of Soledad Client include:
-You can also take a look at :ref:`client-side-code-api` and
-:ref:`client-side-attachments-api` for information on the API.
+ * **Encrypted local storage:** All data cached locally is stored in an
+ encrypted database.
+
+ * **Client-side encrypted sync:** Soledad puts very little trust in the
+ server by encrypting all data before it is synchronized to the server and
+ by limiting ways in which the server can modify the user's data.
+
+ * **Document database:** An application using the Soledad client library is
+ presented with a document-centric database API for storage and sync.
+ Documents may be indexed, searched, and versioned.
+
+ * **Blobs storage:** The client and server API provide blobs storage, which
+ can be used both for data delivery in the server side (i.e. email) and
+ payload storage on the client side.
+
+Setting-up
+----------
+
+The following information is needed in order to instantiate a soledad client:
+
+ * ``uuid``: the user's uuid.
+ * ``passphrase``: the user's passphrase.
+ * ``secrets_path``: a local path for secrets storage.
+ * ``local_db_path``: a local path for the documents database.
+ * ``server_url``: the Soledad Server's URL.
+ * ``cert_file``: a local path for the CA certificate.
+ * ``auth_token``: an authentication token obtained after logging into the
+ provider.
+
+Once all pieces are in place, you can instantiate the client as following:
+
+.. code-block:: python
+
+ from leap.soledad.client import Soledad
+ client = Soledad(
+ uuid,
+ passphrase,
+ secrets_path=secrets_path,
+ local_db_path=local_db_path,
+ server_url=server_url,
+ cert_file=cert_file,
+ auth_token=token)
+
+Usage example
+-------------
+
+Soledad is written in the `Twisted asynchronous model
+<https://twistedmatrix.com/documents/current/core/howto/defer-intro.html>`_, so
+you will need to make sure a `reactor
+<http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html>`_
+is running.
+
+Creation of a document and synchronization is done as follows:
+
+.. code-block:: python
+
+ yield client.create_doc({'my': 'doc'}, doc_id='some-id')
+ doc = yield client.get_doc('some-id')
+ yield client.sync()
+
+The document can be modified and synchronized again:
+
+.. code-block:: python
+
+ doc.content = {'new': 'content'}
+ yield client.put_doc(doc)
+ yield client.sync()
diff --git a/docs/index.rst b/docs/index.rst
index 9e992835..679c8083 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,12 +3,20 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Soledad documentation
-=====================
+Soledad: synchronization of locally encrypted data among devices
+================================================================
-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.
+Soledad consists of a client library and a server daemon that allow
+applications to securely share a common state among devices. It is LEAP's
+solution for synchronizing client-encrypted data among user's devices that
+access a LEAP provider.
+
+
+The local application is presented with a simple, document-centric searchable
+database API. Any data saved to the database by the application is
+client-encrypted, backed up in the cloud, and synchronized among a user's
+devices. Soledad is cross-platform, open source, scalable, and features
+a highly efficient synchronization algorithm.
The application is written in Python and the `source code
<https://0xacab.org/leap/soledad>`_ is available and licensed as free software.
@@ -19,8 +27,8 @@ Both client and server are `distributed through pypi
.. toctree::
:maxdepth: 2
- client
server
+ client
reference
development
migrations