maggesandClaude Sonnet 5
7f6fcb9166
Root cause of a fresh-install "cannot reach the Podman API socket" report (a friend's Unraid box, cache pool present and mounted): unlike Docker-for-Unraid's docker.img path, this plugin never auto-created STORAGE_PATH itself — only podman.img inside it. A perfectly normal, already-mounted cache pool still failed preflight/storage-create with "does not exist", just because its own .../system/podman subdirectory had never been created. Fixed by walking up to the nearest existing ancestor and checking whether it's on a different device than / (real mount vs. nothing mounted at all) — see podman-common.sh's new podman_path_has_real_mount_ancestor(), used by both podman-preflight.sh and podman-storage.sh. Settings gets a "Podman Service" card (status chip + Start/Restart, backed by new ajax/settings.php service_status/start/restart actions that just shell out to rc.podman) so a fresh install that failed to start can be diagnosed and retried without SSH/terminal access at all — exactly what was missing when this was first needed live. Also adds "Format a Disk for Podman Storage" (new ajax/disks.php) for a single-disk system with no cache pool at all. Only ever lists disks with literally no existing partition/filesystem/RAID-or-ZFS-membership signature and that aren't Unraid's boot flash — found live, twice, during development: the boot USB (FAT, labeled "UNRAID") passed the initial mounted-only check because this host's /boot is backed by a ZFS dataset rather than a direct partition mount, and active RAID-member cache disks passed a data-vs-blank *warning* rather than a hard exclusion. Both are now excluded outright, not just flagged — see disks.php's device_or_children_labeled_unraid() and the hasData exclusion in list_candidate_disks(). A disk formatted this way is remounted by UUID on every boot via a new plugin/sbin/podman-mount-managed-disk.sh, called from plugin/event/disks_mounted before rc.podman start. Unrelated fix bundled in: scripts/lib/slackbuild-common.sh now sets SOURCE_DATE_EPOCH (derived from the repo's last commit) before calling makepkg, so two separate builds of the same commit produce byte-identical .txz files — makepkg already supports this (`--clamp-mtime` when $SOURCE_DATE_EPOCH is set, confirmed by reading a real host's /sbin/makepkg) but nothing was setting the variable, so release.yml's "rebuild in CI and verify it matches the committed checksums" step was guaranteed to fail on the first package it checked alphabetically (observed live: aardvark-dns). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
webui/
Dynamix-style WebUI pages, following Unraid's plugin GUI convention of
/usr/local/emhttp/plugins/<name>/. webui/plugins/podman/ is staged to
that path by the unraid-podman scaffolding package (see
packages/unraid-podman/unraid-podman.SlackBuild), which podman.plg installs
alongside the other ten packages.
Status: implemented, covering all ten sections from docs/ARCHITECTURE.md, section 18: Dashboard, Containers, Pods, Images, Volumes, Networks, Logs, Terminal, Compose, Settings. Not yet exercised against a real Unraid/Podman install — see docs/ROADMAP.md for what "implemented" does and doesn't cover yet.
webui/mockups/prototype.html is the static, non-PHP clickable mockup this
implementation was built against — kept as the visual reference; it is not
staged into the package.
Structure
webui/
├── mockups/
│ └── prototype.html # static approved mockup, not shipped
└── plugins/
└── podman/
├── Podman.page # page shell: header, sub-nav, one container per panel
├── include/
│ ├── PodmanClient.php # libpod REST API client (talks to podman.sock only)
│ ├── Config.php # reads podman.cfg (mirrors podman-common.sh)
│ ├── bootstrap.php # shared include + error handling for ajax/*.php
│ └── helpers.php # formatting + JSON-response helpers
├── ajax/ # one endpoint per resource, each require()s bootstrap.php
│ ├── containers.php # list/start/stop/restart/remove/logs
│ ├── pods.php
│ ├── images.php
│ ├── volumes.php
│ ├── networks.php
│ ├── exec.php # Terminal — see its header comment for API scope
│ ├── compose.php # Compose — the one deliberate CLI exception, see header
│ ├── settings.php # plugin's own config, not a libpod resource
│ └── system.php # Dashboard aggregation
├── javascript/
│ ├── app.js # shared AJAX helper + sub-tab router
│ └── <panel>.js # one module per panel, registers with app.js
├── styles/podman.css # design tokens ported 1:1 from the mockup
├── event/ # official Unraid array-event hooks (see plugin/event/)
└── images/ # plugin icon assets
Design constraints (see ARCHITECTURE.md for full rationale)
- Every panel talks to
podman system serviceover its Unix socket viaPodmanClient— noexec()/shell_exec()of thepodmanbinary anywhere ininclude/or in the Containers/Pods/Images/Volumes/Networks/ Logs endpoints. - Two documented, deliberate exceptions, not oversights:
ajax/exec.php(Terminal) uses the real exec REST API, but as one-command-in/output-out rather than a true interactive PTY — libpod's interactive exec needs a persistent hijacked connection that doesn't fit PHP-FPM's request lifecycle. See that file's header comment.ajax/compose.php(Compose) shells out to thepodman composeCLI viaproc_open()with an argv array (never a shell string) — because no REST endpoint for Compose exists in libpod at all. See that file's header comment.
- The API socket is root-equivalent; no unauthenticated network exposure beyond what Unraid's own WebUI auth already provides — see .github/SECURITY.md.
- Dark/light mode via CSS custom properties (
prefers-color-scheme+[data-theme]override), matching Unraid's own theme mechanism — no separate theme toggle inside the plugin page.