updated README

stack/resilient/README.txt

@@ -11,10 +11,10 @@ MySQL and Postgres respectively.
 This involves three different software_types:
 
  * pull-backup
- * {something}_export
- * {something}_import
+ * {mysoftware}_export
+ * {mysoftware}_import
 
-where 'something' is the component that needs resiliency (can be postgres, mysql, erp5, and so on).
+where 'mysoftware' is the component that needs resiliency (can be postgres, mysql, erp5, and so on).
 
 
 pull-backup
@@ -39,12 +39,12 @@ example:
 This is the *active* instance - the one providing live data to the application.
 
 A backup is run via the bin/exporter script: it will
-     1) run bin/{something}-backup
+     1) run bin/{mysoftware}-backup
  and 2) notify the pull-backup instance that data is ready.
 
 The pull-backup, upon receiving the notification, will make a copy of the data and transmit it to the 'import' instances.
 
-You should provide the bin/{something}-exporter script, see for instance
+You should provide the bin/{mysoftware}-exporter script, see for instance
   http://git.erp5.org/gitweb/slapos.git/blob/HEAD:/slapos/recipe/postgres/__init__.py?js=1#l207
   http://git.erp5.org/gitweb/slapos.git/blob/HEAD:/slapos/recipe/mydumper.py?js=1#l71
 
@@ -65,10 +65,144 @@ Any number of import instances can be used. Deciding which one should take over
 or through a monitoring + election script.
 
 
-You should provide the bin/{something}-importer script, see for instance
+You should provide the bin/{mysoftware}-importer script, see for instance
 
   http://git.erp5.org/gitweb/slapos.git/blob/HEAD:/slapos/recipe/postgres/__init__.py?js=1#l233
   http://git.erp5.org/gitweb/slapos.git/blob/HEAD:/slapos/recipe/mydumper.py?js=1#l71
 
 
 
+
+In practice
+-----------
+
+Add resilience to your software
+
+Let's say you already have a file instance-mysoftware.cfg.in that instantiates your
+software. In which there is a part [mysoftware] where there is the main recipe
+that instantiates the program.
+
+You need to create two new files, instance-mysoftware-import.cfg.in and
+instance-mysoftware-export.cfg.in, following this layout:
+
+
+IMPORT:
+
+[buildout]
+extends = ${instance-mysoftware:output}
+          ${pbsready-import:output}
+
+parts +=
+    mysoftware
+    import-on-notification
+
+[importer]
+recipe = YourImportRecipe
+wrapper = $${rootdirectory:bin}/$${slap-parameter:namebase}-importer
+backup-directory = $${directory:backup}
+...
+
+
+
+EXPORT:
+
+[buildout]
+extends = ${instance-mysoftware:output}
+          ${pbsready-export:output}
+
+parts +=
+    mysoftware
+    cron-entry-backup
+
+[exporter]
+recipe = YourExportRecipe
+wrapper = $${rootdirectory:bin}/$${slap-parameter:namebase}-exporter
+backup-directory = $${directory:backup}
+...
+
+
+In the [exporter] / [importer] part, you are free to do whatever you want, but
+you need to dump / import your data from $${directory:backup} and specify a
+wrapper. I suggest you only add options and specify your export/import recipe.
+
+
+
+-----------------------------------------------------------------------------------------
+
+Finally, instance-mysoftware-import.cfg.in and
+instance-mysoftware-export.cfg.in need to be downloaded and accessible by
+switch_softwaretype, and you need to extend stack/resilient/buildout.cfg and
+stack/resilient/switchsoftware.cfg to download the whole resiliency bundle.
+
+Here is how it's done in the mariadb case for the lamp stack:
+
+
+
+ ** buildout.cfg **
+
+extends =
+   ../resilient/buildout.cfg
+
+[instance-mariadb-import]
+recipe = slapos.recipe.template
+url = ${:_profile_base_location_}/mariadb/instance-mariadb-import.cfg.in
+output = ${buildout:directory}/instance-mariadb-import.cfg
+md5sum = ...
+mode = 0644
+
+[instance-mariadb-export]
+recipe = slapos.recipe.template
+url = ${:_profile_base_location_}/mariadb/instance-mariadb-export.cfg.in
+output = ${buildout:directory}/instance-mariadb-export.cfg
+md5sum = ...
+mode = 0644
+
+
+
+ ** instance.cfg.in **
+
+extends =
+  ../resilient/switchsoftware.cfg
+
+[switch-softwaretype]
+...
+mariadb = ${instance-mariadb:output}
+mariadb-import = ${instance-mariadb-import:output}
+mariadb-export = ${instance-mariadb-export:output}
+...
+
+
+
+Then, in the .cfg file where you want to instantiate your software, you can do, instead of requesting your software
+
+ * template-resilient.cfg.in *
+
+[buildout]
+...
+parts +=
+  {{ parts.replicate("Name","3") }}
+  ...
+
+[...]
+...
+[ArgLeader]
+...
+
+[ArgBackup]
+...
+
+{{ replicated.replicate("Name", "3",
+                        "mysoftware-export", "mysoftware-import",
+                        "ArgLeader","ArgBackup") }}
+
+and it'll expend into the sections require to request Name0, Name1 and Name2,
+backuped and resilient. The leader will expend the section [ArgLeader], backups
+will expend [ArgBackup]. If you don't need to specify any options, you can
+omit the last two arguments in replicate().
+
+Since you will compile your template with jinja2, there should be no $${},
+because it is not yet possible to use jinja2 -> buildout template.
+
+To compile with jinja2, see jinja2's recipe.
+
+