How to create a Pod with 2 containers : systemd cannot find the pod service

[TomGudman]

Hi,

I am trialing podman 5.4.2. I am still in the discovery process.

I am trying to get bookstack docker-compose to a podman rootless setup (user: podman). My goal is to encompass 2 containers (app + db) into a pod to stop/start bookstack conveniently. The quadlet files are generated with Ansible and deployed on a VM. Once this test is successful I will proceed to migrate more complex docker-compose.

Unfortunately, my quadlet files don't seem to generate bookstack-pod.service systemd unit. However if I remove the Requires= and the After= constraints from bookstack.pod, bookstack-pod.service suddenly exists and the below error cease to exist but there isn't any other containers except the infra one.

ISSUE

podman@wiki01:~/.config/containers/systemd$ systemctl --user start bookstack-pod
Failed to start bookstack-pod.service: Unit bookstack.pod.service not found.

The quadlet to systemd service is a bit magic to me and I cannot find any logs or pointer indicating why with constraints the pod doesn't start or more exactly its .service file is missing. I can start the 2 containers individually though (db and app by removing any Pod related information from their respective .container files) .

Podman version

Client:        Podman Engine
Version:       5.4.2
API Version:   5.4.2
Go Version:    go1.24.2
Built:         Sat May 24 19:34:43 2025
Build Origin:  Debian
OS/Arch:       linux/arm64

My files

podman@wiki01:~/.config/containers/systemd$ ls -l
-rw-r--r-- 1 podman podman 825 Jun 26 07:49 bookstack-app.container
-rw-r--r-- 1 podman podman 104 Jun 26 04:14 bookstack-app-data.volume
-rw-r--r-- 1 podman podman 638 Jun 26 07:47 bookstack-db.container
-rw-r--r-- 1 podman podman 106 Jun 26 04:14 bookstack-db-data.volume
-rw-r--r-- 1 podman podman 503 Jun 26 07:43 bookstack.pod

.POD

podman@wiki01:~$ cat .config/containers/systemd/bookstack.pod 
[Unit]
Description=Pod for the Bookstack Application
Requires=bookstack-db.service bookstack-app.service     <<<<<  If I remove these two lines, an empty pod will start
After=bookstack-db.service bookstack-app.service            <<<<<

[Pod]
PublishPort=8080:80

[Install]
# This makes 'bookstack.pod.service' the main service you can enable.
WantedBy=default.target

DB CONTAINER

podman@wiki01:~$ cat .config/containers/systemd/bookstack-db.container 
# Defines the MariaDB container
[Unit]
Description=Bookstack MariaDB container
# This service is part of the main pod service
BindsTo=bookstack.pod.service
After=bookstack.pod.service

[Container]
# Assign this container to the 'bookstack' pod
Pod=bookstack.pod
Image=docker.io/linuxserver/mariadb:latest
Volume=bookstack-db-data.volume:/config
Environment=MYSQL_ROOT_PASSWORD=a_very_secret_root_password
Environment=MYSQL_DATABASE=bookstack
Environment=MYSQL_USER=bookstack
Environment=MYSQL_PASSWORD=a_secret_user_password
Environment=PUID=1000
Environment=PGID=1000
Environment=TZ=Etc/UTC

[Service]
Restart=always
TimeoutStartSec=180

APP CONTAINER

podman@wiki01:~$ cat .config/containers/systemd/bookstack-app.container 
# Defines the Bookstack application container
[Unit]
Description=Bookstack application container
# This service is part of the main pod service and depends on the DB
BindsTo=bookstack.pod.service bookstack-db.service
After=bookstack.pod.service bookstack-db.service

[Container]
# Assign this container to the 'bookstack' pod
Pod=bookstack.pod
Image=docker.io/linuxserver/bookstack:latest
Volume=bookstack-app-data.volume:/config
Environment=APP_KEY=base64:3qjlIoUX4Tw6fUQgZcxMbz6lb8+dAzqpvItqHvahW1c=
Environment=APP_URL=http://wiki.infra.net:8080
Environment=DB_HOST=localhost
Environment=DB_PORT=3306
Environment=DB_USER=bookstack
Environment=DB_PASS=a_secret_user_password
Environment=DB_DATABASE=bookstack
Environment=PUID=1000
Environment=PGID=1000
Environment=TZ=Etc/UTC

[Service]
Restart=always
TimeoutStartSec=180 

VOLUMES

podman@wiki01:~/.config/containers/systemd$ cat bookstack-app-data.volume 
[Unit]
Description=Volume for Bookstack data

[Volume]
# This volume will be named 'bookstack-app-data'

podman@wiki01:~/.config/containers/systemd$ cat bookstack-db-data.volume 
[Unit]
Description=Volume for Bookstack DB data

[Volume]
# This volume will be named 'bookstack-db-data'

Quadlets files output:

podman@wiki01:~/.config/containers/systemd$ /usr/libexec/podman/quadlet -dryrun -user -v 
quadlet-generator[10924]: Loading source unit file /home/podman/.config/containers/systemd/bookstack-app-data.volume
quadlet-generator[10924]: Loading source unit file /home/podman/.config/containers/systemd/bookstack-app.container
quadlet-generator[10924]: Loading source unit file /home/podman/.config/containers/systemd/bookstack-db-data.volume
quadlet-generator[10924]: Loading source unit file /home/podman/.config/containers/systemd/bookstack-db.container
quadlet-generator[10924]: Loading source unit file /home/podman/.config/containers/systemd/bookstack.pod
---bookstack-app-data-volume.service---
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=Volume for Bookstack data
SourcePath=/home/podman/.config/containers/systemd/bookstack-app-data.volume
RequiresMountsFor=%t/containers

[X-Volume]
# This volume will be named 'bookstack-app-data'

[Service]
ExecStart=/usr/bin/podman volume create --ignore systemd-bookstack-app-data
SyslogIdentifier=%N
Type=oneshot
RemainAfterExit=yes

---bookstack-db-data-volume.service---
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=Volume for Bookstack DB data
SourcePath=/home/podman/.config/containers/systemd/bookstack-db-data.volume
RequiresMountsFor=%t/containers

[X-Volume]
# This volume will be named 'bookstack-db-data'

[Service]
ExecStart=/usr/bin/podman volume create --ignore systemd-bookstack-db-data
SyslogIdentifier=%N
Type=oneshot
RemainAfterExit=yes

---bookstack-app.service---
# Defines the Bookstack application container
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=Bookstack application container
# This service is part of the main pod service and depends on the DB
BindsTo=bookstack.pod.service bookstack-db.service
After=bookstack.pod.service bookstack-db.service
SourcePath=/home/podman/.config/containers/systemd/bookstack-app.container
RequiresMountsFor=%t/containers
Requires=bookstack-app-data-volume.service
After=bookstack-app-data-volume.service
BindsTo=bookstack-pod.service
After=bookstack-pod.service

[X-Container]
# Assign this container to the 'bookstack' pod
Pod=bookstack.pod
Image=docker.io/linuxserver/bookstack:latest
Volume=bookstack-app-data.volume:/config
Environment=APP_KEY=base64:3qjlIoUX4Tw6fUQgZcxMbz6lb8+dAzqpvItqHvahW1c=
Environment=APP_URL=http://wiki.infra.iob:8080
Environment=DB_HOST=localhost
Environment=DB_PORT=3306
Environment=DB_USER=bookstack
Environment=DB_PASS=a_secret_user_password
Environment=DB_DATABASE=bookstack
Environment=PUID=1000
Environment=PGID=1000
Environment=TZ=Etc/UTC

[Service]
Restart=always
TimeoutStartSec=180
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStop=/usr/bin/podman rm -v -f -i --cidfile=%t/%N.cid
ExecStopPost=-/usr/bin/podman rm -v -f -i --cidfile=%t/%N.cid
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name systemd-%N --cidfile=%t/%N.cid --replace --rm --cgroups=split --sdnotify=conmon -d -v systemd-bookstack-app-data:/config --env APP_KEY=base64:3qjlIoUX4Tw6fUQgZcxMbz6lb8+dAzqpvItqHvahW1c= --env APP_URL=http://wiki.infra.iob:8080 --env DB_DATABASE=bookstack --env DB_HOST=localhost --env DB_PASS=a_secret_user_password --env DB_PORT=3306 --env DB_USER=bookstack --env PGID=1000 --env PUID=1000 --env TZ=Etc/UTC --pod-id-file %t/bookstack-pod.pod-id docker.io/linuxserver/bookstack:latest

---bookstack-db.service---
# Defines the MariaDB container
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=Bookstack MariaDB container
# This service is part of the main pod service
BindsTo=bookstack.pod.service
After=bookstack.pod.service
SourcePath=/home/podman/.config/containers/systemd/bookstack-db.container
RequiresMountsFor=%t/containers
Requires=bookstack-db-data-volume.service
After=bookstack-db-data-volume.service
BindsTo=bookstack-pod.service
After=bookstack-pod.service

[X-Container]
# Assign this container to the 'bookstack' pod
Pod=bookstack.pod
Image=docker.io/linuxserver/mariadb:latest
Volume=bookstack-db-data.volume:/config
Environment=MYSQL_ROOT_PASSWORD=a_very_secret_root_password
Environment=MYSQL_DATABASE=bookstack
Environment=MYSQL_USER=bookstack
Environment=MYSQL_PASSWORD=a_secret_user_password
Environment=PUID=1000
Environment=PGID=1000
Environment=TZ=Etc/UTC

[Service]
Restart=always
TimeoutStartSec=180
Environment=PODMAN_SYSTEMD_UNIT=%n
KillMode=mixed
ExecStop=/usr/bin/podman rm -v -f -i --cidfile=%t/%N.cid
ExecStopPost=-/usr/bin/podman rm -v -f -i --cidfile=%t/%N.cid
Delegate=yes
Type=notify
NotifyAccess=all
SyslogIdentifier=%N
ExecStart=/usr/bin/podman run --name systemd-%N --cidfile=%t/%N.cid --replace --rm --cgroups=split --sdnotify=conmon -d -v systemd-bookstack-db-data:/config --env MYSQL_DATABASE=bookstack --env MYSQL_PASSWORD=a_secret_user_password --env MYSQL_ROOT_PASSWORD=a_very_secret_root_password --env MYSQL_USER=bookstack --env PGID=1000 --env PUID=1000 --env TZ=Etc/UTC --pod-id-file %t/bookstack-pod.pod-id docker.io/linuxserver/mariadb:latest

---bookstack-pod.service---
# This defines the "bookstack" pod and its published ports.
# It also becomes the main systemd service to manage.
[Unit]
Wants=podman-user-wait-network-online.service
After=podman-user-wait-network-online.service
Description=Pod for the Bookstack Application
# This pod requires the volume services to be ready first.
Requires=bookstack-db.service bookstack-app.service
After=bookstack-db.service bookstack-app.service
SourcePath=/home/podman/.config/containers/systemd/bookstack.pod
RequiresMountsFor=%t/containers
Wants=bookstack-app.service
Before=bookstack-app.service
Wants=bookstack-db.service
Before=bookstack-db.service

[X-Pod]
# The ports are published at the pod level.
PublishPort=8080:80

[Install]
# This makes 'bookstack.pod.service' the main service you can enable.
WantedBy=default.target

[Service]
SyslogIdentifier=%N
ExecStart=/usr/bin/podman pod start --pod-id-file=%t/%N.pod-id
ExecStop=/usr/bin/podman pod stop --pod-id-file=%t/%N.pod-id --ignore --time=10
ExecStopPost=/usr/bin/podman pod rm --pod-id-file=%t/%N.pod-id --ignore --force
ExecStartPre=/usr/bin/podman pod create --infra-conmon-pidfile=%t/%N.pid --pod-id-file=%t/%N.pod-id --exit-policy=stop --replace --publish 8080:80 --infra-name systemd-bookstack-infra --name systemd-bookstack
Environment=PODMAN_SYSTEMD_UNIT=%n
Type=forking
Restart=on-failure
PIDFile=%t/%N.pid

Questions

1. Can you pinpoint to what I am doing wrong?
2. What's and where is the bit that magically converts .pod/.containers files to .services files?
3. Where are these generated .services file located?
4. Where can i find logs? journalctl -f didn't show anything useful.

Thank you for your assistance. The internet is full of contradicting or old information and Gemini AI keeps feeding me erroneous info and is apologetic ;-)

[ygalblum]

I'm am not sure it you are deciding the content of the Quadlet units or if it's Ansible. But, the issue is with this reference:

BindsTo=bookstack.pod.service
After=bookstack.pod.service

(similar issue in the app container)

First, they are incorrect because the name of the generated service for the .pod unit is: bookstack-pod.service
But second, and more important, they are redundant at the Quadlet level since Qualdet will set the required dependencies once you set:

Pod=bookstack.pod

Regarding question 2, Quadlet is that bit. Quadlet is a systemd-generator that systemd calls whenever it reloads its daemon (boot, login, explicit reload, etc.)
Question 3 for root it's /run/systemd/generator and for rootless $XDG_RUNTIME_DIR/systemd/generator :

[shaun-forgie]

Thanks @ygalblum for the info.

So to spell it out in plain english...to fix the problem

1. Update the bookstack-app.container / bookstack-db.container files
2. Remove the Requires and After lines in the .pod file

Change the [Unit] section to remove references to the bookstack-pod.service as the dependency is defined in:

[Container]
// Assign this container to the 'bookstack' pod
Pod=bookstack.pod

[Unit]
Description=Bookstack application container
// This service is part of the main pod service and depends on the DB
BindsTo=bookstack-db.service
After=bookstack-db.service

Manage run time dependencies between containers in the [Unit] section of the .container files. In this case bookstack-app.container declares a dependency on the database in this line:

After=bookstack-db.service

[ygalblum]

Yes, I think this sums it up

[shaun-forgie]

@ygalblum it would seem more intuitive to declare dependencies between containers and container artefacts directly rather than using their derived/generated .service file names. At the time of declaring container runtime dependencies those systemd services do not yet exist. This requires the author to understand how container file names are translated into systemd service names.

It would make it alot easier to understand if dependencies between containers used references to other .container artefacts rather than system service artefacts that have not yet been generated.

More generally the mental model should be that containers refer to containers and not their systemd derived service counter parts. This would allow authors to deal with container concepts [containers / volumes / networks / pods] without being aware of the systemd service mechanisms that get generated after.

[ygalblum]

@shaun-forgie I'll split my answer into two parts

One, implicit dependencies should be left for Quadlet to create. For example, if a app.container uses a network created by a app.network, the former should set Network=app.network and let Quadlet translate both the name of the network created by the latter and set the dependency between the generated service units.

Two, explicit dependencies, like between the App and the DB in this example. I've implemented your suggestion not long ago. It was merged here: #25899 and is part of v5.5.X

[TomGudman]

Thank you guys for the detailed answer.s I will try to confirm later down the track.

On a side note, the challenge with Podman is finding the right information because the software has evolved quite a lot over the past year. As a result we find a lot of contradicting information on blog, articles, videos, etc. Unfortunately it's hard to decrypt what's best practice with all the scattered information, the noise and the man style documention available on the podman website :)

Nonetheless, I believe podman is the future and it's looking promising. So thank you again for your answers.

I leave this comment open for now, but I wouldn't be surprised if a bot closes it due to inactivity.

[shaun-forgie]

You may want to contribute your work to the quadlet forge repo found here https://github.com/Rhiplay04/QuadletForge/tree/main

This will provide users with good examples of how to setup and configure applications using these new podman techniques.

[ygalblum]

We also maintain one as part of the containers project: https://github.com/containers/appstore