Update 'README.md'

README.md

@@ -4,20 +4,18 @@ Proof-of-concept meta-configuration app-connector abra wrapper.
 
 ## Advantages
 
-The following problems should be solved with this approach:
-
-- have global configuration that apply on every configuration:
-    - avoid copy pasta errors from reusing the same configuration for multiple instances
+- Have a global configuration that applies on every instance:
+    - avoid copy pasta errors
     - avoid forgetting important configurations
-- reduce manual configuration overhead for connecting multiple apps
+- Reduce manual configuration overhead for connecting multiple apps
     - exchange domains
     - share secrets
     - set specific env vars
-- have a minimal configuration file for each instance
+- Have a minimal configuration file for each instance
     - it should only contain parameters that differ from the defaults and the global configuration
-- set a global subdomain convention
+- Set a global subdomain convention
     - each app will always have the same subdomain
-- set up an instance with multiple connected apps in one run
+- Set up an instance with multiple connected apps in one run
 - Automatic updates of the env configurations 
     - avoid manual env configuration at all
 
@@ -29,9 +27,9 @@ This concept contains the following configuration files.
 Each configuration can be templated with jinja2 and global variables.
 
 1. `defaults.yml`
-    - It contains configurations for each app that are applied on each instance
-    - i.E. smtp config, language...
-    - This configuration is for the operator to avoid copy pasta errors 
+    - It contains global configurations for each app that are applied on each instance
+    - i.e. smtp config, language...
+    - This configuration is for the operator to avoid copy pasta errors and reduce manual configurations
 2. `domains.yml`
     - It contains a mapping for each app to a subdomain
     - i.e. `nextcloud: cloud.example.com`
@@ -44,36 +42,32 @@ Each configuration can be templated with jinja2 and global variables.
     - can optionally contain instance specific configurations for each app
 4. `combine.yml`
     - contains the configuration steps that are required to combine apps with each other
-        - the env variables that should be uncommented
-        - specific values for env variables
-        - secrets that should be shared with each other
-        - commands that should be executed
     - This configuration should not be touched by the operator
         - It should be either split into the recipes repositories and maintained by the recipe maintainer or it should be maintained by the alakazam maintainer
 
-### App Configuration `<app_configurations>`
+### App Configuration
 
 `defaults.yml`, `config.yml` and `combine.yml` contain a similar structure to configure the individual apps.
-For each app the following configuration steps can be used:
+For each app the following `<app_configurations>` steps can be used:
 
-- `uncomment`
+- `uncomment:`
     - uncomment each matching line
     - this is useful for env variables that are used multiple times like `COMPOSE_FILE`
-- `env`
+- `env:`
     - set the value for env variables
-- `execute`
+- `execute:`
     - `abra.sh` commands that should be executed after deployment
-- `secrets`
+- `secrets:`
     - insert a specific value into a secret
-    - if the secrets can not be generated, i.e. smtp passwords
+    - for secrets that can not be generated, i.e. smtp passwords
 
 The `combine.yml` configuration additionally contains
 
-- `shared_secrets`
+- `shared_secrets:`
      - `<source_secret_name>:<target_secret_name>`
      - a mapping to define which secrets should be shared between two apps
 
-Each configuration file can have a `GLOBALS` section, that cat be used to template the configuration with global values.
+Each configuration file can have a `GLOBALS` section, that cat be used to template the configuration with global variables.
 
 ```
 GLOBALS:
@@ -90,54 +84,54 @@ nextcloud:
 ### Configuration Structure
 
 1. `defaults.yml`
-    - there is an entry for each `<app_recipe>` that should have global configuration
-    - the `<app_configuration>` is configured according to "App Configuration" above
+    - there is an entry for each `<app_recipe>` that should have a global configuration
+    - the `<app_configuration>` is configured according to [App Configuration](#app-configuration) above
 
-```
-<app_recipe>:
-    <app_configurations>
-```
+    ```
+    <app_recipe>:
+        <app_configurations>
+    ```
 
 2. `domains.yml`
 
-```
-`<app_recipe>`: <subdomain>.example.com
-```
+    ```
+    <app_recipe>: <subdomain>.example.com
+    ```
 
 3. `config.yml`
 
-```
-domain: <instance_domain>
-server: <instance_server>
-apps:
-    <app_recipe>:
-        <app_configurations>
-```
+    ```
+    domain: <instance_domain>
+    server: <instance_server>
+    apps:
+        <app_recipe>:
+            <app_configurations>
+    ```
 
 4. `combine.yml`
-    - For each `<target_app_recipe>` there is a `<target_app_configurations>` that is only applied if the `config.yml` also contains the `<source_app_recipe>`, to combine these two apps.
+    - To combine two deployed apps each `<target_app_configurations>` of a specific `<target_app_recipe>` is only applied if the `config.yml` also contains the belonging `<source_app_recipe>`
 
-```
-<target_app_recipe>:
-    <source_app_recipe>:
-        <target_app_configurations>
-```
+    ```
+    <target_app_recipe>:
+        <source_app_recipe>:
+            <target_app_configurations>
+    ```
 
 
 ## Process
 
-Creating a new instance
+Create a new instance:
 
-1. The config.yml is created by the operator to define the domain and required apps
+1. The `config.yml` is created by the operator to define the domain and required apps
 2. `./alakazam.py init-server`
     - installs `traefik` and `backup-bot-two`
 3. `./alakazam.py setup-apps`
-    1. the env files for each app are created
-    2. the `defaults.yml` configs/secrets are applied on the env files
-    3. the `config.yml` configs/secrets are applied on the env files
-    4. the `combine.yml` configs/secrets are applied on the env files
+    1. for each app the env files are created
+    2. for each app the `defaults.yml` configs are applied on the env files and secrets are inserted
+    3. for each app the `config.yml` configs are applied on the env files and secrets are inserted
+    4. for each app the `combine.yml` configs are applied on the env files and secrets are inserted
         - the shared_secrets are generated
-        `<source_app_recipe>.example.com` is replaced according to `domains.yml` in the `<target_app` env file
+        - `<source_app_recipe>.example.com` is replaced according to `domains.yml` in the `<target_app_recipe>` env file
     5. all the remaining secrets are generated
 4. `./alakazam.py deploy-apps`
     - each app is deployed