MATERIA-MANIFEST

Author

stryan

Published

January 1, 2026

Name

materia-manifest - metadata file for materia repos and components

Synopsis

<materia_repo>/MANIFEST.toml,<component_directory>/MANIFEST.toml

Description

A TOML config file that sits at the root of materia-repository(5) or materia component that contains metadata describing the entity.

Manifest files are required for a repository or component to be considered valid. Blank manifest files are allowed.

Repository manifests

Options

hosts

A TOML table containing hosts entries of the following format:

  [Hosts.localhost]
  Components = ["caddy","openldap"]
  Roles = ["base"]

hosts.Overrides

The table can also contain an Overrides table that contains keys mapped to component manifests. This can be used to override the MANIFEST.toml included with a component on a per-host basis. Note that this will replace entire tables; if you just want to add an element to a manifest use the Extensions table.

Example:

  [Hosts.localhost]
  Components = ["caddy","openldap"]
  [Hosts.localhost.Overrides.caddy.Defaults]
  port = "80"
  [Hosts.localhost.Overrides.caddy.Services]
  Service = "caddy.service"

This will override the Defaults and Services entries to be the above.

hosts.Extensions

The table can also contain an Extensions table that contains keys mapped to component manifests. This can be used to extend the MANIFEST.toml included with a component on a per-host basis.

Example:

  [Hosts.localhost]
  Components = ["caddy","openldap"]
  [Hosts.localhost.Extensions.caddy.Defaults]
  port = "80"

This will “extend” the caddy component’s Defaults table to have the key-value pair port = "80". If the key already exists in the table it will be updated.

roles

A TOML table of containing roles entries of the following format:

  [Roles.base]
  Components = ["nagios-agent"]

RoleCommand

(EXPERIMENTAL) An external command ran on a host to determine what role(s) it has.

Remote

A TOML table containing Remote Component entries of the following format:

  [Remote.COMPONENT_LOCAL_NAME]
  URL = "git://github.com/example/component_name"
  Version = "v1" # optional

Snippets

Experimental placeholder.

Example Manifest

[roles.base]
components = ["nagios-agent"]

[hosts.warden]
components = ["dota_patch_bot"]
roles = ["base"]

[hosts.ivy]
components = ["authelia"]

Component manifests

Options

Settings

Key-value pairs for component settings. Contains the following options:

NoRestart

By default, materia will restart services belonging to .container and .pod resources when they are updated. Set to true to disable this behaviour.

SetupScript

(EXPERIMENTAL)

A script resource to run on component installation. It will be run as a one-shot transient systemd unit after resources have been installed and the host reloaded, but before services are modified.

CleanupScript

(EXPERIMENTAL)

A script resource to run on component removal. It will be run as a one-shot transient systemd unit after services are stopped but before anything is removed.

Defaults

Key-value pairs describing default variable/attribute values for a component.

Example: defaults.containerTag = "latest"

Services

An array of service definitions, use to describe what systemd services should be started when a component is installed.

[[Services]]
Service = "SERVICE_NAME.[service|container|pod]" # The name of the systemd service or resource to modify.
RestartedBy = ["resource"] # List of resources that, if updated by a materia run, should trigger the service to be restarted
ReloadedBy = ["resource"] # List of resources that, if updated by a materia run, should trigger the service to be reloaded
Disabled = false # if true, don't enable or start this service
Static = false # Indicates whether the systemd service is generated by a Quadlet. Usually used for .timer files
Stopped = false # Prevents materia from starting the service. Useful for .build or .image services
Timeout = 0 # Default timeout in seconds for service actions involving this resource.

Scripts

A list of resources that, despite not ending in .sh, should be treated as script resources.

Snippets

Under construction. Used to indicate custom snippets. See materia-templates(5) for more details.

Secrets

A list of materia attributes that will be added to the podman secrets vault and are accessible in templates with the related macros secretMount and secretEnv.

Secrets = ["attribute1"]

Example Component Manifest

arcade-agent/MANIFEST.toml

[Defaults]
port = "5656"
containerTag = "latest"

[[services]]
Service = "arcade-agent.service"