From Docker Compose to rootless Podman quadlets
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:
systemctl --user start|stop|status forgejoworks as for any service.- The logs are in the journal:
journalctl --user -u forgejo. - Dependencies are plain systemd:
Requires=andAfter=. Restart=alwaysand timers come from systemd too.
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:
| Compose | Quadlet file |
|---|---|
networks: dbnet | forgejo.network |
| a volume | forgejo-data.volume, forgejo-db.volume |
| a service | forgejo.container, forgejo-postgres.container |
.env with a password | a Podman secret |
depends_on | Requires= 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:
Network=forgejo.networkrefers to the quadlet file, not to the network name. systemd then also adds a dependency on the network unit.Volume=forgejo-db.volume:...is the same for volumes.:Zgives the volume a private SELinux label. Post 4 explains:Zand:z.[Install]withWantedBy=default.targetstarts the service at boot. You cannotsystemctl --user enablea quadlet, because the unit is generated. The[Install]section does that job.- The
Label=lines are for Traefik. Compose had them aslabels:, and they stay the same. The next post sets up Traefik.
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
- The working directory.
runuser -u svc -- podman ...from a directory thatsvccannot read fails with strange errors. Run it from the root directory (cd / && runuser ...). - Containers that share a network namespace. A VPN container with other containers inside its namespace (
Network=container:gluetun) cannot be restarted on its own. Stop the dependants first, in reverse order, then start everything in order. - Files mounted into containers. An editor or Ansible replaces a file with a new inode. The container still sees the old file until it restarts. Restart the unit after you change a mounted config file.
sudo -iu svc. WithoutXDG_RUNTIME_DIR,systemctl --usersays it cannot connect to the bus. Usemachinectl shellor set the variable.
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
- podman-systemd.unit(5): the quadlet reference: every key of
.container,.volume,.networkand the other unit types. - Make systemd better for Podman with Quadlet (Red Hat blog): the reasons behind quadlets, from the people who wrote them.
- Basic setup and use of Podman in a rootless environment: subuids, storage and the limits of rootless mode.
- podman-auto-update(1): how
AutoUpdate=registrydecides to pull and how the rollback works. - podman-secret-create(1): secret drivers and how a container gets them.
- loginctl(1):
enable-linger, so that user services run without a login. - podlet: converts compose files and
podman runcommands to quadlets. A good start, but read what it writes.