Getting started

Default dotfiles

The role does not clone any dotfile git repositories defined in the yadm__dotfiles variables by default. To enable this you should set in the inventory:

yadm__dotfiles_enabled: True

Without this, users still are able to use yadm to install their own preferred dotfiles, and role ensures that commonly used CLI shells are present so that users are able to login if they use, for example, /bin/zsh as a shell defined in the LDAP directory.

The role exposes the ansible_local.yadm.dotfiles Ansible local fact, which defines an absolute path to a default dotfiles repository mirrored locally. Other Ansible roles can use it to install a default set of dotfiles using yadm on the users' account. If installation of dotfiles is disabled, or the specified repository is not present, the variable will be empty.

Unsafe Repository error handling

Due to the CVE-2022-24765 git security vulnerability, UNIX accounts cannot clone local git repositories that are not owned by themselves. This causes issues with the yadm repositories managed by the root UNIX account via the role. To mitigate that, the role will add path to the clone repository in the /etc/gitconfig configuration file to tell git that these specific repositories are safe.

Example inventory

The role is included by default in the bootstrap-ldap.yml and the common.yml playbook, therefore you don't need to do anything to enable it.

Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.yadm role:

---

- name: Configure yadm, Yet Another Dotfiles Manager
  collections: [ 'debops.debops' ]
  hosts: [ 'debops_all_hosts', 'debops_service_yadm' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::yadm' ]
      keyring__dependent_gpg_keys:
        - '{{ yadm__keyring__dependent_gpg_keys }}'

    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ yadm__apt_preferences__dependent_list }}'

    - role: yadm
      tags: [ 'role::yadm', 'skip::yadm' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::yadm

Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

Other resources

List of other useful resources related to the debops.yadm Ansible role: