[Feature Request]: Improve Podman + Quadlet Deployment Documentation / Examples

[LeeNX]

Describe the feature you would like to see

First, thanks for the great project!Dozzle has been very lightweight and useful for quickly viewing container logs.

I’ve recently been testing deployments using Podman instead of Docker, specifically with Quadlet-based systemd units, and noticed there is currently limited guidance/examples around this workflow, thou this might also be my lack of knowledge.

Request
Would the project be open to:

• Additional Podman deployment documentation
• Official examples for Quadlet .container files
• Notes about compatibility differences vs Docker Compose
• healthcheck recommendations for Podman environments
• Examples for rootless deployments and socket handling

While basic setups work, there are a few areas where Podman behaves differently from Docker, especially around:

• healthcheck execution
• podman-compose
• rootless socket permissions
• networking differences
• systemd integration through Quadlet

I think having some documented examples would help users who are moving toward systemd-native container management.

Describe how you would like to see this feature implemented

Contribution Offer

If this would be useful to the project, I’d be happy to help contribute:

• sample Quadlet .container files
• Podman deployment examples
• documentation updates
• troubleshooting notes from testing

Before I start working on anything, I wanted to check whether:

1. Podman/Quadlet support is something the maintainers are interested in documenting officially?
2. A PR adding Quadlet examples would be welcome?

Thanks again for the project!

Describe any alternatives you've considered

No response

[amir20]

Any improvements to the documentation is welcomed. I would actually try to redo https://dozzle.dev/guide/podman. I don't use Podman so I haven't had a chance to do it myself.

[LeeNX]

I am happy to add my insights and what has worked for me, thou I am not podman guru.

I will fork an make some small changes and we can see if the improvements are helpful.

Thanks.

[LeeNX]

Thanks @amir20, I understand you don't have podman to test with, so the following questions are meant for anybody else that might have info or knownledage about podman tooling.

I have a wide selection of running systems, mostly for testing and homeLabbing, using the attached screen as reference.

Can dozzle detect the container service, docker vs podman? If it possible, could dozzle use the podman icon in the host title? Should I open a feature/bug report for this icon?

Podman has a number of ways to run containers: cli, compose and quadlets, each seems to have different features/compatibility obstacles, if we can confirm these and possible note them under the FAQ, would make smoother onboarding for new users.

cylon is started using podman-compose and seems to have full access to the podman services in user's namespace, including memory and logging details, but podman-compose services don't start by themselves like it does with docker. The recommend way to have podman services start with a booting server is to switch to podman quadlets, but this has a number of different limitation or wrap it with a systemd service.

hela and lokki are using podman quadlets, which seems not to have access to memory usage, easy enough to note in the FAQ, if this is a limitation or it could be something I am doing wrong.

Podman seem only able to access containers it the user's namespace. Seems that the root user can't see the other users containers, again, could be my podman knowledge.

Healthchecks don't seem to be working or reported correctly with podman, but seems to work fine on docker.
with cylon using compse.yml:

    healthcheck:
      test: ["CMD", "/dozzle", "healthcheck"]
      interval: 3s
      timeout: 30s
      retries: 5
      start_period: 30s
      start_interval: 5s

doing leet@cylon:/opt/podman.d/dozzle$ podman-compose ps

CONTAINER ID  IMAGE                          COMMAND     CREATED            STATUS                        PORTS                   NAMES
4cd0a0bcd2f4  ghcr.io/amir20/dozzle:v10.5.3              About an hour ago  Up About an hour (unhealthy)  0.0.0.0:3080->8080/tcp  dozzle_dozzle_1

but running the healthcheck manually, seems to report healthy

leet@cylon:/opt/podman.d/dozzle$ podman-compose exec dozzle /dozzle healthcheck
podman-compose version: 1.0.6
['podman', '--version', '']
using podman version: 4.9.3
podman exec --interactive --tty dozzle_dozzle_1 /dozzle healthcheck
{"level":"info","version":"v10.5.3","address":":8080","base":"/","time":"2026-05-17T09:36:23Z","message":"Making HTTP request to server"}
{"level":"info","version":"v10.5.3","url":"http://localhost:8080/healthcheck","time":"2026-05-17T09:36:23Z","message":"performing healthcheck"}
exit code: 0
leet@cylon:/opt/podman.d/dozzle$ echo $?
0

Looking forward to any feedback and suggestions, thanks.

[amir20]

Thanks for the detailed write-up — happy to take a PR on the docs. Some answers inline so we can decide what actually belongs in the guide:

Detecting Podman / using a Podman icon
Dozzle just talks to a Docker-compatible socket, so today it can't tell them apart. /info does return Name: "podman" (or similar) on Podman's socket though, so detection is feasible. Open a separate feature request for the icon — happy to look at it but I'd rather not bundle it with the docs PR.

Quadlet vs podman-compose vs CLI
A short compatibility table in the guide would be great. From what you're reporting it sounds like:

• podman-compose: works, but doesn't auto-start on boot (Podman limitation, not Dozzle's).
• Quadlet: recommended for boot-persistence; memory stats appear missing.
• Rootless: only sees containers in the same user namespace — that's Podman by design.

Missing memory with Quadlet
Almost certainly a cgroups v2 / rootless delegation issue rather than Dozzle. Worth checking systemctl --user status and whether memory is in the delegated controllers (cat /sys/fs/cgroup/user.slice/user-\$(id -u).slice/cgroup.controllers). If memory isn't delegated, neither Podman nor Dozzle can read it. A FAQ note pointing at this would help.

Healthcheck reported as unhealthy
Podman doesn't run healthchecks automatically the way Docker does — they need a systemd timer (Quadlet generates one) or podman healthcheck run. With podman-compose the timer often isn't created, so the status stays stale even though manual runs pass. This is a Podman behavior to document, not something Dozzle can fix.

For the PR, I'd suggest:

1. Rewrite guide/podman.md with rootful + rootless socket examples.
2. Add a Quadlet .container example.
3. Short FAQ: memory stats / healthchecks / cross-user visibility.

Open the PR whenever — I'll review.

[amir20]

Also moving this to discussion as more people would look there.

[LeeNX]

Detecting Podman / using a Podman icon - #4712

Still tracking down notes to add to the docs, found some interesting info about healthchecks with podman, seems to be a bug or over sight, where all healthchecks are always run with sh, which is not in the dozzle container image. podman-compose version 1.5.0 has this corrected.

healthchecks for quadlets should be as follows

HealthCmd=CMD /dozzle healthcheck
HealthInterval=5s
HealthTimeout=10s
HealthRetries=5
HealthStartPeriod=15s

Which then does not try and use sh.

At least I am seeing that the pod is healthy, but I am not seeing this in dozzle UI, yet? ;-)

leet@hela:/opt/podman.d/dozzle-agent $ podman ps
CONTAINER ID  IMAGE                             COMMAND               CREATED       STATUS                 PORTS                                                                                   NAMES
1d988ff940f1  ghcr.io/amir20/dozzle:latest      agent                 31 hours ago  Up 31 hours (healthy)  0.0.0.0:7007->7007/tcp, 8080/tcp                                                        systemd-dozzle-agent

I will try and make a PR for the docs with these notes as suggested and information found, unless somebody beats me too it.

[amir20]

That also happens in Docker. docker/cli#3719

AFAIK, it should work with compose. I am not sure what the equivalent solution to compose in podman.

[LeeNX]

Do you mean the missing healthy tick in the UI?

[LeeNX]

In the compose file, should be something like

    healthcheck:
      test: ["CMD", "/dozzle", "healthcheck"]

thou I think the short-cut, which expects a shell, would look like (wrong/broken)

    healthcheck:
      test: "/dozzle healthcheck"

[LeeNX]

Made a PR for the podman guide - #4722

[LeeNX]

Thanks @amir20 , nice catch on my embarrassing copy-and-paste from an old test quadlet container files code-snippets. How I did that I don't know.

Further testing on podman and missing stats like memory, I have a mix of devices: cylon is amd64 (x86-64 - ubuntu 24.04), lokki is arm64 (Raspberry Pi4 - upgrade to debian/trixie) and hela is arm64 (Raspberry Pi5 - deployed with debian/trixie), means these setups can be a little different in very small ways.

Basically, I am saying that I think I can add a little more info for podman and memory metrics collection, thou I think we might just need to note that it's experimental and should be tested and not blindly applied to a deployment.

As in my amd64 podman install seem to have memory metrics enabled vs the arm64 did not and needed a boot kernel change, which could have a performance penalty or some other problem.

I used the following two articles as helpful info https://oneuptime.com/blog/post/2026-03-18-fix-cgroup-v1-v2-issues-podman/view and https://oneuptime.com/blog/post/2026-03-18-use-cgroups-v2-rootless-podman/view

thou not complete info to get the memory sorted on the Raspberry Pi devices.

Just for the info, had to added the following to /boot/firmware/cmdline.txt

cgroup_enable=memory cgroup_memory=1

and rebooted the device.

Further investigation and confirmation this always works.