fix: edited typos and added more exposition for the role scope section

README.md

@@ -1,25 +1,35 @@
 # SUKAATO Ansible
 
-This repository is for automating the management of the configuration of, and the provisioning of software for, my virtual private servers using [Ansible](https://www.redhat.com/en/ansible-collaborative?intcmp=7015Y000003t7aWQAQ). This repository is especially useful for setting up the virtual private server(s) that is(/are) to host and serve my website(s). It is also meant to be useful for provisioning of software and the configuration of that software for personal or household LAN computers.
+This repository is for automating the management of the configuration of, and the provisioning of software for, my virtual private servers using [Ansible](https://www.redhat.com/en/ansible-collaborative?intcmp=7015Y000003t7aWQAQ). It's main purpose is to spin up the VPSs, create initial users and groups, import SSH or GPG keys, lock down SSH accessor harden SSH, and then install and configure packages available to the given package manager of the operating system. The `bootstrap` role in here serves to abstract some of these tasks for our main playbook files.
 
-## Installation and Use
+## Variable Names and Their Scopes
 
-All files with file extension `.example` must be converted to [YAML](https://yaml.org/) files that follow their semantics and naming (or follow the minimum bare "namespace" nesting for dictionaries or lists thereof) *prior* to executing any given [play or task](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html). For more on semantics and naming conventions see the [mini-documentation](#mini-documentation).
+To be able to make use of the Ansible playbooks, it is necessary to specify some variables in or at relevant scopes, though some may have some defaults. The relevant scopes variables are defined in, for our purposes, are:
 
-> [!IMPORTANT]
+- Ansible **inventory scope**: corresponds to variables inside per-hostname files in `group_vars` or `host_vars` directories, or the inventory file itself, i.e. `hosts.ini` or `hosts.yml`. The inventory file has some enforced naming conventions to be covered later or elsewhere.
-> Keep in mind files with the `.example` extension may also be present recursively under given [role](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html) directories (i.e., under path `${SUKAATO_ANSIBLE_PROJECT}/.ansible/roles/**/**/`).
+- Ansible **role scope**: corresponds to variables found in files inside the `defaults` / `vars` directory in a role directory, or variables found in files inside subdirectory `main` in either `defaults` or `vars` directory of that role directory. There are favored conventional directory structure within which these variables are specified in the aforementioned directories, to be covered later or elsewhere.
 
-## Mini-Documentation
+### Inventory Scope
 
-### Available Roles
+Herein are listed the relevant variables at or in the *inventory* scope. These must be specified for a specific inventory host or group, typically in their corresponding files under `group_vars` or `host_vars`. Some variables must take in a dictionary type to be valid. To save space, there will be more detail on what keys are required or optional for such dictionaries elsewhere and not here.
 
-To surmise, the available or planned [roles](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html) are as follows (and are all found under `${SUKAATO_ANSIBLE_PROJECT}/.ansible/roles`):
+name | type | value validity rule | default value | required?
+---|---|---|---|---
+`fqdn` | `\<str\>` | fully qualified domain name | none | true
+`vps_service` | `\<dict{\<str\>:<str\|bool\|list\>}\>` | valid fields providing data for spinning up new VPS | none | true
+`groups` | `\<dict{$group_name:\<dict\>}\>` | fields/keys that are group names with data configuring that group | none | true
+`users` | `\<dict{$user_name:\<dict\>}\>` | fields/keys that are user names with data configuring that user | none | true
+`keywords` | `\<list[\<str\>]\>` | strings that describe the VPS, useful for applying tags if allowed by API | none | false
+`custom_vars` | `\<dict{\<str\>:\<any\>}\>` | your own custom variables, though there are some reserved variable names for this namespace | none | true (hence the reserved variable names)
 
-role name | purpose
+## Role Scope
----|---
+
-lockdown | creating initial `sudo`-capable user, disabling system/SSH root login, setting up key-based SSH authentication, transferring GPG keys, configuring environment, hardening system
+Herein are listed the relevant variables at or in the *role* scope. These must be specified for a set of role tasks expected to run in a playbook for the host specified for its play. Some variables must take in a dictionary type to be valid. To save space, there will be more detail on what keys are required or optional for such dictionaries elsewhere and not here.
-bootstrap | installing programming language and server/container packages, installing extra system managers and essential utilities, configuring and running servers/services/containers
+
-postinstall | installing and configuring custom sets of packages, largely non-server related and not essential
+name | type | value validity rule | default value | required?
+---|---|---|---|---
+`software` | `\<dict{\<str\>:\<dict\>}\>` | valid fields providing data for software installations | none | false
+`config` | `\<dict{$software_name:\<dict\>}\>` | software name fields providing data for configuring that software | none | false
 
 > **TBC**
-> This README is yet unfinished. Check back later.
+> This README is yet unfinished and unverified. Check back later.

roles/bootstrap/handlers/nextcloud.yml

@@ -17,10 +17,6 @@
     # @TODO see if setting below is necessary given use of reverse proxy
     - name: Set trusted domains
       block:
-        - name: Set localhost as trusted domain
-          ansible.builtin.command:
-            cmd: "/snap/bin//snap/bin/nextcloud.occ config:system:set trusted_domains 0 --value='localhost'"
-        # @TODO see if setting below is necessary given use of reverse proxy
         - name: Set FQDN as trusted domain
           ansible.builtin.command:
             cmd: "/snap/bin//snap/bin/nextcloud.occ config:system:set trusted_domains 1 --value='cloud.{{ hostvars[inventory_hostname].fqdn }}'"
@@ -28,6 +24,7 @@
     - name: Set trusted reverse proxy addresses
       block:
         - name: Set trusted reverse proxy IPv4 address based on hostname
+          # @TODO create config.trusted_revproxy_ips data structure in bootstrap role's vars dir--may include loopback addresses
           when: config.trusted_revproxy_ips.ipv4 is None or len(config.trusted_revproxy_ips.ipv4) < 1
           ansible.builtin.command:
             argv:
@@ -65,4 +62,44 @@
           loop: "{{ config.trusted_revproxy_ips.ipv6 }}"
           loop_control:
             index_var: idx
+    # @TODO create task based on shell command `sudo /snap/bin/nextcloud.occ config:system:set default_phone_region --value="US"`
+    - name: Set default phone region
+      ansible.builtin.command:
+        argv:
+          - /snap/bin/nextcloud.occ
+          - "config:system:set"
+          - default_phone_region
+          - "--value={{ config.nextcloud.phone_region }}"
+    # @TODO create task based on shell command:
+    #   `sudo /snap/bin/nextcloud.occ config:system:set overwrite.cli.url --value="https://cloud.{{ fqdn }}"` for Caddy task
+    - name: Set overwrite CLI URL
+      ansible.builtin.command:
+        argv:
+          - /snap/bin/nextcloud.occ
+          - "config:system:set"
+          - overwrite.cli.url
+          - "--value=cloud.{{ hostvars[inventory_hostname].fqdn }}"
+    # @TODO create task based on shell command `sudo /snap/bin/nextcloud.occ config:system:set overwriteprotocol --value="https"` for Caddy task
+    - name: Overwrite protocol
+      ansible.builtin.command:
+        argv:
+          - /snap/bin/nextcloud.occ
+          - "config:system:set"
+          - overwriteprotocol
+          - --value="https"
     # @TODO create system-level bash alias for `/snap/bin/nextcloud.occ` command
+    - name: Get Nextcloud snap binaries
+      ansible.builtin.find:
+        paths:
+          - /snap/bin
+        patterns:
+          - nextcloud\..*
+        recurse: false
+        use_regex: true
+      register: nextcloud_snap_binaries
+    - name: Create symbolic links for Nextcloud snap binaries
+      ansible.builtin.file:
+        dest: "/usr/sbin/{{ item.path | basename }}"
+        src: "{{ item.path }}"
+        state: link
+      loop: "{{ nextcloud_snap_binaries.files }}"

roles/bootstrap/handlers/podman.yml

@@ -1,13 +0,0 @@
-# SPDX-License-Identifier: MIT-0
----
-# handlers file for bootstrap
-- name: Pull podman images
-  listen: rsync
-  block:
-    - name: Pull container images via podman
-      containers.podman.podman_image:
-        name: "{{ item.value['name'] }}"
-        tag: "{{ item.value['tag'] | default('latest') }}"
-        state: present
-      notify: "{{ item.key }}"
-      loop: "{{ lookup('ansible.builtin.dict', software.containers) }}"

roles/bootstrap/meta/main.yml

@@ -1,12 +1,9 @@
-#SPDX-License-Identifier: MIT-0
+# SPDX-License-Identifier: MIT-0
 galaxy_info:
-  author: your name
+  author: Alex Tavarez
-  description: your role description
+  description: A role that aids in the deployment and bootstrapping of a new VPS.
-  company: your company (optional)
+  company: SUKAATO
-
+  issue_tracker_url: https://git.sukaato.moe/admin/skato-ansible/issues
-  # If the issue tracker for your role is not on github, uncomment the
-  # next line and provide a value
-  # issue_tracker_url: http://example.com/issue/tracker
 
   # Choose a valid license ID from https://spdx.org - some suggested licenses:
   # - BSD-3-Clause (default)
@@ -16,20 +13,13 @@ galaxy_info:
   # - Apache-2.0
   # - CC-BY-4.0
   license: license (GPL-2.0-or-later, MIT, etc)
+  min_ansible_version: "2.1"
+  galaxy_tags:
+    - sukaato
+    - vps
+    - server
+    - web
 
-  min_ansible_version: 2.1
+dependencies:
-
+  - community.general
-  # If this a Container Enabled role, provide the minimum Ansible Container version.
+  # - containers.podman
-  # min_ansible_container_version:
-
-  galaxy_tags: []
-    # List tags for your role here, one per line. A tag is a keyword that describes
-    # and categorizes the role. Users find roles by searching for tags. Be sure to
-    # remove the '[]' above, if you add tags to this list.
-    #
-    # NOTE: A tag is limited to a single word comprised of alphanumeric characters.
-    #       Maximum 20 tags per role.
-
-dependencies: []
-  # List your role dependencies here, one per line. Be sure to remove the '[]' above,
-  # if you add dependencies to this list.

roles/bootstrap/templates/systemd/user/aria2cd.service.j2

@@ -0,0 +1,13 @@
+[Unit]
+Description=aria2 Daemon
+After=network.target
+
+[Service]
+Type=forking
+ExecStart=/usr/bin/aria2c --conf-path={{ ansible_facts['user_dir'] }}/.config/aria2/aria2.conf
+ExecReload=/usr/bin/kill -HUP $MAINPID
+RestartSec=1min
+Restart=on-failure
+
+[Install]
+WantedBy=default.target

roles/bootstrap/vars/main/software.yml

@@ -193,13 +193,14 @@ software:
     proftpd-mod-crypto:
       name:
         apt: proftpd-mod-crypto
-    # proftpd-mod-ldap:
+    # @TODO write configuration files and handler for below two package installations
-    #   name:
+    #    based on: 
-    #     apt: proftpd-mod-ldap
+    clamav:
-    # @TODO manually install the commented below on current active new VPS, then uncomment
+      name:
-    # proftpd-mod-clamav:
+        apt: clamav
-    #   name:
+    clamd:
-    #     apt: proftpd-mod-clamav
+      name:
+        apt: clamav-daemon
     proftpd:
       name:
         apt: proftpd
@@ -211,7 +212,7 @@ software:
         apt: rsync
     # rclone:
     #   name:
-    #     apt: rsync 
+    #     apt: rclone
     aria:
       name:
         apt: aria2 
@@ -235,10 +236,6 @@ software:
         - "nextcloud:ports.http=81"
         # @TODO see how to set these options: https://help.nextcloud.com/t/how-to-configure-nextcloud-snap/216036#p-649442-trusted-domains-configuration-8
         # @TODO see how to set these options: https://help.nextcloud.com/t/how-to-configure-nextcloud-snap/216036#p-649442-trusted-proxy-configuration-9
-  containers:
-    ariang:
-      name: https://docker.io/p3terx/ariang
-      tag: latest
   links:
     quartz:
       name: quartz
@@ -293,6 +290,7 @@ config:
         username: admin
         # @TODO change this password to ansible-vaulted actual choice password later
         password: password123 # @NOTE placeholder
+    phone_region: US
   aria:
     checksum: ~
     secret: ~

tasks.org

@@ -3,6 +3,7 @@
 #+language: en
 
 * PLANNED
+** TODO [#A] Write documentation on the expected conventional names to be used in the inventory file
 ** TODO [#A] Rewrite dot notation usage of keys for accessing values in custom dictionary variables to bracket notation usage of keys across whole project
 
 * IN PROGRESS