Role Scope

Herein the variables at or in the inventory scope are explained further. We already have the following table from the overview:

name	type	value validity rule
`software`	`<dict{<str>:<dict>}>`	valid fields providing data for software installations
`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. I.e., $SKATO_ANSIBLE_ROOT/roles/bootstrap/vars/main/software.yml.

`software`

The software takes a dictionary value that includes the following fields/keys:

key	value type	purpose
`pkgs`	`<dict{$corresponding_handler_name:<dict>}>`	determines what packages to install that are accessible via the VPS's native package management system
`snaps`	`<dict{$corresponding_handler_name}:<dict>>`	determines what software to install that are accessible via the VPS's newly installed snapd package service
`containers`	`<dict{$corresponding_handler_name}:<dict>>`	determines what images to download from a container registry onto the VPS
`links`	`<dict{$corresponding_handler_name}:<dict>>`	determines what links to pull or download from to build given software in the VPS (e.g., a git repo link, source archive, package file, script, etc.)

Important

The key/field of each of these keys'/fields' dictionary value must be a name that corresponds to the listen name given to a handler in the bootstrap role that handles the details of the software configuration process, and that is notified after the software had been installed. Handlers in a role are found under the handlers directory of that role's directory.

Since each of these themselves take dictionary data types as their value, those having conventional/valid fields/keys, it is necessary to go through each one's dictionary field/keys separately.

`pkgs`

This pkgs key or field of software takes in a dictionary comprised of the following keys/fields:

key	value type	purpose
`$corresponding_handler_name`	`<dict{<str>:<dict>}>`	determines the package to be installed by the VPS's package manager

The dictionary taken by $corresponding_handler_name has at least a field/key of name, that itself takes in a dictionary value with field/key named after the package manager for whom the package name it takes as value applies, e.g.:

key	value type	purpose
`name`	`<dict{$package_manager_name:<str>}>`	determines the name to be searched for finding the package under the given package manager to be installed by it

Here is an example of how one would write a package entry under pkgs in software:

software:
  pkgs:
    php-lang:
      name:
        apt: "php"

`snaps`

This snaps key or field of software takes in a dictionary comprised of the following keys/fields:

key	value type	purpose
`$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:

key	value type	purpose
`name`	`<str>`	determines the name to be searched for finding the snap
`channel`	`<str>`	determines the channel the snap name is being searched in/through
`opts`	`<list[<str>]>`	determines some configuration options to set on snap installation

Important

For opts in particular, each string must have a valid syntax that corresponds to that accepted by the options field for the Ansible community.general.snap module. For more, see this.

Here is an example of how one would write a snap entry under snaps in software:

snaps:
  nextcloud:
    name: "nextcloud"
    channel: ~
    opts:
      - "nextcloud:php.memory-limit=512M"
      - "nextcloud:nextcloud.cron-interval=10m"
      - "nextcloud:http.compression=true"
      - "nextcloud:ports.http=81"

`containers`

Note

No containers' value validity rules have been declared yet, as it is highly recommended to instead use Compose files for image installation and container management. As of right now, this field or key essentially does nothing. An example Compose file can be found in this repo.

`links`

This links key or field of software takes in a dictionary comprised of the following keys/fields:

key	value type	purpose
`$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:

key	value type	purpose
`name`	`<str>`	determines the name to be conventionally used for this software
`src`	`<str>` (a URI/URL to a package file, installation script, source archive, git repo, etc.)	determines the network location of the software or software-related resource
`branch`	`<str>`(branch name or path to the preferred software version)	specifies the relevant files for the software build or installation
`version`	`<str>` (version name)	specifies the version name of the software version to be installed or built
`output`	`<str>` (path to a resulting file or name of or reference to a desired state)	determines either what the software build/installation will output, or what result to track to confirm successful build/installation

Here is an example of how one would write a link entry under links in software:

links:
  quartz:
    name: "quartz"
    src: "https://github.com/jackyzha0/quartz.git"
    branch: "v4"
    version: ~
    output: ~

`config`

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:

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...:

To make sure the name corresponds to a handler's name (as in its listen field) for the bootstrap role.
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".