Introduction

comtrya

Comtrya is a permissively licensed Open Source tool that is built 100% in Rust. It allows you, as the user, to provision and configure your systems through the use of simple configuration files using the YAML or TOML formats.

The goals of comtrya are as follows:

Run on any operating system
Provide a simple YAML/TOML interface to, potentially, complex tasks

Comtrya's source code is available on GitHub.

Comparison to alternatives

Ansible

Ansible is a great tool task runner, but comes with a lot of modules that aren't really necessary for localhost provisioning and can be cumbersome to run individual tasks within a playbook.

SaltStack

SaltStack has been a favourite of mine (@rawkode) for many years, and while it's event system is a game changer for working with many devices - it's inability to display progress of large state runs makes it cumbersome to use for localhost provisioning.

Supported Systems

The following operating systems are officially supported by Comtrya:

FreeBSD
Linux
macOS
NetBSD
Windows

If your operating system is not listed, file an issue on the projects GitHub and the team will see what needs to be done to add support.

Installation

There are several ways to install Comtrya on a system: cargo, shell script, provided binaries, or package managers. Comtrya can also be built from source.

Cargo installation

If your system has the Rust programming language tools such as cargo installed, cargo can be used to fetch the source and build a binary on your machine, placing it in location accessible by your path environment variable. First, ensure that the Rust programming language tool is installed by running the following:

cargo --version

You should see the version of cargo installed on your system printed out. If you get an error or nothing, please get the Rust tooling from the Rust Website if you want to build from source.

Once you have cargo and rustc on your system, you can fetch the sources and build with the following command:

cargo install comtrya

Shell Script

A shell script is provided to fetch a pre-compiled comtrya binary and install it onto your system (if your operating system is supported by the script). To do this, in your terminal or command prompt, run the following line:

curl -fsSL https://get.comtrya.dev | sh

Or, optionally, you can get a specific version of comtrya using the following one-liner:

curl -fsSL https://get.comtrya.dev | VERSION=v0.9.1  sh

Precompiled-binaries

Pre-compiled binaries are also included on our GitHub repository under our releases.

Package managers

Some package managers may provide comtrya. Check with yours. At the time of writing this, comtrya is available in the Arch User Repository (AUR), Homebrew and Ravenports. If you are interested in packaging comtrya for another ports or packaging system, feel free to reach out to the team by opening an issue on our GitHub for support.

Building from source

Building from source should be a straight forward task for anyone familiar with the Rust toolchian. It is recommended that you read through the cargo book and get familiar with it. Once you are, building is a matter of simply cloning our repository and compiling it. However, it is important to note that you may need to ensure you have the development libraries for openssl installed on your system. Check with your operating system and package manager what these packages are as they can often vary in naming between different systems.

CLI

Basic usage on local manifests

Comtrya works by running a manifest or set of manifests. Following are examples of running comtrya against manifests that are on the local machine:

# Run all manifests within your current directory
comtrya apply

# Run all manifests within your current directory and a specified configuration file
comtrya -c /path/to/Comtrya/yaml

# --manifests, or -m, will run a subset of your manifests
comtrya apply -m one,two,three

# Run all manifests within a specified directory
comtrya -d ./manifests apply

Please refer to the commands section for more information about the usage of apply.

Basic usage on remote manifests

Comtrya also has the ability to run remote manifests, normally hosted in a git repository on github.

# Manifests in a Git repository
comtrya -d https://github.com/rawkode/rawkode apply

# Manifests in a Git repository with a branch and path
comtrya -d https://github.com/rawkode/rawkode#main:dotfiles apply

# Manifests in a Git repository with a branch and path and a subset selector
comtrya -d https://github.com/rawkode/rawkode#main:dotfiles apply -m dev.git

Comtrya provides a help menu that can be shown by running the following command in your terminal:

comtrya -h

A tool to simplify reprovisioning a fresh OS. Installs packages and manages dotfiles.

Usage: comtrya [OPTIONS] <COMMAND>

Commands:
  apply            Apply manifests
  status           List manifests status (ALPHA)
  version          Print version information
  contexts         List available contexts
  gen-completions  Auto generate completions
  help             Print this message or the help of the given subcommand(s)

Options:
  -d, --manifest-directory <MANIFEST_DIRECTORY>

  -c, --config-path <CONFIG_PATH>
          Specify a configuration path (if invalid Comtrya will exit)
      --no-color
          Disable color printing
  -D, --defines <DEFINES>

  -v...
          Debug & tracing mode (-v, -vv)
  -h, --help
          Print help
  -V, --version
          Print versionA tool to simplify reprovisioning a fresh OS. Installs packages and manages dotfiles.

Auto generate completions

Shell completions for comtrya can be generated by the desired shell via gen-completions subcommand.

comtrya gen-completions [SHELL]

for bash:

source <(comtrya gen-completions bash)

for fish:

comtrya gen-completions fish | source

Define variables via CLI

Comtrya offers the ability to set variables to use throughout manifests. Variables have normally been defined via the Comtrya config file named Comtrya.yaml at the root directory of the manifests. However, variables can also be defined in the command line interface by using the defines options.

comtrya -v -d ./ --defines foo=bar apply -m sample

In the sample, a variable is created in comtrya with the name foo and is set to the value bar. An action, like the sample below, can utilize this variable.

- action: command.run
  command: echo
  args:
    - "{{ variables.foo }}"

Commands

Comtrya offers several commands for use. They can be listed in the terminal by running comtrya with the help command.

comtrya help

The most frequently used command s the apply command, which will apply the actions of provided manifests to the system.

Available Commands

Command	Description
apply	Apply manifests
status	List manifest status
version	Print version information
contexts	List available contexts
gen-completions	Auto generate completions
help	Print out help information for using comtrya

Apply

The apply command executes and runs the manifests. There are a few ways to do this.

The first option is to point comtrya to a directory of manifests and have it execute them all:

comtrya -d ./manifests apply

As shown, this is done with the -d option, which tells comtrya the directory that contains the manifests to be applied.

The second option is to specify specific manifest(s) to be executed:

comtrya apply -m one,two,three

The -m option is used to let comtrya know which manifests to apply. Note that the name of the manifest (i.e. one.yaml) is only the name and must not contain any path information or file extension (.yaml). So, /manifests/one is not a valid input. Any manifests are expected to be located in the directory of the manifests you specified.

Suppose you have a directory manifests/ that contains the manifests one.yaml and two.yaml. You want to only execute one.yaml. There are three ways to achieve this. You can simply specify the manifest if it's in the current working directory:

cd manifests/
comtrya apply -m one

Or you can specify the directory:

comtrya -d manifests/one.yaml apply

Alternatively a combination of the two is possible as well:

comtrya -d manifests/ apply -m one

Contexts

The contexts command is useful to see what comtrya knows about your system. This can be environment variables, included variables, information about the OS, user information and other variables. Below is an exmaple of the output.

env
 COLORTERM     DBUS_SESSION  DESKTOP_SES  DISPLAY      DOTNET_BUND  GDMSESSION
               _BUS_ADDRESS  SION                      LE_EXTRACT_
                                                       BASE_DIR
 GNOME_DESKTO  GNOME_SHELL_  GNOME_TERMI  GNOME_TERMI  GPG_AGENT_I  GTK_IM_MODU
 P_SESSION_ID  SESSION_MODE  NAL_SCREEN   NAL_SERVICE  NFO          LE
 GTK_MODULES   HOME          LANG         LESSCLOSE    LESSOPEN     LOGNAME
 LS_COLORS     NVM_BIN       NVM_CD_FLAG  NVM_DIR      NVM_INC      OLDPWD
                             S
 PATH          PWD           QT_ACCESSIB  QT_IM_MODUL  SESSION_MAN  SHELL
                             ILITY        E            AGER
 SHLVL         SSH_AGENT_LA  SSH_AUTH_SO  SWIFTLY_BIN  SWIFTLY_HOM  SYSTEMD_EXE
               UNCHER        CK           _DIR         E_DIR        C_PID
 TERM          TEXTDOMAIN    USER         USERNAME     VTE_VERSION  WINDOWPATH
 XAUTHORITY    XDG_CONFIG_D  XDG_CURRENT  XDG_DATA_DI  XDG_MENU_PR  XDG_RUNTIME
               IRS           _DESKTOP     RS           EFIX         _DIR
 XDG_SESSION_  XDG_SESSION_  XDG_SESSION  XMODIFIERS   _
 CLASS         DESKTOP       _TYPE

include_variables
 <empty>

os
 bitness
 codename
 distribution
 edition
 family
 hostname
 name
 version

user
 config_dir
 data_dir
 data_local_dir
 document_dir
 home_dir
 id
 name
 username

variables
 <empty>

You can also view the values that these contexts have by passing in a show-values option as demonstrated below:

comtrya contexts --show-values

Status

The status command provides an overview of manifests.

Manifest	Count of Actions
kubectl.krew	3
kubectl.kubesess	3
kdash.kdash	1

Manifests

Comtrya provisions systems and performs configuration using a single or set of manifest files. These files are defined in either YAML or TOML syntax. Each manifest files is composed of actions and dependencies. To break it down even further, each action is defined as an atom or a set of atoms. An action can be something as simple as echoing text out on a terminal.

A dependency defines a relationship between manifests and actions. For instance, in order to configure neovim on a new system that is being provisioned, we might first want comtrya to ensure that neovim is installed. So we may define a dependency on an action to use the system's native package manager to install neovim before placing any configuration files we need for neovim.

Example of a YAML manifest

actions:
  - action: command.run
    command: echo
    args:
      - hi

Example of TOML manifest

[[actions]]
action = "command.run"
command = "echo"
args = [ "hi" ]

Actions

As mentioned under manifests, actions are used to dictate an action that needs to be done to configuration a system. The following is an example of a simple action:

actions:
  # Action ID can be command.run or cmd.run
  - action: command.run
    command: echo
    args:
      - hi

The above does the following: It defines a list of actions (with only one element). The action defined is the for command.run, which in this case runs the echo command, providing the argument of 'hi.' The result is something equivalent to running the following command line on a Unix-based system:

echo hi

Groups of actions provided

Comtrya provides multiple actions which are broken down into groups with the actions being apart of a larger group:

Git actions are not avaible for 0.8.8 through 0.9.0, see action documentation for me information

Binary

binary.github

binary.github

This action will grab a binary from GitHub and place it in the target directory.

Key	Type	Optional	Description
action	string	no	binary.github
name	string	no	name of binary locally after download
directory	string	no	directory to save the binary locally
repository	string	no	Github repository
version	string	no	version/tag name

Key	Type	Optional	Description
action	string	no	`file.copy`
from	string	no	source file
to	string	no	destination file
template	boolean	yes	renders files using context providers
			default: `false`
chmod	integer	yes	octal permissions
owned_by_user	string	yes	user for chown
owned_by_group	string	yes	group for chown

Key	Type	Optional	Description
action	string	no	`file.link`
from	string	no	symlink location
to	string	no	symlink points to
walk dir	boolean	yes	Walk diles in directory
			default: `false`
source	string	yes	Used in conjunction with walk dir
			in liue of `from`

Key	Type	Optional	Description
action	string	no	`file.unarchive`
from	string	no	full path to archive
to	string	no	destination of unarchived contents
force	bool	yes	force the unarchiving (defaults true)

Provider	OS
pacman/yay	Arch
paru	Arch
apt	Debian/Ubuntu
pkg	FreeBSD
pkgin	NetBSD (Multiple)
brew	macOS
winget	Windows
xbps	Void Linux
zypper	OpenSUSE
macports	macOS
dnf	Fedora
snapcraft	Linux