update readme

readme.md

 # IML deployment client :: proof of concept :: WIP
 
-This client is a set of bash scripts to deploy a package that was built on ci server.
+This client is a set of bash scripts to deploy a package that was built on th IML CI server.
+
+This project is related to
+
+* CI deployment web gui <https://git-repo.iml.unibe.ch/iml-open-source/imldeployment>
+* CI package server <https://git-repo.iml.unibe.ch/iml-open-source/ci-pkg>
 
 ## License
 
@@ -16,26 +21,41 @@ On a server the client must be deployed i.e. in `/opt/deployment-client/`
 
 Use git clone if you feel familiar with git. Otherwise download the archive and extract it.
 
-## Set up a software package
+## Execution plan
+
+I fully configured the deployment executes the following steps
+
+* loop over profiles ... and per profile ...
+* set profile data by sourcing [profile]/config.js
+* download Software archive
+* detect if download is newer than the last one
+* jump into installation dir of your application
+* optional: execute pre installation tasks
+* optional: run cleanup
+* extract software archive
+* create config files
+* optional: execute post installation tasks
 
-### Set up access to software
+## Set up access to package server
 
 This setting is for all projects on the server. It has to be done once.
 
 * in ./bin directory copy getfile.sh.cfg.dist to getfile.sh.cfg
 * edit getfile.sh.cfg and define software endpoint and set the phase:
 
-```txt
+```bash
 IMLCI_URL=https://software.example.com
 IMLCI_PKG_SECRET=put-secret-here
 IMLCI_PHASE=preview
 ```
 
-### Set up rollout
+## Set up software rollout
+
+### Create a profile
 
 * Create a subdirectory in ./profiles/ for each rollout
 * The example subdir gives an orientation and can be copied, i.e. `cp -r example myapp`
-* create a config file named `./profiles/myapp/config.sh`
+* create a config file named `./profiles/myapp/config.sh` (copy the config.sh.dist from example profile)
 
 ```txt
 # my install dir
@@ -58,6 +78,17 @@ cleanup_preview=0
 cleanup_force=0
 ```
 
+Config variables:
+
+name            | type   | description 
+---             | ---    | ---
+installdir      | string | target directory of your application
+appowner        | string | if not empty a chown -R will be applied in target directory by `chwon -R ${appowner} ${installdir}`; appowner is the parameter behind -R. It is something like "myuser." or "myuser:mygroup". For a web application it should be the user of your webservice (www-data/ apache/ nginx). The command chown requires to run the deploy script as root.
+IMLCI_PROJECT   | string | Project id in IML CI server
+IMLCI_PHASE     | string | optional: override the global IMLCI_PHASE in ./bin/getfile.sh.cfg; it is one of preview\|stage\|live
+cleanup_preview | 0 or 1 | Cleanup preview - shows diff between downloaded TGZ and ${installdir}. 
+cleanup_force   | 0 or 1 | Run cleanup: it deletes all files in target directory that aren't in the last downloaded tgz. To keep runtime data like logs or uploads you can add a file `.keep` in the directory.
+
 Make a testrun: `./deploy_app.sh` in application root.
 It should download the software package and extract it and install it into you `${installdir}`.
 
@@ -78,22 +109,13 @@ For hooks you can create files with pre defined names. A hook script must have e
 * profiles/myapp/tasks_config.sh - replace config files (see below)
 * profiles/myapp/tasks_postinstall.sh - do postinstall actions before finishing
 
-Example:
-
-```txt
-# ----------------------------------------------------------------------
-# TASKS :: POST INSTALL ACTIONS
-# ----------------------------------------------------------------------
-hooks/ondeploy
-```
-
-### Create configs
+#### Create configs
 
 The script `./bin/create_config.sh` can read config templates and create an output file.
 
 You need to reference the template, output file and a file for replacement data.
 
-```txt
+```bash
 # ----------------------------------------------------------------------
 # TASKS :: GENERATE CONFIGS
 # ----------------------------------------------------------------------
@@ -103,3 +125,27 @@ You need to reference the template, output file and a file for replacement data.
 #               v                   v                                             v                                 v
 "${selfdir}/bin/create_config.sh"   hooks/templates/mytemplate.erb                config/target.php                 ${projectdir}/replace.txt
 ```
+
+#### Pre and post install actions
+
+Example: A simple tasks_postinstall.sh can contain the start of a script that is delivered in the tgz archive.
+
+```bash
+# ----------------------------------------------------------------------
+# TASKS :: POST INSTALL ACTIONS
+# ----------------------------------------------------------------------
+hooks/ondeploy
+```
+
+## Scripts
+
+### deploy_app.sh
+
+This is the main deployment script.
+
+```txt
+./deploy_app.sh [PROFILENAME]
+```
+
+If you start it without parameter it will loop over all existing profiles.
+You can add an existing profile name to limit the execution to that profile only.
\ No newline at end of file