DEBOPS.YADM(5)

NAME
debops.yadm - Manage yadm, Yet Another Dotfiles Manager

SYNOPSIS

debops service/yadm [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Yet Another Dotfiles Manager <https://yadm.io/> (yadm) is a wrapper script around the git command that manages dotfiles <https://en.wikipedia.org/wiki/Hidden_file_and_hidden_directory> located in the $HOME directory using a git repository. yadm supports encrypted storage for sensitive files, alternative file selection based on host class/OS/hostname/user account, bootstrap script and Jinja templating.

The debops.yadm Ansible role will install the yadm script, either from an APT repository, or using the upstream git repository. The role will also install a zsh shell and a few essential CLI applications.

Optionally, debops.yadm role can clone selected dotfiles git repositories to the host creating mirrors, that can be used by users or other Ansible roles to deploy dotfiles locally.

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.

  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', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  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:

•   Manual pages: yadm(1) <https://manpages.debian.org/yadm(1)>

•   The yadm homepage <https://yadm.io/> with documentation and examples

•   An unofficial guide to dotfiles on GitHub <https://dotfiles.github.io/>

•   A curated list of dotfiles resources <https://github.com/webpro/awesome-dotfiles>

DEFAULT VARIABLE DETAILS

Some of debops.yadm default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  yadm__dotfiles

The yadm__*_dotfiles variables define a list of custom dotfile git repositories to clone to the host, so that they are available locally. The dotfiles will be cloned to the directory defined by the yadm__dotfiles_root variable, with subdirectories corresponding to the repository host (for example github.com), repository owner (for example drybjed), and finally the dotfiles.git directory, which contains a bare git repository itself.

The repositories are cloned and/or updated using the root account, with optional GPG signature verification. The role does not execute any code contained in the repositories at this stage. Users are then able to use the yadm script to install or update their desired dotfiles from the local mirror instead of the remote repository. This can be done either manually, or via other Ansible roles.

Because yadm uses the $HOME directory directly as the git work directory, it's best to avoid putting non-dotfile files like README.md and similar in the master branch of the repository (yadm will check it out by default). If you want to present a README file in the dotfiles repository, you can put it on a separate git branch and set it as default branch in the GitHub repository settings.

See yadm dotfile repository examples <https://yadm.io/docs/examples> for an example repositories compatible with yadm script.

  Examples

Clone dotfiles without any GPG signature verification:

yadm__dotfiles:
  - name: 'user'
    git:
      - repo: 'https://github.com/user/dotfiles'

Disable the default drybjed dotfiles from being cloned automatically and remove them if they are present:

yadm__dotfiles:
  - name: 'drybjed'
    state: 'absent'

  Syntax

The variables are YAML lists, each list entry is a YAML dictionary that uses specific parameters:

name
    Required. A name of a given dotfile entry, not used otherwise. Entries with the same name parameter are merged together, this can be used to modify existing entries later on.

state
    Optional. If not specified or present, a given dotfile repository will be cloned or updated by the role. If absent, a given repository and GPG keys will be removed from the host, or will not be imported and cloned. If ignore, a given configuration entry will be ignored during evaluation by the role.

gpg Optional. A string containing a GPG key fingerprint used to sign the commits and/or tags in the dotfile repository; you can also specify multiple GPG fingerprints as a YAML list. Spaces in the fingerprint will be automatically removed. An alternative format is a YAML dictionary for each list element, with specific parameters:

id  The GPG key fingerprint.

keybase
    Optional. The name of the Keybase <https://keybase.io/> profile which should be used to lookup the GPG key.

state
    Optional, either present (import the GPG key) or absent (remove the GPG key from the keyring).

    The specified GPG keys will be added to the root GPG keyring in the ~/.gnupg/pubring.gpg file and subsequently used to verify commits in cloned or updated git repositories.

    The GPG keys are managed via the debops.keyring Ansible role, see its documentation for more details.

git Optional. A string containing an URL to the git repository with dotfiles; you can also specify multiple URLs as a YAML list. Only public repositories accessible via https:// make sense - the role does not support cloning private repositories using a password, or repositories accessible over SSH connection. An alternative format is a YAML dictionary for each list element, with specific parameters:

repo
    The URL of the repository.

version
    The git branch/tag to checkout - not useful because the role will clone bare git repositories without checking them out.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others