Starting rewrite of documentation

README.md

@@ -1,66 +1,3 @@
 # 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 -->
-
-
+Automates the implementation of VPS servers for my server ecosystem. There is a specific logic and structure to this project, that will be expounded on herein.