Podman's Quadlet feature allows podman containers to be integrated into systemd services.

Why manage containers with systemd? You might argue that containers are better orchestrated with Docker Swarm, Kubernetes, or even Ansible. That is true for larger installations. For a single Linux box or VPS, systemd is probably running on it already. I couldn't summarize it better than Elias Bourgess: it's the control pane you already run.

There are two ways to write Quadlets:

• INI-style quadlet definitions. An extension of systemd's INI-style config language. This adds sections for things like containers and volumes. This approach is for Linux system administrators who are already familiar with systemd.
• K8s-style quadlet definitions. These are Kubernetes-style yaml files that define your containers. This approach is clearly aimed at developers and devops folks already familiar with Kubernetes or docker-compose.

I'm a developer who's used to docker-compose, so I tried out the k8-style first. That said, curiosity got the better of me, and I wondered what INI-style Quadlet definitions would look like.

Setup 🔗

Here's a minimal setup for a Node.js application (full source code can be found here):

├── app
│   ├── index.js
│   ├── node_modules
│   ├── package.json
│   └── package-lock.json
├── dev
│   ├── example-app-dev.container
│   └── example-app-dev.pod
├── prod
│   ├── Containerfile
│   ├── example-app.build
│   ├── example-app.container
│   └── example-app.pod
└── README.md

The quadlet-specific files here are under the dev and prod subdirectories for development and production, respectively. Here's a look at the ones in dev:

dev/example-app-dev.container:

[Unit]
Description=Example Node.js app

[Container]
Pod=example-app-dev.pod
Image=docker.io/node:24
WorkingDir=/app
Exec=/bin/sh -c "npm i && node --watch index.js"
Volume=../app:/app:Z
Environment=PORT=3001

[Install]
WantedBy=multi-user.target

dev/example-app-dev.pod:

[Unit]
Description=Development version of example app

[Pod]
PodName=example-app-dev
ExitPolicy=stop
PublishPort=3001:3001

[Install]
WantedBy=default.target

Dev Workflow: 🔗

1. Clone the repo.
2. Find your systemd discovery path. On most systems, that resolves to ${XDG_CONFIG_HOME:-$HOME/.config}/containers/systemd. So something like ~/.config/containers/systemd. (If you're doing rootless, which I am)
3. cd into your repo, and link up the repo's subdirs into your quadlet discovery path:

cd project-dir

# symlink the entire project directory over. Note that "example-app" can be anything, and should be uniquely named
# to prevent clashes with other systemd services
ln -sfn "$PWD" ~/.config/containers/systemd/example-app

Now reload systemd with this new application, and confirm all is well

# This rebuilds the quadlets -> actual systemd runtime files
systemctl --user daemon-reload

# Confirm that quadlet picked it up with `podman quadlet list`. If all went well, you'll see your pod listed.
podman quadlet list

# Will probably give you something like
# NAME                       UNIT NAME                    PATH ON DISK                                       STATUS          APPLICATION
# example-app-dev.container  example-app-dev.service      /your/dev-dir/dev/example-app-dev.container        active/running  .dev.app
# example-app-dev.pod        example-app-dev-pod.service  /your/dev-dir/dev/example-app-dev.pod              active/running  .dev.app

# Check the status of the service
systemctl --user status example-app-dev.service

# BONUS: If you'd prefer your services to keep running after you log out (and start at boot), enable lingering for your user
sudo loginctl enable-linger $USER

Now to the actual developing! 🔗

The main source files under app are volume-mounted, so go ahead, start changing index.js, for example. Reload the browser to see your changes.

Deployment Workflow 🔗

If you're deploying to the same system you develop on, then all you're really doing is COPYing the node source files instead of volume-mounting. If you're using Typescript or anything else requiring compilation, you'll have to add that to your Containerfile too.

prod/example-app.container:

[Unit]
Description=Example Node.js app

[Container]
Pod=example-app.pod
Image=example-app.build
Exec=/bin/sh -c "node index.js"
Environment=PORT=3005

[Install]
WantedBy=default.target

prod/example-app.pod:

[Unit]
Description=Production version of example app

[Pod]
PodName=example-app-pod
ExitPolicy=stop
PublishPort=3005:3005

[Install]
WantedBy=default.target

prod/Containerfile:

FROM docker.io/library/node:24-alpine

WORKDIR /app

COPY app/ /app/

RUN npm ci

prod/example-app.build:

[Build]
ImageTag=localhost/example-app
File=Containerfile
SetWorkingDirectory=..

You've already linked the production files over, its just a matter of rebuilding.

# Rebuilds any necessary files
systemctl --user daemon-reload

# Start the production service
systemctl --user restart example-app.service

Point a browser at localhost:3005 and you should see your production app!

Final Thoughts 🔗

Honestly, I prefer the k8-style workflow over this. The idea of linking my project subdirectory into an arbitrary system path to start my service just feels so, alien. Even with the changes to Podman 6 and the --application flag, it feels like an odd workflow.

On the flipside, INI-style quadlets feel "closer to the metal". Having everything already written in systemd INI files is a pretty close representation of what actually gets loaded by systemd. There's a movement in the frontend ecosystem which eschews elaborate frameworks for plain "vanilla" javascript, and to just use the platform. I felt like there was a parallel to be found with Quadlets, and that was worth exploring.

I've been using Podman for a few years now, and overall I've found it a completely acceptable replacement for Docker. That said, I've found most of the tutorials/resources (and subsequently, AI) have described Podman from a more system-admin/devops workflow, not a web developer workflow. So in the next few posts, I'm going to outline some ways I've found to work with Podman containers. Some of them will be fairly familiar (like podman-compose), while others are much newer (like a Kubernetes-style “kube” file).

While the language is fairly readable, its error-messages aren't always clear. I was working on something like this today:

class Animal
  def initialize
  end
end

class Dog < Animal
  def initialize(name : String)
  end
end

class PetCemetary
  def initialize(@pets : Array(Animal | Dog))
  end
end

rufus = Dog.new(name: "rufus")

deadPets = Array(Animal).new
deadPets << rufus
cemetary = PetCemetary.new(deadPets)

This yielded a compile-error:

Showing last frame. Use --error-trace for full trace.

In classTest.cr:20:28

 20 | cemetary = PetCemetary.new(deadPets)
                                 ^-------
Error: expected argument #1 to 'PetCemetary.new' to be Array(Animal), not Array(Animal)

Overloads are:
 - PetCemetary.new(pets : Array(Animal | Dog))

In particular:

Error: expected argument #1 to 'PetCemetary.new' to be Array(Animal), not Array(Animal)

The error message implies a type-mismatch, but the types are identical.

So what's the issue?

Crystal can accept descendant classes (in this case, Dog) where they just ask for the parent classes (here that's Animal). So the solution was to remove the union from the parameter, and the Dog instance will still be accepted in to an array of Animal:

class Animal
  def initialize
  end
end

class Dog < Animal
  def initialize(name : String)
  end
end

class PetCemetary
  def initialize(@pets : Array(Animal))
  end
end

rufus = Dog.new(name: "rufus")

deadPets = Array(Animal).new
deadPets << rufus
cemetary = PetCemetary.new(deadPets)

But why would union of its type and sub-type throw an error? Especially if its subtype and parent type are interchangeable. Sure, the union is redundant, but not erroneous.

After discussing the error on the Crystal discord (thanks to @Blacksmoke16 and @HertzDevil for checking this out) it was determined this is a compiler bug of sorts. Not a terrible one, but confusing nonetheless.

Basically, the type-checker might be overly restrictive. when comparing types in a union operator. Things are a little more complicated by the fact that while it throws an error when expressing things in a ParentType | ChildType format, it doesn't throw an error when expressing it as Union(ParentType, ChildType). So really, its an inconsistency.

Anyways, I stil think Crystal is a fantastic language, and despite sometimes cryptic compile-time errors, I find the language is easy to use, productive, and relatively safe. If you like the Ruby's syntax, but can't stand its sluggish performance, not to mention lack of null/nil safety and duck-typing system, give Crystal a shot. What's more, I've found the community of developers and contributors really friendly and responsive.