Quadlet lets you run your Podman containers as systemd services.
This is especially useful for running containers in the background and automatically starting them after a server reboot.

Running Podman containers under systemd isn’t new.
Indeed, this was supported by Podman for a long time with the command podman generate systemd.
But this command now shows a deprecation warning to migrate to Quadlet.

For some months, I was too lazy to do that migration on my home server.
Why even touch a working system?
But now that I finally found time for it, I really appreciate Quadlet!
I think that Podman finally has a Docker Compose alternative which is even more flexible and powerful!

In this blog post, I will explain how to use Quadlet with rootless Podman and migrate from the old method with podman generate systemd.

Landscape mode recommended on mobile devices

The deprecated method

Let’s see how the old method worked before comparing it to Quadlet.
You can skip to the Quadlet section though.

First, you had to create a container.
In an older post about Containerized PostgreSQL with rootless Podman, I created a container with a command similar to the following:

podman create 
  --name test-db 
  -p 5432:5432 
  -v ~/volumes/test-db:/var/lib/postgresql/data:Z 
  -e POSTGRES_PASSWORD=CHANGE_ME 
  --label "io.containers.autoupdate=registry" 
  docker.io/library/postgres:16

The command details are explained in the older post.
The only option that isn’t explained there is --label "io.containers.autoupdate=registry".
This option enables updating the container image using podman auto-update which will be explained later in this post.

After creating the container, you can run the following command:

podman generate systemd test-db -fn --new

It creates the systemd service file container-test-db.service in your current path.
The options of the command aren’t relevant for now, but they are also explained in the older post.

To use this generated service file, you had to place it in the directory ~/.config/systemd/user.
To enable and start it, you had to run the following command:

systemctl --user enable --now container-test-db

The problem

The problem with the old method is that it required you to run commands to…

1. create a container
2. generate a service file
3. move the service file if not already in the mentioned directory
4. enable the service

Especially the command for creating the container is often lengthy.
This means that you had to create a shell script with these commands if you wanted to be able to rerun them later.

To reduce duplication, I created the following fish function to be called in my fish scripts that create the containers:

function podman-default-create
    set -l container_name $argv[1]

    podman create 
        --name $container_name 
        --replace 
        $argv[2..]; or return 1

    podman generate systemd --no-header --new --name $container_name >~/.config/systemd/user/container-$container_name.service; or return 1

    systemctl --user enable --now container-$container_name
end

You don’t have to understand the details of the function above.
What I want to demonstrate with it is that the old method was too hacky and involved the usage of redundant commands.

There must be an easier way, you might think.
Especially if you experienced the convenience that Docker Compose provides.
But this is not the only problem.
The old method is very inflexible!

If you want to cutomize the service file and use all systemd features, you need to manually edit it after each generation!

Quadlet

Let’s take a look at the new method with Quadlet.

First, you create the directory ~/.config/containers/systemd.
Then, you place a .container file inside it.
For example, here is the test-db.container file:

[Container]
Image=docker.io/library/postgres:16
AutoUpdate=registry
PublishPort=5432:5432
Volume=%h/volumes/test-db:/var/lib/postgresql/data:Z
Environment=POSTGRES_PASSWORD=CHANGE_ME

[Service]
Restart=always

[Install]
WantedBy=default.target

It is a normal systemd service file but with the special section [Container].
This section has many documented options.
Almost all these options map to command line options that can be used to create a container with Podman (podman create).
The ones that we are interested in for the example are the following:

• Image specifies the image (with tag) to use
• AutoUpdate=registry maps to --label "io.containers.autoupdate=registry" (explained later in this post)
• PublishPort maps to -p
• Volume maps to -v
• Environment maps to -e

It is important to use the systemd specifier %h instead of ~ for the user home directory.

In the [Service] section, we use the Restart option and set it to always to always restart the container (unless stopped manually).

To automatically start the container on boot, we set the WantedBy option in the [Install] section to default.target.

Read More