Skip to main content

Introduction

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.

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​

PresetWhat it is
developmentApp + services, working copy live-mounted for local editing. Enabled by default.
frankenphp-octaneProduction-style image, app code baked in. Commented out by default.
devcontainerVS Code/JetBrains Dev Containers image. Commented out by default. See Devcontainer.
proxyCaddy reverse proxy in front of the other services. Enabled by default.
s3CORS 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.

Working on frontend assets? Vite's dev server is opt-in, not part of the default bundle (it needs pnpm install run first, or it'll 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​

CommandDescription
podman:setupGenerate the default set of presets in one go
podman:publish PRESETPublish a preset for customization
podman:generate PRESETRender a single preset
podman:s3-setupCreate 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. 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. See lpod CLI.