Rootless podman installation

This is a guide on how to install cradle-cms as a rootless podman systemd service on a DietPI distro. DietPI is a bare minimal debian installation mainly targeted for SBC:s but it works on PC:s and laptops as well.

We also show how utilise podman auto-update in order to automatically update cradle-cms.

Install latest podman and required dependencies

The curse of many debian based distros is that they are far behind the latest software versions. In this case we need podman v5.8+ but it’s not available in the package sources. To overcome that we install podman from debian unstable.

Add debian unstable and set it as a low priority source.

echo "deb https://deb.debian.org/debian unstable main contrib" >> /etc/apt/sources.list
cat << EOF
Package: *
Pin: release o=debian, a=unstable
Pin-Priority: 300
EOF >> /etc/apt/preferences
apt update

Now you can install podman from unstable along with the dependencies we need.

apt install podman -t unstable dbus-user-session passt polkitd uidmap slirp4netns

After installation you should test to reboot the system.

reboot

Create a non root user

We want a rootless podman that runs as a cradle user.

adduser cradle
# give user access to journalctl
usermod -a -G systemd-journal cradle
# setup podman user runtime directory
mkdir -p /run/user/$(id -u cradle)
chown -R cradle:cradle /run/user/$(id -u cradle)
# allow cradle user to linger
systemctl unmask systemd-logind.service
systemctl start systemd-logind.service
loginctl enable-linger cradle

Instead of password login you should use ssh authorized_keys

Login as the cradle user

ssh cradle@your.server.ip
# setup XDG_RUNTIME_DIR needed by podman
echo '[ -z "${XDG_RUNTIME_DIR}" ] && export XDG_RUNTIME_DIR=/run/user/$(id -ru)' >> .profile
# logout 
exit

Verify podman and configure registry.cradlecms.com

ssh cradle@your.server.ip
# check that you have a working podman and that the version is `v5.8` (or better)
podman -v
# login to the registry using your licensekey and account password
# we store the authentication in `auth.json` as it's needed for automatic updates 
podman login --authfile /home/cradle/.config/auth.json registry.cradlecms.com/cradle-cms
# test that pulling from the registry using the `auth.json` actually works
podman pull --authfile /home/cradle/.config/auth.json registry.cradlecms.com/cradle-cms:latest

Create container configuration

This is a basic configuration which uses a self signed certificate for https. If you want to utilise a letsencrypt certificate for your own domain name then change Environment=ACME=false to Environment=Domain=your.domain.name and set published port to PublishPort=443:4040 and PublishPort=80:8080.

Create the container configuration directory if it doesn’t exist.

mkdir -p /~.config/containers/systemd

Create the service container file ~/.config/containers/systemd/cradle-cms.container

[Unit]
Description=Cradle CMS

[Container]
Image: cradle-cms.image
ContainerName=cradle-cms
Environment=ACME=false
PublishPort=4040:4040
PublishPort=8080:8080
Volume=storage:/storage
AutoUpdate=registry

[Service]
Restart=always

[Install]
WantedBy=default.target

Create the service image file ~/.config/containers/systemd/cradle-cms.image

[Image]
Image=registry.cradlecms.com/cradle-cms:latest
AuthFile=/home/cradle/.config/auth.json

We do recommend you pin the version number instead of using :latest, so change it to the latest available feature release you want like :0.14. And if you don’t want automatic updates / fixes you may want to pin the version to something like :0.14.1.
You may even use :test to get access to new features, it updates multiple times per week.

You can bake the above files into a single .quadlets file and use podman quadlet install cradle-cms.quadlets and podman generates the above files we just created.

Start the cradle-cms service

systemctl --user daemon-reload
# check that the cradle-cms.service has been generated
systemctl --user cat cradle-cms
# start the container
systemctl --user start cradle-cms
# check the service status
systemctl --user status cradle-cms
# start the auto update timer
systemctl --user enable --now podman-auto-update.timer

The auto update timer is by default set to daily updates. If you want to schedule that more specifically you need to override the timer configuration.

# override the auto update OnCalendar timer
systemctl --user edit podman-auto-update.timer
# Insert the following lines to run podman auto update daily at 4am.
[Timer]
OnCalendar=
OnCalendar=*-*-* 04:00:00

And finally, reboot the server to ensure the service starts up automatically as expected.

Troubleshooting

Since there are many linux distributions and they work a bit differently, you probably need to adapt this setup a bit. The most common problem is due to missing dependencies or various permission errors caused by file ownership or missing directories.

If you have issues with service not found when trying to start the service it’s most likely caused by errors in the podman quadlet files. Validate the service generation using /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun and correct the issues. Then run systemctl --user daemon-reload to invoke the podman system generator which produces a systemd service.

You may also check with journalctl --user -u cradle-cms to see log output for the service.