Role-Scope.md

@@ -8,7 +8,7 @@ name | type | value validity rule
 `config` | `<dict{$software_name:<dict>}>` | software name fields providing data for configuring that software
 
 > [!NOTE]
-> These variables' values should be defined in either a `main.yml` under the `bootstrap` role's `vars` directory, or in an arbitrarily named YAML file under a `main` subdirectory of the `bootstrap` role's `vars` directory. In fact, the latter is preferred, with the filename being `software.yml`.
+> These variables' values should be defined in either a `main.yml` under the `bootstrap` role's `vars` directory, or in an arbitrarily named YAML file under a `main` subdirectory of the `bootstrap` role's `vars` directory. In fact, the latter is preferred, with the filename being `software.yml`. I.e., `$SKATO_ANSIBLE_ROOT/roles/bootstrap/vars/main/software.yml`.
 
 ## `software`
 
@@ -56,7 +56,7 @@ This `snaps` key or field of `software` takes in a dictionary comprised of the f
 
 key | value type | purpose
 ---|---|---
-`$corresponding_handler_name` | `<dict{<str>:<dict>}>`| determines the package to be installed by the VPS's package manager
+`$corresponding_handler_name` | `<dict{<str>:<str\|list>}>`| determines the package to be installed by the VPS's package manager
 
 The dictionary taken by `$corresponding_handler_name` has the following keys/fields:
 
@@ -94,7 +94,7 @@ This `links` key or field of `software` takes in a dictionary comprised of the f
 
 key | value type | purpose
 ---|---|---
-`$corresponding_handler_name` | `<dict{<str>:<dict>}>`| determines the network resource to be pulled for software building or installation on the VPS
+`$corresponding_handler_name` | `<dict{<str>:<str>}>`| determines the network resource to be pulled for software building or installation on the VPS
 
 The dictionary taken by `$corresponding_handler_name` has the following keys/fields:
 
@@ -120,5 +120,60 @@ links:
 
 ## `config`
 
-> **TBC**
-> This page of the documentation is still a work in progress. Revisit later.
+The `config` variable takes in a dictionary data type as value, wherein each entry in that dictionary represents the configuration setting of a given software or package. Each entries' key / field is the name of the handler that will be applying the value(s) to configure the software or package.
+
+key | value type | purpose
+---|---|---
+`$corresponding_handler_name` | `<dict{<str>:<dict>}>`
+
+While there are conventions for the valid fields/keys of *some* software or packages that are expected to be installed (e.g., git, proftpd, nextcloud, and aria2), there is no standardization of fields/keys for each software or package configuration.
+
+> [!NOTE]
+> Despite current lack of standardization of fields/keys for the dictionary-typed values of each of `config`'s dictionary entries, there are ongoing plans to alter this state of affairs in the future. 
+
+Consequently, it's more effective just show examples for configurations that are already in use:
+
+```yaml
+config:
+  git:
+    sys:
+      editor: nvim
+  proftpd:
+    name: "{{ hostvars[inventory_hostname].fqdn.split('.')[0] }}"
+    auth_filepaths:
+      users_path: "/etc/proftpd/ftpd.passwd"
+      groups_path: "/etc/proftpd/ftpd.group"
+    msg:
+      welcome: "Hi hi~!"  
+    vusers:
+      webmaster:
+        username: "webmaster"
+        id_of: "{{ ['caddy', 'www-data'][0] }}"
+        gid_of: "{{ ['caddy', 'www-data'][0] }}"
+        password: "h@ckmyFtp"
+        services: ["http","https"]
+      smuggler:
+        username: "smuggler"
+        id_of: "{{ hostvars[inventory_hostname]['users']['ftp']['username'] }}"
+        gid_of: "{{ hostvars[inventory_hostname]['users']['ftp']['group'] | default(hostvars[inventory_hostname]['users']['ftp']['username']) }}"
+        password: "plzH@c|<m3@ga1n"
+        services: []
+    tls_paths:
+      cert: "/usr/local/share/ca-certificates/{{ hostvars[inventory_hostname]['fqdn'] }}.crt"
+      privkey: "/usr/local/share/ca-certificates/{{ hostvars[inventory_hostname]['fqdn'] }}.key"
+  nextcloud:
+    users:
+      admin:
+        username: "admin"
+        password: "password123" # @NOTE placeholder
+    phone_region: "US"
+  aria:
+    checksum: ~
+    secret: "alkjw1h5eh6j8nl144L3JHUIJHL46Nlusx8f7h5567NNashgsafdFDPpsk"
+```
+
+When adding new, or your own, configurations for software or packages under  `config`, what's important is...:
+
+1. To make sure the name corresponds to a handler's name (as in its `listen` field) for the `bootstrap` role. 
+2. To make sure that the variables or fields/keys in the dictionary entry for that software or package's configuration under `config` are eventually made values of variables declared in or via `bootstrap`'s template files.
+   - The latter is done in the handlers in the handler file for post-install configuration of the relevant software or package. So for example, for the above example YAML code I could have `$SKATO_ANSIBLE_ROOT/roles/bootstrap/handlers/{git.yml,proftpd.yml,nextcloud.yml,aria2.yml}`, wherein each of those have a top-most block task with a `listen` key/field of, respectively: "git", "proftpd", "nextcloud", and "aria".