Quadlets Without the Friction

See on github: https://github.com/fkmiec/quadctl

I've been trying to go all-in on podman quadlets for my home lab. With quadlets, systemd handles startup ordering, container and other system dependencies, monitoring and restarting containers, starting on boot, and even auto-updating containers.

Quadlet files are simple key=value property files, typically one per container or other resource. Recently, the podman team also proposed a single .quadlet file format, which makes it possible to declare my entire application setup in one file, similar to both docker compose and kubernetes.

In day to day operation, quadlets are rock solid.

Systemd? But I'm Not a System Admin

All that being said, if you were not a system admin in a previous life, you may have some trepidation about involving systemd to run containers. Even if you see the benefits, you may view installing quadlets to systemd as tantamount to doing a production deployment and feel like you need to be able to run locally with something like docker-compose while you're figuring out the container options, volumes, networking, etc.

Thankfully, when you think you are ready, podlet is there to convert your compose yaml file to one or more quadlet files. Unfortunately, while it works well, due to differences between docker and podman, there are often more details to figure out.

Then there is the fact that podman defines no less than 10 locations where you can deploy your quadlet files, with differences for rootful and rootless setups, and the complication of checking systemd status and logs.

Quadlets are a great solution in need of some user-friendly tooling.

One Set of Files, One Workflow, Systemd When You're Ready

So, having felt the pain, I created quadctl as a compose-like tool for working directly with podman quadlets. It supports a simple workflow that bridges running locally for development and deploying to systemd for production. You define your application as a folder with one or more quadlet files (.container, .pod, .volume, .network or .quadlet), a bit like docker compose, and then call quadctl start to launch it.

By design, quadctl has only a handful of commands and a few key flags:

• pull
• create
• start
• stop
• remove
• status
• ps
• stats
• images
• list, ls
• logs

The goal is to keep it simple and application-focused. If you want to inspect, exec, export, etc. the individual containers, the podman CLI has you covered.

The quadctl commands call podman by default but are applied to systemd if you pass the -s (or --systemd) flag. For example:

quadctl start will pull the images, if necessary, create and then start your containers by directly calling podman
quadctl -s start will install the quadlet files in your configured rootless quadlet generator folder (e.g. $HOME/.config/containers/systemd), reload and start them via systemd

Podman is rootless by default. Use sudo quadctl ... when dealing with rootful containers and images.

A Word About Organization

Quadctl uses folders for organization and scoping. That means that it treats a set of .container, .volume, .network and .pod files in a folder as an application and each command operates on the entire application. So, quadctl pull will pull all the application's images, quadctl start will start all the containers, and the "wrapper" commands like ps, stats, images, volumes and status all filter to show only the specified application's resources, rather than every container on the system.

Folder organization is also optionally extended to the quadlet generator folders. In other words, when you call quadctl -s create, your quadlet files AND their containing folder are copied to the quadlet generator folder (e.g. $HOME/.config/containers/systemd) as shown in list example below. The quadctl list command can show you a tree view of your configured quadlets path or, with the -s flag, a tree view of your quadlet generator folder.

❯ ./quadctl -s ls           
── /home/fkmiec/.config/containers/systemd
   ╰─ homebox
      ├─ homebox-app.container
      ├─ homebox-app.container.d
      │  ╰─ app.config
      ├─ homebox-data.volume
      ╰─ homebox.pod

The quadlet generator doesn't care if your quadlets are organized in subfolders, but YOU MIGHT if you ever need to browse or manipulate your deployed quadlets. Using quadctl -s create and quadctl -s remove, you may rarely have to examine the quadlet generator folders, but when something goes wrong, as it invariably does, you'll appreciate the extra organization.

If you're unfamiliar with systemd, remembering to daemon-reload and how to check systemd status and how to view systemd logs, as opposed to podman logs, just adds to the confusion. Quadctl tries to keep it simple. If you pass the -s flag, it invokes the requisite systemd commands so you see what you need to see. e.g.: quadctl -s status shows systemd status, quadctl -s logs opens systemd logs, quadctl -s list shows what's in your systemd quadlet generator folder (ie. what you have deployed).

Conclusion

There is still plenty to learn when moving from docker to podman. Rootless podman has many subtle gotchas and quadlet files and their many options take time to learn. Quadctl lets you focus on using quadlet files from the start, skip the compose/kubernetes translations, and run your quadlets locally or under systemd using the same simple command set.