Added some documentation for Ansible herein

README.md

@@ -0,0 +1,66 @@
+# SUKAATO Ansible
+
+Automates the implementation of VPS servers for the SUKAATO web domain ecosystem. There is a specific logic and structure to this project, that will be expounded on herein.
+
+## Default Groups
+
+The default inventory groups and their child groups in this Ansible project are:
+- `vps`, for virtual private servers
+    - `web`, for webservers
+    - `mail`, for email servers if separate
+- `local`, for LAN servers
+    - `stationary`
+    - `mobile`
+- `this`, for localhost servers
+
+## Assumed Host and Group Variables
+
+Inventory group variables should be placed in files or directories under `group_vars/` that have the associated group name as filename or directory name, and inventory host variables should be placed in files or directories under `host_vars/`  that have the associated hostname or fully qualified domain name as filename or directory name.
+
+More importantly, the following variables should be specified for groups or hosts:
+- `hname`: The hostname to be placed in `/etc/hosts` for the target server(s)
+- `tzone`: The timezone for the target server(s)
+- `remote`: Specifies the host or group of hosts are at public address rather than at loopback address
+- `root_auths`: A list of accounts with their authentication that are or are to be root on the target server (more details on this later)
+- `admin_auths`: A list of accounts with their authentication that have or are to have superuser privileges on the target server
+- `guest_auths`: A list of accounts that are or are to be guest accounts
+- `user_auths`: A list of accounts with their authentication that are or are to be standard/regular user accounts
+- `regular_accts`: A list combination of the last 3 list type variables--do not change this variable unless you know what you're doing
+- `user_pubkeys`: A list structured around the specific SSH keys for accounts under `regular_accts`
+- `crowdsec_key`: The enrollment key for initial set-up of crowdsec security engine; gotten from a CrowdSec online account
+- `gocrypt_password`: The password for or to be set for any and all gocryptfs vaults
+
+Because Crowdsec is installed by playbook `install@vps.yml` by default, `crowdsec_key` is also required among these. In addition, `gocrypt_password` is required as part of importing private GPG keys during the `configure@vps.yml` playbook run. This is because the GPG private key file is held inside a `gocryptfs` vault in the target server rather than deleted after import. (To disable this, edit `roles/bootstrap/tasks/configure_core/gpg.yml` appropriately.)
+
+For all aforementioned host or group variables that are account lists, as well as for `gocrypt_password` and `crowdsec_key`, it is recommended to create directories for groups and hosts that contain their variables in a file under that directory--a file called `vars`. That way, a `vault` file sharing the same parent directory can be used for storing and encrypting that sensitive authentication and user information that is then referenced by `vars`.
+
+The items in each account list represent users and have a particular syntax, exemplified by the following:
+
+```yaml
+username: ~
+actual_name: ~
+password: ~
+email: ~
+ssh_auth: ~
+```
+
+The `ssh_auth` field for the user is itself a list of public SSH keys for that user.
+
+## Custom Package Installations
+
+To install additional packages than core packages, first make sure that `install@vps.yml` playbook has playbook variable `want_extra_pkgs` set to `yes`, then edit the file at `roles/bootstrap/defaults/custom_pkgs@Debian.yml`. In that file, the syntax requires that the packages be listed under the YAML field `my_pkgs`, and it also requires that each element in the list have a `package` field while optionally a `version` field. An example of such an element would be:
+
+```yaml
+package: inspircd
+version: ~
+```
+
+## Dynamic Playbook Variables, Role Variables and Role Defaults
+
+By default, variables referenced in role tasks and role handlers--unless Ansible "magic variables" or group/host variables--are also listed as role defaults, in a file `general.yml` under the `main` subdirectory for defaults. This is to make the use of yet-undeclared variables in the role more transparent. Typically, such variables not declared or assigned in the role itself, though referenced by it, are dynamically assigned or declared within playbooks.
+
+For ease, you may prefer to simply copy-paste the variables defined in `${ROLE}/defaults/main/general.yml` of the relevant role into some file in that role's `vars` directory--likely `main.yml`. Then, in the applicable playbooks, under role inclusions in tasks you can add a `vars_from` field entry.
+
+<!-- @TODO complete README -->
+
+