Introduction

comtrya

Comtrya is a tool that is built 100% in Rust. It's goal is to allow you, as the user, to provision and configure your systems using through the use of simple configuration files in the form of YAML files or TOML files.

The goals of comtrya are as follows:

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

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 for Comtrya. 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.

Windows
macOS
Linux
FreeBSD
NetBSD

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. 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 if this is your perferred path from the Rust Website.

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. 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.0  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 your package manager. As of this time, comtrya is provided both by Arch in the AUR and Ravenports. If you are interested in packaging comtrya for another package manager, 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 go through the cargo book and have some familiarity. Outside of that, it is simply cloning our repository and building. 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. The 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>
      --no-color                                 Disable color printing
  -v...                                          Debug & tracing mode (-v, -vv)
  -h, --help                                     Print help
  -V, --version                                  Print version

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

Commands

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

comtrya help

The primary command of use will be 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 will execute and run the manifests. There are a few ways to do this.

First, point it to a directory of manifests and have comtrya execute them all.

comtrya -d ./manifests apply

As shown, this is achieved with the -d option, which tells comtrya the directory that houses the manifests to be executed.

Second, specify specific manifest(s) to be executed.

comtrya apply -m one,two,three

The -m option is used to tell comtrya the specific manifests to run. Note that the name of the manifest (i.e. one.yaml) is only the name of the manifest and does not contain any path information or file extension (.yaml). So, /manifests/one is not a valid input. So it is expected to be located in the directory of the manifests you are specifying to run.

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.

cd manifests/
comtrya apply -m one

comtrya -d manifests/one.yaml apply

Or, the third and final way is a combination of the two.

comtrya -d manifests/ apply -m one

Contexts

The contexts command is useful to see what comtrya knows about. 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

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 the 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. The action defined in a list of actions is the action for command.run, which runs the echo command, providing the argument of 'hi.' This results in something equivalent to running the following 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 a 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)

Key	Type	Optional	Description
action	string	no	`macos.default`
domain	string	no	Domain: `defaults` or `domains` or https://macos-defaults.com
key	string	no	which key to change
kind	string	no	value type
value	string	no	value