MATERIA-TEMPLATES

Author

stryan

Published

October 1, 2026

Name

materia-templates - Variables, functions, and snippets accessible within Materia template execution

Description

Materia uses the standard Go templating engine for executing resources that end in the .gotmpl file type.

To access a attribute within a templated resource, use the standard Go Template method of accessing variables: { .containerTag } will resolve to the containerTag attribute.

Besides normal attributes insertion, Materia also supports macros and snippets.

Macros

Macros are privileged functions available to Materia while executing a resource. They are not user-modifiable.

Macros are accessed the same way as any other Go Template function: { macro_name }.

Macros with arguments should have the arguments passed in quotes.

Macro List

m_dataDir “component_name”

Other variants: m_quadletDir, m_scriptsDir, m_serviceDir, m_outputDir.

Reference the components data directory. Often used for templating bind mounts

Example: Volume={{ m_dataDir "component" }}/config.yaml:/config.yaml will be templated as Volume=/var/lib/materia/components/component/config.yaml:/config.yaml

m_facts “fact_name”

Lookup a fact about the host.

The following facts are available: host.hostname: The hosts reported (not configured in Materia) hostname host.interfaces: All network interfaces on the host and their IPv4/IPv6 addresses materia.hostname: The configured hostname, if any materia.roles: What roles the host has materia.assigned_components: What components are assigned to the host materia.installed_components: What components are already installed materia.last_revision: The last source revision used in an update operation materia.last_run: When the last update opperation occured materia.last_run_successful Whether the last update operation was successful.

Example: PublishPort={{ m_facts "host.interfaces.tailscale0.ip4.0" }}:{{.port}}:{{.port}} would template as PublishPort=<tailscale interface IP address>:<port attribute>:<port attribute>

m_default “attribute” “value”

Return a attribute’s value or the provided value if the attribute is not defined

exists “attribute”

Returns true if the attribute is defined, otherwise false

snippet “snippet_name” “argument”

Special macro, see the Snippets section below

secretEnv “attribute name” “TARGET (OPTIONAL)”

Access a Materia attribute that is specified as a podman secret in the component manifest. The “attribute name” should be as specified in the secrets = ["attribute_name"]. Optionally, provide the target as defined in the Podman manual

secretMount “secret name” “ARGS (OPTIONAL)”

Same as secretEnv but accesses the secret as a file mount. Optionally, provide additional arguments as defined in the Podman manual

isRoot

Returns true if materia is running in rootful mode.

Snippets

Snippets are pre-made blocks of templated text that can be inserted with the snippet macro. Some come with materia, while others are defined in a component manifest or Repository manifest.

Snippets are not designed for highly-dynamic text, but can take one value as an argument.

Snippets are an experimental feature