Uptime Kuma on Fedora with Podman Quadlet

Over the weekend, I decided to set up Uptime Kuma on my mini-server. I needed a quick way to monitor some important work services, and Uptime Kuma’s Slack notifications make it easy to get alerts directly in our channel whenever something goes down.

While I was at it, I figured it was the perfect time to learn Podman Quadlet. I have recently learned as a neat way to manage containers using declarative files (similar to Kubernetes YAML) that automatically generate systemd services so your apps start at boot and stay running.

Installing Podman

First, make sure Podman is ready to go. On my Fedora machine, that’s just a quick:

sudo dnf update -y && sudo dnf install podman -y

Project Organization

I like to keep my tools organized under an infrastructure directory.

mkdir -p ~/infrastructure/uptime-kuma/data
cd ~/infrastructure/uptime-kuma

We’re creating a data directory here to mount as a volume so our Uptime Kuma configuration persists even if the container restarts.

Handling SELinux Permissions

Since Fedora is strict about security, you need to tell SELinux that the container is allowed to write to your local data folder.

chcon -t container_file_t -R ~/infrastructure/uptime-kuma/data

Using :Z in a YAML hostPath isn't standard K8s syntax (unlike what we commonly find in Docker Compose files), so this manual chcon approach is a reliable way to ensure the container has write access.

Creating the Kubernetes YAML

Next, create a file named uptime-kuma.yaml. This defines the pod and the container.

apiVersion: v1
kind: Pod
metadata:
  name: uptime-kuma-pod
spec:
  containers:
  - name: uptime-kuma
    image: lscr.io/linuxserver/uptime-kuma:latest
    ports:
    - containerPort: 3001
      hostPort: 3001 ## You can change this port
    env:
    - name: TZ
      value: "Asia/Manila"
    volumeMounts:
    - mountPath: /app/data
      name: kuma-data
  volumes:
  - name: kuma-data
    hostPath:
      path: /home/jantolentino/infrastructure/uptime-kuma/data ## Change this path
      type: Directory

Moving to Quadlet (Systemd Integration)

Instead of just running podman kube play, we’ll use a Quadlet .kube file. This tells systemd to manage the Kubernetes YAML we just wrote.

First, create the Quadlet directory if it doesn't exist:

mkdir -p ~/.config/containers/systemd

Now, create a file named uptime-kuma.kube inside that folder:

[Unit]
Description=Uptime Kuma Service
Wants=network-online.target
After=network-online.target

[Kube]
## Path to your Kubernetes YAML
Yaml=/home/jantolentino/infrastructure/uptime-kuma/uptime-kuma.yaml

[Install]
WantedBy=default.target

Activating the Service

The awesome part is that when you reload the systemd daemon, Podman’s Quadlet generator sees your .kube file and creates a real systemd service automatically.

## Refresh systemd to find the new Quadlet
systemctl --user daemon-reload

## Start and enable the service
systemctl --user enable --now uptime-kuma.service

Enable "Linger"

By default, "user" services stop when you log out. Since this is a server, we want it to run 24/7 even without an active SSH session. Use the loginctl command to enable "lingering":

loginctl enable-linger jantolentino

Now your Uptime Kuma instance will start automatically as soon as the server boots up. No more manual starts needed!