Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: A Quadlet Stack

Turn a multi-container app into a boot-time systemd stack with Quadlet: volume, network, pod, database and web units, secrets, health checks, auto-update, and a checklist to validate it.

In the previous project you started a pod by hand. If the server reboots, nothing comes back. Here you describe the same application declaratively with Quadlet files so that systemd creates the network and volume, starts the database and app in the right order at boot, restarts them on failure and updates them safely.

Quadlet needs systemd and Podman, so the unit files are shown read-only. Two stand-ins generate the whole set of files from one description and validate that every reference points at something that exists.

The target

A rootless user deploy runs these units from ~/.config/containers/systemd/:

File Role
hits.network A private network for the app
hitsdata.volume Database storage
hits.pod The pod, publishing the web port
hits-db.container PostgreSQL in the pod
hits-app.container The web app in the pod
hits.build Builds the app image from a Containerfile (optional)

First prepare the host:

Terminal
sudo loginctl enable-linger deploy
printf '%s' 'a-long-random-password' | podman secret create hits-db-password -

The secret is stored by Podman, outside the unit files.

The unit files

hits.network:

INI
[Network]
Subnet=10.89.20.0/24

hitsdata.volume:

INI
[Volume]

hits.pod:

INI
[Pod]
PodName=hits
Network=hits.network
PublishPort=127.0.0.1:8080:8000

hits-db.container:

INI
[Unit]
Description=Hits database

[Container]
Image=docker.io/library/postgres:17
Pod=hits.pod
Volume=hitsdata.volume:/var/lib/postgresql/data
Secret=hits-db-password,type=env,target=POSTGRES_PASSWORD
HealthCmd=pg_isready -U postgres
HealthInterval=5s
HealthRetries=5
Notify=healthy

[Service]
Restart=on-failure
TimeoutStartSec=300

[Install]
WantedBy=default.target

hits-app.container:

INI
[Unit]
Description=Hits web app
After=hits-db.service
Requires=hits-db.service

[Container]
Image=hits.build
Pod=hits.pod
Secret=hits-db-password,type=env,target=PGPASSWORD
Environment=DATABASE_URL=postgresql://postgres@localhost:5432/postgres
AutoUpdate=local

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

hits.build:

INI
[Build]
ImageTag=localhost/hits:1.0
File=%h/hits/Containerfile
SetWorkingDirectory=%h/hits

Points to notice:

  • Notify=healthy makes systemd consider the database started only when its health check passes, so hits-app.service (ordered After=hits-db.service) never starts too early. This replaces the retry loop from the earlier project.
  • Both containers use Pod=hits.pod; the port is published on the pod and bound to localhost.
  • Image=hits.build tells Quadlet to build the image first and to use the resulting tag.
  • The app gets the password as PGPASSWORD, which the PostgreSQL client library (libpq, used by psycopg) reads automatically, so DATABASE_URL needs no password and the secret never sits in a unit file.

Starting the stack

Terminal
systemctl --user daemon-reload
systemctl --user start hits-app.service
systemctl --user status hits-pod.service hits-db.service hits-app.service
curl http://127.0.0.1:8080/
journalctl --user -u hits-app.service -f

Starting hits-app.service pulls in the database, the pod, the volume and the network through the dependencies Quadlet added. After a reboot (with lingering on) everything returns by itself. To change something, edit the file, run daemon-reload and restart the service.

Generating the files from one description

When you manage many stacks, writing each file by hand invites typos. This stand-in produces all the files from a single dictionary and prints them as a tree, which is also a decent way to review what you intend to deploy.

Python Generate a Quadlet file set (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Validating the stack

A set of unit files is only good if every reference resolves. This stand-in checks the references in the generated files: each Pod=, Network= and Volume= that names a Quadlet file must exist in the set.

Python Validate references (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The check finds that cache.volume is used but not defined. Add a cache.volume file (or remove the line) and the set is consistent.

Operations checklist

  • systemctl --user list-units 'hits*' shows every generated unit.
  • podman pod ps and podman ps --pod show the running objects.
  • journalctl --user -u hits-db.service for database logs.
  • systemctl --user enable --now podman-auto-update.timer for auto-update of labeled containers (see Systemd Services and Auto-Update).
  • Back up the volume: podman volume export hitsdata -o hitsdata.tar.
  • Review disk use occasionally: Storage Maintenance and Cleanup.

Keep the unit files in a Git repository and deploy them by copying into ~/.config/containers/systemd/. The stack becomes reviewable, repeatable and easy to rebuild on a new server.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Notify=healthy change for the database unit?

    With Notify=healthy, systemd waits for the container's health check before marking the service active.
  2. 2. How does hits-app.container make sure the database starts first?

    Ordering and requirement dependencies between services control start order.
  3. 3. Why use Secret= instead of Environment= for the password?

    Podman stores secrets separately, so unit files can be shared or committed without exposing them.
  4. 4. Which command makes systemd regenerate services after you edit a .container file?

    daemon-reload re-runs the Quadlet generator.

Summary

  • A Quadlet stack is a directory of .network, .volume, .pod, .container and .build files.
  • References between files create the objects and the systemd dependencies automatically.
  • Notify=healthy, Restart= and AutoUpdate= give readiness, supervision and updates.
  • Secrets keep passwords out of unit files; linger keeps the stack alive at boot without a login.
  • Generate and validate file sets with scripts when you maintain several stacks.

Next: Practice: Podman Troubleshooting Drills