foxws/laravel-podman

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 an earlier major version? See UPGRADING.md.

Features

Presets for every stage

• development: your working copy mounted live, Octane with file watching, Xdebug (off until you turn it on), 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 after 10 minutes without traffic (on-demand services). Change the timeout with PODMAN_ONDEMAND_IDLE_TIMEOUT, e.g. 5min, 30min or 2h.
• The database, cache and other services sleep too, once no jobs are left.
• Works behind the bundled proxy or your own, such as a NAS or Nginx on another machine.
• Set PODMAN_ONDEMAND_ENABLED=false to keep everything 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.
• lpod also turns Xdebug on and off, and checks your host with lpod doctor.
• 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"

If you run production in these containers, install it as a regular dependency, not with --dev: the idle check runs php artisan podman:idle inside them, and production images are built without dev dependencies. If you only use it for development and deploy elsewhere, --dev is preferred. Where it is installed but shouldn't touch services, set PODMAN_ENABLED=false: podman:generate, podman:setup, podman:publish and podman:s3-setup then refuse to run. See Customizing for every config key.

[!TIP] Let your AI agent do the hard parts. This package ships Laravel Boost skills (podman-lpod, podman-presets, podman-s3 and podman-upgrade) that teach your agent how to install, configure and use Laravel Podman. Install Boost and select the skills when prompted:

composer require laravel/boost --dev
php artisan boost:install

Already using Boost? Run php artisan boost:update --discover to pick up the skills. Then just ask, for example: "Switch the database to PostgreSQL and create an S3 bucket with a CORS policy."

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. Upgrade it later with lpod self-update:

   curl -fsSL https://github.com/foxws/lpod/releases/latest/download/install.sh | bash
   

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
   lpod idle enable my-app
   

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

   lpod my-app open
   

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

For frontend work, run pnpm install and add the Vite dev server:

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

For production, also set the secrets it expects, such as your .env and the 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, Installer
• 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.