Materia v0.7 has been released! This release contains many new features and QoL improvements, plus lays the ground work for more improvements in the future.

As always, here’s a bit of a more detailed over view of the bigger changes. If you just want the changelog, check it out here.

Rollback on failed updates

0.0.7 adds the first steps for fullly self healing quadlets. By setting the new rollback.kind setting to service in your config, materia will now detect when an update results in one or more services in the failed state and will “rollback” its local source cache to the state before the update, running a new plan-execute cycle along the way. This will also send a “Rollback initated” message to a notification webhook, if configured.

This service healthcheck occurs at two points during an update: when the service’s state is changed (i.e. when materia runs systemctl start foo.service) and at the end of the execute portion, where Materia will verify all adjusted services are in the state they should be.

Currently this only works with the git source type, but I plan for oci support to be added in a point release or two once any initial bugs are ironed out.

As some of you may have guessed from this getting its own [rollback] configuration block, I plan on expandeding this feature in the future with multiple types of rollback healthchecks, support for using this in server mode, and different rollback types, such as migrating volume state.

This has been one of the most asked about features on the roadmap.md for a while now. In fact, I think this is the only feature asked for by multiple independent people; this shows both how much people want it and the variety of ways people use Materia :)

Server mode improvements

The materia server command has been given a little refresh this update.

The biggest change is server mode now starts a Varlink-compatible server on its listening socket. This replaces the existing bespoke command setup, and was done for two reasons:

systemd is moving to Varlink as its IPC system and Materia strives to be compatible with it
Varlink makes it easy to expose the same API both locally and over HTTP with varlink-http-bridge
Having a standardized protocol should hopefully make it easier for you to automate Materia in more expansive ways.

You can use the materia agent command to try it out, or introspect the socket directly with varlinkctl.

Additionally, server mode now supports starting a /webhook endpoint for triggering materia update on command with a JSON payload. Server mode also now uses the new notify substem for sending alerts, keeping it in line with the rest of Materia

Instanced Components

Systemd supports templating service units by naming them with the format servicename@ and running them with systemctl start servicename@foo. This is useful for running multiple instances of the same server with different configurations. For example web-server@site1 and web-server@site2 use the same web-server@ unit file.

You can now use Materia components in the same way; simply assign the component to the host/role with the same component@instance format as systemd expects. Materia will then detect any name@ style resources and install them with the proper instance variable like name@instance instead, allowing them to be used as systemd instanced services.

This also applies to attribute expansion: Materia will search for both component and component@instance attributes at run time, with the latter overriding the former.

Other Changes You Should Know

Drop-in files

A little know Quadlet fact: much like with systemd services, you can override Quadlet settings by placing a quadlet.container.d/00-override.conf drop-in file next to the Quadlet file. Systemd will combine the two files together, allowing you to modify Quadlet services without editing the actual file. Materia now correctly ignores these drop-in files, allowing you to edit Quadlets in components locally without worrying about Materia overriding your changes next update. This is now officially the supported way of doing so.

Podman bindings

Materia now directly uses the Podman bindings package for its interactions with Podman. This replaces the previous method of wrapping the Podman command (done to make it eaiser to build Materia on multiple platforms) and should provide better integration in the future.

The old Podman command wrapper will stick around for a point release or two but will be removed before 0.8.

Service strictness

As part of the Rollback changes, Materia is now much stricter about checking service status at the end of an update run. You may notice more failures reported for e.g. services that start up correctly but fail soon after start.

If you see more failures or other improper states when services are starting correctly, please open a discussion or leave a message on the Matrix channel.

Changelog

- feat: Components with instanced systemd units (i.e. `unit@.service`) can now be instanced at the component level
- refactor: removed `autoUpdate` snippet, added `onBoot` and `harden` snippets.
- feat: Added `m_quadletDir`, `m_outputDir`, `m_scriptsDir`, `m_serviceDir` macros
- feat: simplified volume compression. `containers.compression_command` and `containers.compression_suffix` have been simplified into one `containers.compression` setting that can be blank, `gzip`, or `zstd`
- refactor/note: volume dump file are now in the format `volumename-volume.tar(.gz/zst)`.
- feat: `PreCommand` and `PostCommand` component manifest settings for running scripts before or after an update. Experimental.
- feat: Remote components can specify a `subpath` to use.
- tests: new testcontainers based setup to replace virter tests
- feat: `clean` command now attempts to gracefully remove components. Skippable with `--force`.
- feat: server mode can now listen on a webhook for sync/update requests.
    - `server.webhook` is now `server.notify_webhook`, though see also the new `notify` config block
    - `server.update_webhook` = true|false
    - `server.update_secret` = "shared secret"
    - `server.update_url` = URL to listen on. Default `:6284/webhook`
- feat: `lock` setting causes materia to create a dbus or file lock, preventing multiple instances from running destructive actions.
- feat: `materia server` now exposes a varlink api over its socket
- feat: `materia agent` now uses new varlink api
- refactor: materia now uses native podman bindings instead of wrapping the `podman` command. If you experience issues with this, use the `MATERIA_PODMAN_COMMAND` flag to restore the old behaviour.
- feat: quadlet drop-ins are now left-unchanged by `materia update`.
- feat: new service resource config setting: `Oneshot`.
- feat: experimental rollback on failure support. Enable with `rollback.kind = "service"`
    - service state health checks have been rewritten
    - Currently supports git source, OCI coming post 0.7.0
    - If a materia update leads to a failed service or a service is in the wrong state at the end of the update, checkout the last known git commit and run the update again
- feat: `notify` config block for configuring all webhook notifications in one place
    - Set `notify.triggers.update` to replace `server.notify_webhook`
    - Get notifications when rollback occurs with `notify.triggers.rollback`
    - `server.notify_webhook` is now deprecated and will be removed in a future release, server mode uses same notification code as everywhere else.
- refactor: removed `source.URL` guessing. `source.URL` is now passed directly to the sources config.

Deprecations

{ snippet "autoUpdate" } has been removed; there was little purpose for it with AutoUpdate= already existing.
Materia will no longer attempt to guess the source type from source.URL. You now need to specify the source type with source.kind.