Laravel Podman

Renders Podman Quadlet units from your Laravel app's config, then installs them as systemd-managed containers on your host — no all-in-one runtime, no lock-in. Swap any bundled part (Caddy for Nginx, Postgres for MySQL) for your own.

See docs/ for the full reference: Commands, Customizing, Proxy, S3 Buckets, The lpod CLI, Setting up without PHP, Comparison.

Requirements

• Linux with systemd (rootless or system-wide) — macOS, Windows, and WSL are not supported
• Podman with the quadlet CLI plugin (podman quadlet --help should work)

Installation

composer require foxws/laravel-podman --dev

php artisan vendor:publish --tag="podman-config"

Only needed to render Quadlet units — install as a dev dependency and skip it in production. See Customizing for every config key.

Presets

Preset	What it is
development	App + services, working copy live-mounted for local editing. Enabled by default.
frankenphp-octane	Production-style image, app code baked in. Commented out by default.
devcontainer	VS Code/JetBrains Dev Containers image. Enabled by default.
proxy	Caddy reverse proxy in front of the other services.
s3	CORS policy for S3-compatible storage buckets.

Custom presets: publish one (php artisan podman:publish frankenphp-octane) without touching the others — see Customizing.

Quick start

1. Render the default presets:

   php artisan podman:setup

2. Install lpod once per host — a dependency-free script, no PHP/Composer needed:

   curl -fsSL -o ~/.local/bin/lpod https://github.com/foxws/lpod/releases/latest/download/lpod
   chmod +x ~/.local/bin/lpod

3. Install each rendered service (the only step that needs podman itself):

   lpod install development/app.quadlets --replace
   lpod install development/pgsql.quadlets --replace
   lpod install development/valkey.quadlets --replace
   lpod install proxy/proxy.quadlets --replace

4. Set secrets, then start:

   lpod my-app secrets
   lpod pgsql secrets
   lpod my-app up
   lpod my-app open

Trust the proxy's local certificate once — see Proxy.

No PHP on the host? lpod setup renders the same way without it — see Setting up without PHP.

Commands reference

Command	Description
podman:setup	Generate the default set of presets in one go
podman:publish PRESET	Publish a preset for customization
podman:generate PRESET	Render a single preset
podman:s3-setup	Create S3 buckets and a CORS policy (requires aws/aws-sdk-php)

Installing, listing, removing, and setting secrets is lpod's job, not Artisan's. Full flag reference: Commands.

Warning: lpod remove/lpod uninstall delete the Podman volumes they own (databases, uploads, search indexes), with no undo — see Backing up volumes.

The lpod utility

lpod is a separate, dependency-free bash script — no PHP, Composer, or this package required to run it:

curl -fsSL -o ~/.local/bin/lpod https://github.com/foxws/lpod/releases/latest/download/lpod
chmod +x ~/.local/bin/lpod

lpod SERVICE COMMAND [options] [arguments]

lpod my-app up
lpod my-app artisan queue:work
lpod my-app shell

lpod install development/app.quadlets --replace
lpod my-app secrets

This package ships one Composer binary, vendor/bin/lpod-setup, which renders presets inside a disposable container for hosts with Podman but no PHP. lpod setup is a shortcut for it — copy bin/lpod-setup next to wherever lpod lives on your PATH.

Full command reference, shortening the call, and tips & tricks: foxws/lpod.

Testing

composer test

Links

• CHANGELOG
• Security policy
• foxws/lpod — the CLI this package pairs with
• Podman Quadlet reference

Credits

• francoism90
• All Contributors

AI, specifically Claude, was used to help build this package. All AI-assisted output is reviewed by me, and I retain final say over everything that is implemented and released.

License

MIT. See License File.