From dca8f58da735c3fe34b54786fa4b08f8ac173888 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@iml.unibe.ch>
Date: Mon, 25 Apr 2022 18:45:11 +0200
Subject: [PATCH] update docs

---
 docs/10_Installation.md | 42 +++++++++++++++++++++++++++++++++++++++++
 docs/40_Usage.md        | 27 +++++++++++++++++++++++++-
 docs/_index.md          | 24 ++++++++++++++++++++++-
 3 files changed, 91 insertions(+), 2 deletions(-)

diff --git a/docs/10_Installation.md b/docs/10_Installation.md
index 2fc1cbe..640f63c 100644
--- a/docs/10_Installation.md
+++ b/docs/10_Installation.md
@@ -39,3 +39,45 @@ Then create a folder for log data. As root:
 ```shell
 mkdir -p /var/log/imldeployment-client/
 ```
+
+## Automation
+
+This is an example for Ansible.
+
+Execute the `deploy_app.sh [PROFILENAME]` as root.
+
+Snippet of a playbook:
+
+```yaml
+# ---------- install deployment profile
+- name: Deployment profile
+  hosts: web
+  become: yes
+  become_user: root
+  vars:
+    deploy_profile_name: my_ci_project_id
+
+  roles:
+    - iml.deployment_profile
+
+  tags:
+    - rollout
+```
+
+Snippet of the Ansible role iml.deployment_profile:
+
+```yaml
+# run deploy script
+- name: '{{ deploy_profile_name }} - run deployment client'
+  shell: | 
+    {{ CONST.imldeployment.clientdir }}/deploy_app.sh {{ deploy_profile_name }}
+  register: out_install
+  ignore_errors: yes
+
+- debug: var=out_install.stdout.split("\n")
+  when: out_install.rc > 0
+  
+- name: 'check returncode of deployment' 
+  fail: msg="ERROR - occured. See output in the debug task above."
+  when: out_install.rc > 0
+```
diff --git a/docs/40_Usage.md b/docs/40_Usage.md
index 846ebf0..6ae41b3 100644
--- a/docs/40_Usage.md
+++ b/docs/40_Usage.md
@@ -6,12 +6,37 @@
 This is the main deployment script.
 
 ```txt
-./deploy_app.sh [PROFILENAME]
+./deploy_app.sh -h
+
+
+<<<<<<<<<<##########|  IML - DEPLOYMENT SCRIPT  |##########>>>>>>>>>>
+
+HELP
+Load one or more profiles profile to deploy an application.
+If the download file is not newer then it does not extract files and does not
+run pre and post hooks - it updates the config files only and sets the owner.
+
+Syntax:
+  deploy_app.sh [OPTION] [PROFILE(S)]
+
+Optioms:
+  -h | show this help and exit
+  -f | force full installation even if the download file is not newer
+  -l | list exiting profile names
+
+Profile(s):
+  Set one or more valid profile names. By default it loops over all profiles.
+  This prameter limits the execution to the given profiles.
+  Use option -l to get a list of profiles.
+
 ```
 
 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.
 
+To start a single profile start `./deploy_app.sh -l` to get a list of exisring configured profiles
+and then `./deploy_app.sh [PROFILE]`.
+
 ## ./bin/create_config.sh
 
 The script is used to read a template (*.erb) to replace simple placeholders
diff --git a/docs/_index.md b/docs/_index.md
index 44d438a..eb9bcbd 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -1,6 +1,28 @@
 # IML deployment client
 
 This client is a set of bash scripts to deploy a package that was built on th IML CI server.
+It handles a secure download, extracts the package, generates configs.
+
+```mermaid
+graph LR
+    CI(CI deployment web gui ) --> |Build package| PkgDir 
+
+    PkgDir[Package dir]
+    PkgDir --> |rsync| Pkg1
+    PkgDir --> |rsync| Pkg2
+    PkgDir --> |rsync| Pkg3
+
+    Pkg1(CI package server 1) --> |secure download| DeployClient
+    Pkg2(CI package server N)
+    Pkg3(Puppet master)
+
+    subgraph Appserver
+    DeployClient --> |installs| ApplicationA(Application A)
+    DeployClient --> |installs| ApplicationB(Application B)
+    end
+
+```
+
 
 This project is related to
 
@@ -37,6 +59,6 @@ Tested environments:
 * Extraction to target dir
 * Cleanup: delete all files in target dir that are not included in the software package
 * Create (config) files by inserting strings into placeholders
-* Several hooks to allow custom actions
+* Several hooks to allow custom actions, eg. restart a service un changes
 * Handle multiple applications on a machine (aka profiles)
 * Writes a logfile per execution and application (and to stdout)
-- 
GitLab