Introduction

This package turns your Laravel app's config into Podman Quadlet units. systemd runs them as containers on your host. Every bundled part can be swapped for your own, like Nginx instead of Caddy or MySQL instead of Postgres.

Requirements

• Linux with systemd, rootless or system-wide. macOS, Windows and WSL are not supported.
• Podman with the quadlet CLI plugin. Check with podman quadlet --help.

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 all config keys.

If you use Laravel Boost, run php artisan boost:install (or boost:update) after installing. Your AI agent then gets skills for lpod, presets, S3 setup and upgrading.

Presets

Preset	What it is
development	App and services, with your working copy mounted for local editing. Enabled by default.
production	FrankenPHP and Octane image with the app code baked in, for servers. Commented out by default.
devcontainer	Dev Containers image for VS Code/JetBrains. See Devcontainer. Commented out by default.
ondemand	Socket that starts the app on its first request, so it and its services can sleep when idle. See On-demand services. Enabled by default.
proxy	Caddy reverse proxy in front of the other services. Enabled by default.
s3	CORS policy for S3-compatible storage buckets.

To change a preset, publish it with php artisan podman:publish production. See Customizing.

Quick start

1. Render the default presets:

   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 rendered services:

   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
   

   Replace my-app with your app's name (APP_NAME, kebab-cased).

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

   lpod my-app open
   

   The app starts on its first request and stops again after 10 minutes without traffic. See On-demand services to change that, or to keep it running with PODMAN_ONDEMAND_ENABLED=false.

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

For frontend work, install the Vite dev server too. Run pnpm install first, or it will keep crashing and restarting:

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.

To render presets on a host without PHP, see Setting up without PHP.

Commands

Command	Description
podman:setup	Render the default presets
podman:publish PRESET	Copy a preset into your project so you can edit it
podman:generate PRESET	Render a single preset
podman:s3-setup	Create S3 buckets and a CORS policy (needs aws/aws-sdk-php)
podman:idle	Succeed when the app has no work in progress. The idle check runs it

Everything else (installing, starting, removing, secrets) is done with lpod. See Commands for all flags.

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

Links

• CHANGELOG
• foxws/lpod
• Podman Quadlet reference
• Flatpak-packaged editors