{"id":40928163,"url":"https://github.com/stryan/materia","last_synced_at":"2026-01-27T03:11:30.809Z","repository":{"id":301667771,"uuid":"1008732286","full_name":"stryan/materia","owner":"stryan","description":"GitOps tool for deploying Quadlets","archived":false,"fork":false,"pushed_at":"2026-01-18T03:11:42.000Z","size":989,"stargazers_count":115,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-18T14:34:37.169Z","etag":null,"topics":["configuration-management","containers","continuous-delivery","gitops","podman","quadlets"],"latest_commit_sha":null,"homepage":"https://primamateria.systems","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stryan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-26T02:36:24.000Z","updated_at":"2026-01-18T03:11:46.000Z","dependencies_parsed_at":"2025-07-24T03:32:47.194Z","dependency_job_id":"23f1b0de-055f-424a-8d45-715638b6a4a2","html_url":"https://github.com/stryan/materia","commit_stats":null,"previous_names":["stryan/materia"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/stryan/materia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stryan%2Fmateria","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stryan%2Fmateria/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stryan%2Fmateria/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stryan%2Fmateria/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stryan","download_url":"https://codeload.github.com/stryan/materia/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stryan%2Fmateria/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28798674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"online","status_checked_at":"2026-01-27T02:00:07.755Z","response_time":168,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration-management","containers","continuous-delivery","gitops","podman","quadlets"],"created_at":"2026-01-22T04:00:40.907Z","updated_at":"2026-01-27T03:11:30.803Z","avatar_url":"https://github.com/stryan.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Materia\n\n[![Chat on Matrix](https://matrix.to/img/matrix-badge.svg)](https://matrix.to/#/#materia:saintnet.tech)\n\nA GitOps tool for managing services and applications deployed as [Podman Quadlets](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).\n\nMateria handles the full lifecycle of an application (or **component**):\n1. Materia polls a remote source, downloading a manifest describing what the state of the applications on the host should look like.\n2. It installs components and all their associated Quadlets and data files, templating files with variables and secrets if required\n3. It starts services required by the component.\n4. When updated files are found in the source repository it updates the installed versions and restarts services accordingly.\n5. And when a component is not longer assigned to a host, it stops all related services and removes the resources, keeping things nice and tidy.\n\nCurious to how it works? See the `materia update` [workflow diagram](./diagram.md)\n\n# Documentation\n\nMain Documentation site: [primamateria.systems](https://primamateria.systems)\n\nQuickstart guide: [On the documentation website](https://primamateria.systems/quickstart.html).\n\nOnline Manpages: [latest](https://primamateria.systems/documentation/latest/reference/)\n\nExample Materia Repository: [here](https://github.com/stryan/materia_example_repo)\n\nExample Materia Component: [dnsmasq component here](https://github.com/stryan/dnsmasq_component)\n\n# Installation\n\n## Requirements\n\nThe following are run time requirements and reflect what systems Materia is tested on. It may work without the specified versions (especially the systemd requirement).\n\nMateria will not work with Podman versions lower than 4.4, as that is the version Quadlets were introduced in.\n\n- Podman 5.4 or higher\n- Systemd v254 or higher\n- AMD64 or ARM64 architecture\n\nMateria supports running both root-full and rootless quadlets, however currently root-full is the more tested pathway.\n\n## From source\nBuild from source using `mise build`. By default this will generate binaries for amd64 and arm64.\n\nIf you'd like to build without mise, you can do so through the normal go methods such as: `go build -ldflags=\"-w -s\" -o bin/materia-arm64 ./cmd/materia/`\n\n## From Binary\n\nGrab a release for your architecture from the releases page; the static binaries should work on any relatively recent Linux distro.\n\n## With Podman\n\nFor obvious reasons, materia should only be run using `podman` as your container engine.\n\nBy default it is assumed you are running using root. If not, you'll need to update the bind mounts to their appropriate locations; see the [manual](./docs/markdown/reference/index.md) for more details. By default materia uses XDG_DIR settings in rootless mode.\n```\npodman run --name materia --rm \\\n\t--hostname \u003csystem_hostname\u003e \\\n\t--network host \\\n\t--security-opt label=disable \\ # optional, depending on OS security settings\n\t-v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket \\ # needed to manage systemd units\n\t-v /run/podman/podman.sock:/run/podman/podman.sock \\ # needed to get container status\n\t-v /var/lib/materia:/var/lib/materia \\ # Where materia stores its source cache and component data\n\t-v /etc/containers/systemd:/etc/containers/systemd \\ # needed to install Quadlets\n\t-v /usr/local/bin:/usr/local/bin \\ # customizable, change to where ever you want scripts to be installed to\n\t-v /etc/systemd/system:/etc/systemd/system \\ # Needed to manage services, can also use /usr/local/lib/systemd/system/\n\t-v /etc/materia/known_hosts:/root/.ssh/known_hosts:ro \\ #Optional, used for git+ssh checkouts\n\t-v /etc/materia/key.txt:/etc/materia/key.txt \\ #Optional, used for age decryption\n\t-v /etc/materia/materia_key:/etc/materia/materia_key \\ # Optional, used for git+ssh checkouts\n\t--env MATERIA_AGE__KEYFILE=/etc/materia/key.txt \\\n\t--env MATERIA_SOURCE__KIND=\"git\" \\\n\t--env MATERIA_SOURCE__URL=https://github.com/stryan/materia_example_repo \\\n\tghcr.io/stryan/materia:stable update\n```\n\nNote that some security settings may need to be adjusted based off your distro. For example, systems using AppArmor may require `PodmanArgs=--security-opt=apparmor=unconfined`.\n\nSee [install](./install/) for example Quadlets.\n\n### Available tags\n\n**stable**: Use the latest tagged release.\n\n**v\u003ctag\u003e**: Specific tagged release.\n\n**latest**: Latest push to master\n\n# Contributing\n\n Questions or bug reports are welcome! Please start a Discussion versus opening an Issue, as Materia does bug tracking outside of Github using [git-bug](https://github.com/git-bug/git-bug). You can also submit bugs/suggestions or ask questions in the [Matrix room](https://matrix.to/#/#materia:saintnet.tech).\n\nFor submitting features/bugfixes/code-in general via merge requests, please see the [Contribution guide](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstryan%2Fmateria","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstryan%2Fmateria","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstryan%2Fmateria/lists"}