Cheat Sheet

Terminology

target: The node materia is running on

repository: A local directory or Git repository containing Materia components,manifests, and resources.

manifest: A TOML file containing metadata. Found at the repository level and the component level.

component: A collection of resources. Similar to an ansible role and is the basic building block of a repository.

resource: An individual file that is installed as part of a component and removed when the component is removed. Includes quadlets, data files, non-generated systemd units, scripts, and more.

attribute: A variable in a templated Materia resource.

plan: The series of steps Materia will take to get the target node to the state specified in the repository.

execution: The act of Materia actually installing a resource to a target. For non-templated resources this is a straight file copy. For templated resources, this involves treating it as a Go template.

Default locations

Root

Base prefix for materia data: /var/lib/materia

Target’s local copy of source repository: /var/lib/materia/source

Quadlet files (.container,.volume,etc): /etc/containers/systemd/COMPONENT_NAME/

Data files for components: /var/lib/materia/components/COMPONENT_NAME

Materia generated files: /var/lib/materia/output

Local copies of Remote Components: /var/lib/materia/remote

The following resources types are installed to the specified locations as well as the Data file location

Script resources: /usr/local/bin/

Systemd unit files: /etc/systemd/system/

Rootless

Assuming username is user. Materia will use XDG_DIR locations by default, even if the environmental variables are not set. This can be overridden.

Base prefix for materia data: $XDG_DATA_HOME/materia

Target’s local copy of source repository: $XDG_DATA_HOME/materia/source

Quadlet files (.container,.volume,etc): /etc/containers/systemd/COMPONENT_NAME/

Data files for components: $XDG_DATA_HOME/materia/components/COMPONENT_NAME

Materia generated files: $XDG_DATA_HOME/materia/output

Local copies of Remote Components: $XDG_DATA_HOME/materia/remote

The following resources types are installed to the specified locations as well as the Data file location

Script resources: $HOME/.local/bin

Systemd unit files: $XDG_CONFIG_HOME/containers/systemd/

Materia high-level overview

  1. Sync copy of source repo on target host (e.g. git pull in /var/lib/materia/source )
  2. Determine what components are assigned to the target
  3. Mark all installed components that are no longer assigned to the target for removal
  4. For all components that are assigned to the target and already installed, check for any added or removed resources
  5. For any resource that exists in both the source cache and the target host, check for any differences, templating if necessary.
  6. Generate plan of installing/removing/updating resources and components.
  7. If any components are changed, schedule a systemctl daemon-reload
  8. Determine what services need to be stoped/started/restarted.
  9. Start execution.
  10. In alphabetical order, add/remove/update components.
  11. If any components with setup/cleanup scripts are installed/removed, run those scripts.
  12. Modify services as calculated in step 8.
  13. Wait for services to start/stop