Laravel Podman

Run your Laravel app and its services as Podman Quadlet containers, managed by systemd on your own Linux machine or server.

The package renders ready-to-use presets from your app's config: the app on Octane and FrankenPHP, a database, cache, queue worker, search, object storage, a mail catcher and a Caddy proxy. You install them with one command each. There's no all-in-one runtime and no lock-in: the output is plain Quadlet files you can read, change or replace.

Upgrading from v3? See UPGRADING.md.

Features

Presets for every stage

• development: your working copy mounted live, Octane with file watching, and an optional Vite dev server.
• production: a FrankenPHP and Octane image with your code baked in, Inertia SSR, and the queue worker and scheduler running independently of the app.
• devcontainer: a Dev Containers image for VS Code and JetBrains, with an optional AI variant (Claude Code, Codex, Laravel LSP).
• proxy: Caddy in front of everything, with HTTPS (local certificates in development, Let's Encrypt in production) and subdomains for Vite, Reverb, S3 and Mailpit.

Services included, one per category

Scale to zero

• The app starts on its first request and stops again after 10 minutes without traffic (on-demand services).
• Make that shorter or longer with PODMAN_ONDEMAND_IDLE_TIMEOUT, e.g. 5min, 30min or 2h.
• Works behind the bundled proxy or your own, such as a NAS or Nginx on another machine.
• The database, cache and other services sleep too, once no jobs are left.
• Turn it off with PODMAN_ONDEMAND_ENABLED=false to keep the app and its services running all the time.

Native to your system

• Plain systemd units that work rootless or system-wide. Services restart on failure. The proxy, the app's socket and the production workers start at boot.
• Database, cache and proxy images are pinned to a major version, and every container is set up for podman auto-update.
• Production secrets, like your .env, are stored as Podman secrets instead of files.
• SELinux-aware volume mounts, which you can turn off on hosts without SELinux.

Yours to customize

• Publish just the preset you want to change. The rest keep following package updates.
• Swap services, add your own, or set memory limits with plain Quadlet files and {{placeholders}}.
• Add your own placeholders from config/podman.php.

Tooling

• lpod, a small CLI for installing services and running Artisan, Composer, Node and tests inside your containers.
• podman:s3-setup creates your S3 buckets and applies a CORS policy.
• Render presets on a host without PHP with lpod setup.
• An example CI workflow builds and pushes a multi-arch production image.
• Laravel Boost skills, so AI agents know how to run commands in, customize and upgrade your setup.

Requirements

• Linux with systemd (rootless or system-wide). macOS, Windows and WSL aren't supported.
• Podman with Quadlet support (podman quadlet --help should work).

Installation

composer require foxws/laravel-podman
php artisan vendor:publish --tag="podman-config"

Install it as a regular dependency, not with --dev: the idle check runs php artisan podman:idle inside your production containers too. See Customizing for every config key.

Quick start

1. Render the default presets (development, ondemand and proxy):

   php artisan podman:setup
   

2. Install lpod once per host. It's a single bash script and doesn't need PHP:

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

3. Install the services. Replace my-app with your app's name (APP_NAME, kebab-cased):

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

4. Open your app. The first request starts it:

   lpod my-app open
   

5. Trust the proxy's local certificate once. See Proxy.

Working on frontend assets? Run pnpm install, then add the Vite dev server:

lpod install development/vite.quadlets --replace
lpod my-app-vite up

Deploying with production? Also set the secrets it expects, such as your .env and database password, with lpod my-app secrets and lpod my-app-pgsql secrets.

Commands

Everything else, like installing, starting, removing and setting secrets, is done with lpod:

lpod my-app artisan migrate
lpod my-app composer require laravel/horizon
lpod my-app pest
lpod my-app shell

Warning: lpod remove and lpod uninstall delete the service's Podman volumes, including databases and uploads. There's no undo. See Backing up volumes.

Documentation

The full documentation is at foxws.nl/laravel-podman:

• Getting started: Commands, lpod CLI
• Configuration: Customizing, Devcontainer, Proxy, S3 Buckets, On-demand services
• Advanced: Setting up without PHP, CI: Building a Container Image
• Reference: Comparison with Sail, Herd and others

Testing

composer test

Links

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

Credits

• francoism90
• All Contributors
• Spatie: the idle checks follow the design of spatie/laravel-health's checks

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.