Foxws
Containers · Podman Quadlet · systemd
Laravel Podman

Turn your Laravel app's config into Podman Quadlet containers systemd can manage.

Latest release
2.1.8
Requires
PHP ^8.4
Laravel
11.x / 12.x / 13.x
Runtime
Podman (Quadlet)
Licence
MIT
$ composer require foxws/laravel-podman
Get started Source ↗

Introduction

This package turns your Laravel app's config into Podman Quadlet units, which systemd then manages as containers on your host. There's no all-in-one runtime and no lock-in — swap any bundled part for your own, like Caddy for Nginx or Postgres for MySQL.

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"

You only need this package to render Quadlet units, so install it as a dev dependency and skip it in production. See Customizing for the full list of config keys.

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. Commented out by default. See Devcontainer.
proxy Caddy reverse proxy in front of the other services. Enabled by default.
s3 CORS policy for S3-compatible storage buckets.

Want a custom preset? 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. It's a small script with no dependencies — no PHP or 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. This is 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.

Working on frontend assets? Vite's dev server isn't part of the default setup — it's opt-in. Run pnpm install first, or it will crash-loop:

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

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)

lpod handles installing, listing, removing, and setting secrets — not Artisan. See Commands for the full flag reference.

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. lpod-setup, which ships alongside it, renders presets inside a disposable container for hosts that have Podman but no PHP. lpod setup is a shortcut for it. See lpod CLI.

Commands