--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/admin/pyro.rst	Thu Jan 08 22:11:06 2015 +0100
@@ -0,0 +1,62 @@
+.. _UsingPyro:
+
+Working with a distributed client (using Pyro)
+==============================================
+
+In some circumstances, it is practical to split the repository and
+web-client parts of the application for load-balancing reasons. Or
+one wants to access the repository from independant scripts to consult
+or update the database.
+
+Prerequisites
+-------------
+
+For this to work, several steps have to be taken in order.
+
+You must first ensure that the appropriate software is installed and
+running (see :ref:`ConfigEnv`)::
+
+  pyro-nsd -x -p 6969
+
+Then you have to set appropriate options in your configuration. For
+instance::
+
+  pyro-server=yes
+  pyro-ns-host=localhost:6969
+
+  pyro-instance-id=myinstancename
+
+Connect to the CubicWeb repository from a python script
+-------------------------------------------------------
+
+Assuming pyro-nsd is running and your instance is configured with ``pyro-server=yes``,
+you will be able to use :mod:`cubicweb.dbapi` api to initiate the connection.
+
+.. note::
+    Regardless of whether your instance is pyro activated or not, you can still
+    achieve this by using cubicweb-ctl shell scripts in a simpler way, as by default
+    it creates a repository 'in-memory' instead of connecting through pyro. That
+    also means you've to be on the host where the instance is running.
+
+Finally, the client (for instance a python script) must connect specifically
+as in the following example code:
+
+.. sourcecode:: python
+
+    from cubicweb import dbapi
+
+    cnx = dbapi.connect(database='instance-id', user='admin', password='admin')
+    cnx.load_appobjects()
+    cur = cnx.cursor()
+    for name in (u'Personal', u'Professional', u'Computers'):
+        cur.execute('INSERT Tag T: T name %(n)s', {'n': name})
+    cnx.commit()
+
+Calling :meth:`cubicweb.dbapi.load_appobjects`, will populate the
+cubicweb registries (see :ref:`VRegistryIntro`) with the application
+objects installed on the host where the script runs. You'll then be
+allowed to use the ORM goodies and custom entity methods and views. Of
+course this is optional, without it you can still get the repository
+data through the connection but in a roughly way: only RQL cursors
+will be available, e.g. you can't even build entity objects from the
+result set.