From 8757d554c7052d6533772b0a693ec89122b9630e Mon Sep 17 00:00:00 2001
From: Benjamin Dauvergne <bdauvergne@entrouvert.com>
Date: Fri, 23 Jan 2015 17:39:45 +0100
Subject: [PATCH] Add README section describing content of the environment
 dictionnary (#6339)

---
 README | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/README b/README
index d665177..2067578 100644
--- a/README
+++ b/README
@@ -61,6 +61,50 @@ being deployed.  Successfully deployed services will add a link to their
 administration pages on the homepage.
 
 
+Environment
+-----------
+
+An Hobo agent is a class defined in `hobo.agent.services` and derived from
+`BaseService`. For each service in the environment dictionary sent by the hobo
+portal, it's instantiated with the key `base_url`, `title` and `secret_key` of
+the service. If the `base_url` matches the `AGENT_HOST_PATTERNS` locally
+defined, the `execute()` method of the instant is called, passing it the full
+environment dictionary.
+
+The environment dictionary contains services for this particular agent and all
+other services defined on the portal. The `execute()` method should only create
+a tenant for the service whose `base_url` was passed to constructor. All other
+informations are only for defining links with other services. The schema of the
+dictionary is::
+
+    {
+        'timestamp': <current_time_as_an_unix_timestamp>,
+        'users': [
+            {
+                'username': 'john.doe',
+                'first_name': 'John',
+                'last_name': 'Doe',
+                'email': 'john.doe@example.com',
+                'password': '<django-compatible-hashed-password>',
+            }
+        },
+        'services': [
+           {
+                'service-id': 'authentic' / 'wcs' / 'passerelle',
+                'title': 'name of service,
+                'secret_key': '..', # base secret for Django applications or other needs
+                'base_url': 'base url of the service',
+                'template_name': 'demo', # name of the template bundle to use
+                'variables': {
+                    'variable-1': 'value-of-variable-1'
+                }
+           }
+        ]
+        'variables': {
+            'variable-1': 'value-of-variable-1'
+        }
+    }
+
 Agents
 ------
 
@@ -74,3 +118,4 @@ to use sudo if necessary).
 Template keys defined in SERVICE_TEMPLATES have to map wcs skeleton sites
 (created from settings / export) stored in /var/lib/wcs/skeletons (the exact
 directory may vary according to the wcs configuration).
+