docs(284): gotchas 9 + 10 from the first real podman workload - #300
Merged
Conversation
Phase 0 was proven on a throwaway host with a hello-world quadlet. Deploying an
actual service (Leapmotor Mate, CT 6004) surfaced two more, both quadlet-authoring
rules rather than engine bugs:
9. Podman does NOT create missing bind-mount source directories — Docker does.
With Restart=always this is a crash loop ending in "start request repeated too
quickly". Fix with [Service] ExecStartPre=mkdir -p, which also makes the unit
self-sufficient ahead of a data migration.
10. HealthCmd cannot carry a quoted command at all. Quadlet rejoins systemd's
word-split value, destroying inner quoting however it's written: bare quotes
give podman an unterminated string, escaped \" survive literally. The nasty
part is the failure mode — the container sits permanently "unhealthy" while
the app serves HTTP 200, so monitoring keyed on health status lies. A
healthcheck must be quote-free; if it can't be (python one-liner, because the
image ships no curl/wget), drop it or render a script and call it quote-free.
Also records that #5/#6/#9/#10 are author rules nothing enforces yet — the
candidate for validate-time enforcement.
Refs #285, #284
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #294, from Phase 1 (#285, Homelab.Stacks.SmartHome#4).
Phase 0 proved the platform on a throwaway host with a hello-world quadlet. Deploying an actual service (Leapmotor Mate on CT 6004) surfaced two more gotchas — both quadlet-authoring rules rather than engine bugs, which is why the throwaway didn't catch them.
9. Podman does not create missing bind-mount source directories
Docker does; podman refuses with
Error: statfs …: no such file or directory. Combined withRestart=alwaysthat's a crash loop ending instart request repeated too quickly— six restarts in under two seconds. Fix is[Service] ExecStartPre=/usr/bin/mkdir -p …, which also makes the unit self-sufficient ahead of a data migration.10.
HealthCmdcannot carry a quoted command — at allQuadlet rejoins systemd's word-split value, so inner quoting is destroyed however it's written. Both forms verified broken live:
HealthCmd=python -c "…'http://…'…"/bin/sh: Syntax error: Unterminated quoted stringevery 30sHealthCmd="python -c \"…\""The dangerous part is the failure mode: the container sits permanently
unhealthywhile the app serves HTTP 200, so anything keyed on health status reports a lie. A healthcheck must be quote-free; if it can't be (a python one-liner, because the image ships nocurl/wget) then either drop it and rely onRestart=always, or render a script and call it quote-free — the latter needs the provisioner to render non-quadlet assets, which is a platform change.Doc-only. Also notes that #5/#6/#9/#10 are author rules nothing enforces yet — the candidate for validate-time enforcement.
🤖 Generated with Claude Code