Laravel Podman Laravel Package

Getting Started

foxws/laravel-podman is a Podman-based local development environment for Laravel — conceptually the same slot as Sail, but driven by Podman instead of Docker. Release 6.0.1 is a patch release on the 6.0 line and does not change the onboarding path.

Minimal setup:

1. Install as a dev dependency (composer require --dev foxws/laravel-podman) and run the installer/publish command the package exposes (php artisan list | grep podman shows the exact set, typically something like podman:install/podman:init).
2. Publish and read config/podman.php first — this is where the preset, service definitions, ports, volumes, and idle-check behaviour live. It is the single most important file to understand before touching anything else.
3. Inspect the generated compose file (compose.yaml / docker-compose.yml) and confirm it matches the services your app actually needs (mysql/pgsql, redis, mailpit, etc.).
4. Bring the stack up and verify: containers running, app reachable, php artisan migrate working from inside the container.

First real use case: replace an existing Sail/Docker Compose setup for a standard Laravel app on a Linux workstation. Get podman:up → HTTP request → podman:artisan migrate working end-to-end before customising anything. If you are on a host without lpod (the author's Podman CLI helper, e.g. apps scaffolded with laravel-installer), pay attention to the ondemand preset specifically — 6.0.1 exists to keep that path working.

Implementation Patterns

Preset selection is the primary decision. The package ships presets (at minimum a default always-on preset and an ondemand preset) configured in config/podman.php and typically overridable via .env. Choosing ondemand is the right call for laptops and low-spec dev machines: services start on demand and idle workers are stopped after a period of inactivity rather than running all day. Choosing the default preset is the right call for CI, shared dev hosts, or anyone who finds socket activation surprising.

Day-to-day loop. Keep the workflow inside the container to avoid host/container PHP drift: run artisan, composer, phpunit, and node through the package's exec wrappers rather than on the host. Tail logs per service when debugging boot failures instead of guessing. Treat podman:down / podman:up as the reset button when state gets weird — rootless Podman volumes and networks occasionally survive a stopped container in ways that confuse you.

How the ondemand idle check actually works (post-6.0.1). The idle check is now gated on the app's ondemand.socket being active — the same condition lpod idle uses. Two practical consequences:

• The socket is the thing that both wakes services and authorises the idle check to stop them. If you disable or stop the socket unit, you should not expect ondemand teardown to behave normally.
• The idle check now only stops workers the app actually defines. Previously it could log errors about workers that don't exist (e.g. you have no Horizon, no queue workers, or you removed a worker from config). Those spurious error lines are gone — so absence of "worker stopped" style logs is now normal and not a sign the idle check isn't running.

Worker/queue integration. If you use Horizon or a queue worker container, ensure the worker is declared in the package config so the idle check knows about it. Conversely, if you don't run workers at all, 6.0.1 makes the ondemand preset clean out of the box — no config gymnastics needed to silence warnings.

CI and parity. Use the same config for local and CI where possible, but switch presets: default/always-on in CI so there are no timing assumptions about socket activation, ondemand locally. Pin service image tags in config/podman.php so local and CI don't silently drift.

Extending the stack. Add extra services (Meilisearch, MinIO, a second database) by editing the package's service config or layering a compose override, and prefer bind-mounting your app code with the correct SELinux label (:z/:Z) on Fedora/RHEL-family hosts.

Gotchas and Tips

• 6.0.1 is a safe patch upgrade. No breaking changes, no deprecations, no config keys renamed. Update and move on. The only behavioural delta is the gating of the idle check and the suppression of "worker doesn't exist" errors — if anything in your tooling greps logs for those errors, that tooling is now broken, not the package.
• Silent idle check is a feature, not a failure. After upgrading, if you previously used the presence of idle-check log lines as a liveness signal, replace that with an explicit check (socket unit status, container state) rather than log scraping.
• Hosts without lpod are the reason this preset still has its own idle check. If you're on such a host (common with laravel-installer-scaffolded apps), don't "simplify" by removing the idle check from your fork or config — it's the only thing stopping the ondemand stack from idling forever.
• Symptom → cause map for the ondemand preset: containers never stop ⇒ socket not active, or idle timeout not yet elapsed, or no workers declared to stop. Containers stop at a bad moment ⇒ idle timeout too aggressive for your edit-test loop; raise it or use the always-on preset while actively working on queue code.
• Rootless Podman friction is the most common source of confusion, not this package: privileged ports, UID mapping on bind mounts (files created in-container owned by a subuid), and SELinux volume labels. Debug with podman ps -a and podman logs <service> before assuming the config is wrong.
• Config is the extension point. Almost all customisation — extra services, resource limits, env passthrough, idle timings — belongs in config/podman.php (and its env overrides), not in ad-hoc podman run commands that bypass the package and don't survive a teammate cloning the repo.
• Version-pin in composer.json if you have a customised setup. The 6.x line is actively iterating on socket/idle semantics; a ^6.0 constraint with a hand-edited fork or override file is how you end up debugging behaviour that was fixed two patches ago.