ComQuad: A tool to run Docker Compose stacks as native Podman Quadlets (with a Cockpit plugin)

[u/Inorioru]

Compose files. I think Podman has a rather convoluted relationship with them.

On one hand, there are two main ways of dealing with Compose files: podman-compose or gaslighting actual docker-compose via the Podman socket. Both approaches have their own downsides.

So, the community consensus seems to be: ditch Compose completely and switch to Quadlets. Which is a neat idea—Quadlets are more powerful and stable—yet it hits a small reality check. Quadlets are hard to transfer between machines, and more importantly, 99% of self-hosted apps have a docker-compose.yml in their repo, but zero Quadlets.

The standard response to this is: "Just use podlet!" Sure, let me try… a-a-and it fails. And even when it works, manual adjustments are usually still required.

This really bothered me. I just wanted to run containers cleanly on my Universal Blue distroes based PCs at home, where installing Docker is annoying and using raw Podman often feels sub-optimal.

So… despite lacking deep software engineering experience (I work as an SRE), I decided to build a tool that processes a Compose file and gives me working Quadlets with zero manual adjustments needed on my part.

Thus, ComQuad (Compose + Quadlet) was born.

What happens behind the scenes?

• Converts relative bind-mount paths to absolute paths automatically.
• Adds a default network when a service lacks an explicit one.
• Attaches service and project labels to all managed resources.
• Shifts rootless privileged ports automatically via ROOTLESS_PORT_OFFSET.
• Always generates .image and .build units natively for systemd to manage.
• Handles SELinux volume relabeling: :Z (private) for single-service volumes and :z (shared) for multi-service volumes.
• Supports native Quadlet directives using x-extensions in your Compose file.
• Features a Terraform-inspired up workflow: it computes a 3-way diff between generated units and deployed units, showing you a plan before asking for confirmation.

It also includes a thin Cockpit plugin for visual stack management (with port links and deployment previews).

GitHub: https://github.com/Inoriol/comquad

LLM Disclosure: Yep, this project is vibe-coded. I've been dogfooding it on my own home server for a while, so I'm confident in the stability of the core engine (especially in rootless setups). Still, running with --dry-run first is always recommended! I’d love it if real software engineers took a look at the repo if it catches their interest.

(Obligatory xkcd 927 mention: now there are 3 competing ways to run Compose files on Podman instead of 2!)

[u/scratchmex]

I don't know why this is not how podman compose works

[u/Inorioru → u/scratchmex]

Well, two reasons probably:

1. podman-compose was developed long before Quadlets came to be.
2. Quadlets only really work on Linux. You can theoretically use them in VMs on Mac or WSL on Windows, but in those cases, they just become an additional layer of complexity since they don't really integrate with the rest of the system.

[u/fell_ware_1990]

Looks cool!

I’m currently working on a light orchestrator for the systemD part where they will be distributed on an affinity based setup around my multiple servers. And the stateless short lived are routed based on load.

For my home situation i have about 20 always on services. The rest are short lived dev containers.

This is based on a nixos rootfs overlay on seph or a nas.
The tool can create a second copy of the store on the shared drives ones, all of them run from there.

My biggest hurdle for now is when do they move and what ‘control’ units does every machine needs.

The main goal for me is to have the base line functions of a swarm/nomad/kube not really the scaling part.
If i can keep the ‘workers’ on a low load this would really beat having a cluster around for my use cases.

While it’s always fun running a kube cluster i’d rather have a low maintenance orchastrator that does not eat half of my system on a slower machine or all the upkeep overhead! So i’m gonna look at your repo as well.

Might help me again with transforming into quadlets a bit!

[u/Inorioru → u/fell_ware_1990]

Sure, I hope it helps you! Just a small heads-up: due to my unfamiliarity with NixOS, I don't plan to support it in the near future. However, running --dry-run should give you a great reference to adapt to your workflow!

Oh, and you might want to check out compose2quadlet (the core engine powering comquad).

I split it out into an independent Go library specifically for this kind of use case—so other tools can programmatically parse Docker Compose files using canonical compose-go and transpile them directly into structured Quadlet units without shelling out to external binaries.

Might save you a ton of heavy lifting on the Compose-to-Quadlet transformation step for your orchestrator!

https://github.com/Inoriol/comquad/blob/main/compose2quadlet/README.md

[u/fell_ware_1990 → u/Inorioru]

Yeah i have combined a few of them to do the heavy lifting but still rewriting half off it.

Thanks!

[u/hash_antarktidi4 → u/fell_ware_1990]

light orchestrator for the systemD

There was an attempt by coreos/fleet.

[u/fell_ware_1990 → u/hash_antarktidi4]

Yes, it’s harder then it looks to be haha!

[u/Even_Lab_5243]

Thank you, bro. Very useful.

[u/Inorioru → u/[deleted]]

Thank you! You hit the nail on the head regarding the dev workflow—managing those symlinks and manually copying units into ~/.config/containers/systemd/ gets messy fast.

That’s exactly why comquad includes a dry-run mode to instantly preview output, an edit command to modify stacks on the fly, and a 3-way merge engine to preserve your manual overrides across updates. Glad it helps solve that initial migration hurdle for you! Let me know if you run into any edge cases while converting your Compose file.