Linux Lunatix

From Docker Compose to rootless Podman quadlets

Stefan Marx
| 7 minutes

Part 2 of the series that starts with Four servers, three distributions: why I consolidated.

At the end of this post you have a two-container app (Forgejo with PostgreSQL) running as rootless Podman quadlets. They start at boot, update themselves and log to the journal. No root daemon and no Compose file are involved.

Why quadlets

Podman can run Compose files with podman-compose or docker-compose against the Podman socket. I tried both. They work, but they keep the Compose model: one tool starts a group of containers, and systemd knows nothing about them. The older podman generate systemd is deprecated.

Quadlets put the containers into systemd directly. You write a .container file. At boot, or at systemctl --user daemon-reload, a systemd generator turns it into a normal service unit. From then on:

You need Podman 4.4 or newer. Fedora 44 ships Podman 5.

Step 1: a user for the apps

Each host has one unprivileged user that owns all its containers. I call it svc.

sudo useradd --create-home --shell /bin/bash svc
# Let svc's systemd instance run without a login session, and start it at boot
sudo loginctl enable-linger svc

useradd on Fedora also writes ranges to /etc/subuid and /etc/subgid. Rootless Podman needs them to map the user IDs inside a container. Check them:

grep svc /etc/subuid /etc/subgid
# /etc/subuid:svc:524288:65536
# /etc/subgid:svc:524288:65536

To work as that user, you need a real login session, or at least the right XDG_RUNTIME_DIR. sudo -iu svc alone gives you a shell where systemctl --user fails. These work:

sudo machinectl shell svc@          # a full session (needs systemd-container)
# or, for single commands:
sudo -u svc XDG_RUNTIME_DIR=/run/user/$(id -u svc) systemctl --user status

Rootless containers cannot bind ports below 1024 by default. If an app must listen on 80 or 443 directly (Traefik in the next post), lower the limit:

echo 'net.ipv4.ip_unprivileged_port_start = 80' | sudo tee /etc/sysctl.d/90-unprivileged-ports.conf
sudo sysctl --system

Step 2: the Compose file we start from

This is a shortened version of what ran on the old Ubuntu host:

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:15
    restart: unless-stopped
    environment:
      - DB_TYPE=postgres
      - DB_HOST=postgres:5432
      - DB_PASSWD=${FORGEJO_DB_PASSWORD}
    networks: [proxy, dbnet]
    depends_on: [postgres]
    volumes:
      - ./forgejo:/data
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.forgejo.rule=Host(`git.example.org`)"

  postgres:
    image: postgres:17-alpine
    restart: always
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: ${FORGEJO_DB_PASSWORD}
      POSTGRES_DB: forgejo
    networks: [dbnet]
    volumes:
      - ./postgres:/var/lib/postgresql/data

networks:
  dbnet:
  proxy:
    external: true

Each part of it becomes one quadlet file:

ComposeQuadlet file
networks: dbnetforgejo.network
a volumeforgejo-data.volume, forgejo-db.volume
a serviceforgejo.container, forgejo-postgres.container
.env with a passworda Podman secret
depends_onRequires= and After=

All files go into ~svc/.config/containers/systemd/.

Step 3: network and volumes

# forgejo.network
[Network]
NetworkName=forgejo
# forgejo-data.volume
[Volume]
VolumeName=forgejo-data
# forgejo-db.volume
[Volume]
VolumeName=forgejo-db

Without NetworkName= and VolumeName=, Podman calls them systemd-forgejo and systemd-forgejo-data. That works, but the explicit names are easier to read in podman volume ls and in backup scripts.

Step 4: a secret instead of the .env file

Compose read the database password from .env. Podman has secrets. Create one as svc:

printf '%s' "$(pwgen -s 32 1)" | podman secret create forgejo-db-password -
podman secret ls

The secret is stored in the user’s Podman storage and is not part of any image or quadlet file. In post 6 Ansible creates it from pass, so I never type it.

Step 5: the containers

The database first:

# forgejo-postgres.container
[Unit]
Description=Forgejo database

[Container]
ContainerName=forgejo-postgres
Image=docker.io/library/postgres:17-alpine
AutoUpdate=registry
Network=forgejo.network
# The host name the app uses for its database
NetworkAlias=postgres
Volume=forgejo-db.volume:/var/lib/postgresql/data:Z
Environment=POSTGRES_USER=forgejo POSTGRES_DB=forgejo
Secret=forgejo-db-password,type=env,target=POSTGRES_PASSWORD
HealthCmd=pg_isready -U forgejo
HealthInterval=30s

[Service]
Restart=always

[Install]
WantedBy=default.target

Then the app:

# forgejo.container
[Unit]
Description=Forgejo
Requires=forgejo-postgres.service
After=forgejo-postgres.service

[Container]
ContainerName=forgejo
Image=codeberg.org/forgejo/forgejo:15
AutoUpdate=registry
Network=forgejo.network
Volume=forgejo-data.volume:/data:Z
# Web UI only on localhost: the reverse proxy forwards to it
PublishPort=127.0.0.1:3000:3000
# Git over SSH, published directly
PublishPort=2222:22
Label=traefik.enable=true
Label=traefik.http.routers.forgejo.rule=Host(`git.example.org`)
Label=traefik.http.routers.forgejo.entrypoints=https
Label=traefik.http.routers.forgejo.tls.certresolver=default
Label=traefik.http.services.forgejo.loadbalancer.server.port=3000

[Service]
Restart=always

[Install]
WantedBy=default.target

Some details:

Step 6: start it

systemctl --user daemon-reload
systemctl --user start forgejo        # starts forgejo-postgres first
systemctl --user status forgejo forgejo-postgres
podman ps
journalctl --user -u forgejo -f

If a unit does not appear after daemon-reload, the generator did not like the file. Ask it directly:

/usr/libexec/podman/quadlet -dryrun -user

It prints the generated units, or the error with the file and line.

Step 7: updates with podman auto-update

AutoUpdate=registry marks a container for podman auto-update. The command checks the registry for a new image under the same tag. If there is one, it pulls it and restarts the unit. If the new container fails to start, it rolls back to the old image.

Enable the timer that ships with Podman:

systemctl --user enable --now podman-auto-update.timer
podman auto-update --dry-run          # what would be updated now

The timer runs once a day. To change that, add a drop-in:

# ~/.config/systemd/user/podman-auto-update.timer.d/interval.conf
[Timer]
OnCalendar=
OnCalendar=*:0/15
RandomizedDelaySec=0

The empty OnCalendar= clears the default first. Without it, you get both schedules.

The tag decides what an update can bring. postgres:17-alpine gets patch releases of PostgreSQL 17, never 18. A major PostgreSQL upgrade needs a dump and a restore, and I want to do that by hand. forgejo:15 is the same. I use :latest only for images where every new version is fine, for example my own website images.

Step 8: move the data

The old data was in bind mounts under /opt, owned by root and by the container’s user IDs. Rootless Podman maps IDs: UID 0 in the container is svc on the host, and UID 1000 in the container is some high number from /etc/subuid. A plain cp therefore gives the wrong owners.

podman unshare runs a command inside the user’s ID mapping. Owners then look the same as they did inside the old container:

# as root: copy the old bind mount into the new volume, owners as numbers
podman_svc() { runuser -u svc -- env XDG_RUNTIME_DIR=/run/user/$(id -u svc) podman "$@"; }
podman_svc volume create --ignore forgejo-data
mp=$(podman_svc volume inspect --format '{{.Mountpoint}}' forgejo-data)
tar -C /opt/forgejo/forgejo --numeric-owner -cf - . \
  | runuser -u svc -- podman unshare tar -C "$mp" --numeric-owner -xpf -

Do not copy a database directory this way while the database runs. For PostgreSQL I used a dump: pg_dumpall on the old host, then psql in the new container.

# on the old host
docker exec forgejo-postgres-1 pg_dumpall -U forgejo | gzip > forgejo.sql.gz
# on the new host, as svc: start with an empty database, then load the dump
systemctl --user stop forgejo
podman exec forgejo-postgres sh -c 'dropdb -U forgejo --force forgejo && createdb -U forgejo forgejo'
gunzip -c forgejo.sql.gz | podman exec -i forgejo-postgres psql -q -U forgejo -d postgres
systemctl --user start forgejo

What bit me

Check

sudo reboot
# after the reboot, without logging in as svc:
sudo -u svc XDG_RUNTIME_DIR=/run/user/$(id -u svc) systemctl --user is-active forgejo forgejo-postgres

Both say active. The containers run as svc, and nobody logged in.

Next: Traefik in front of rootless containers.

Further reading

Previous: Four servers, three distributions: why I consolidated Next: Traefik in front of rootless containers

Related content

One generic Ansible role for every app
SELinux enforcing with containers
Traefik in front of rootless containers