README

Laravel Podman brings Podman Quadlet support to your Laravel application. It ships a set of Artisan commands to install, list, print, and remove the Quadlet-managed services that make up your app (the application itself and sibling services such as a database, cache, or search engine), manage the Podman secrets those services need, and publish the container runtime used to build your application image.

A Sail-inspired lpod CLI script is also included for day-to-day interaction with the running containers (starting/stopping services, opening a shell, running Artisan/Composer/Node commands, and more).

Requirements

• Linux with systemd (rootless or system-wide); macOS and Windows, including WSL, are not supported
• A recent version of Podman with the quadlet CLI plugin (podman quadlet --help should work); the --application option used by podman:install requires Podman 6+
• PHP 8.4+

Installation

You can install the package via composer:

composer require foxws/laravel-podman

You can publish the config file with:

php artisan vendor:publish --tag="laravel-podman-config"

This is the contents of the published config file:

return [
    'quadlet_prefix' => env('PODMAN_QUADLET_PREFIX', env('APP_NAME', 'laravel')),

    'quadlet_uid' => env('PODMAN_QUADLET_UID'),

    'quadlet_gid' => env('PODMAN_QUADLET_GID'),

    'runtime_path' => env('PODMAN_RUNTIME_PATH', 'runtimes'),

    'config_path' => env('PODMAN_CONFIG_PATH', 'runtimes/config'),

    'selinux_volume_mapping' => env('PODMAN_SELINUX_VOLUME_MAPPING', true),

    'reload_systemd' => env('PODMAN_RELOAD_SYSTEMD', true),
];

quadlet_prefix is used to namespace the services installed for your application (for example laravel-pgsql), and defaults to your APP_NAME. quadlet_uid/quadlet_gid default to the UID/GID of the user running the Artisan command. You can also override where the package looks for Quadlet and runtime files by adding quadlets_path and runtimes_path to the config file; both default to the ones bundled with the package.

Usage

The package discovers its Quadlet service definitions (*.quadlets files) and its container runtimes (folders containing a Containerfile) on disk, and exposes them through the commands below. Every command that needs a service or runtime name will prompt you to select one interactively when it's omitted.

podman:install

Installs a Quadlet service so systemd can manage it.

php artisan podman:install pgsql

# Install into a named application subdirectory (requires Podman 6+)
php artisan podman:install pgsql --application=my-app

# Replace the service if it already exists
php artisan podman:install pgsql --replace

# Prompt for and set the secrets required by the service before installing
php artisan podman:install pgsql --secrets

podman:secret

Prompts for and sets the Podman secrets used by a service, without installing it.

php artisan podman:secret pgsql

# Replace secrets that already exist
php artisan podman:secret pgsql --replace

Secrets are read from the Secret= directives in a service's .quadlets file. type=env secrets prompt for a value directly, while type=mount secrets prompt for a file path (defaulting to your project's .env) whose contents are stored as the secret.

podman:list

Lists the Quadlets configured for the current user.

php artisan podman:list

php artisan podman:list --filter=status=running --format=json --noheading

podman:print

Prints the generated systemd unit for a service, as Podman would install it.

php artisan podman:print pgsql

podman:remove

Removes an installed Quadlet service.

php artisan podman:remove pgsql

# Force removal of a running service, ignoring missing services
php artisan podman:remove pgsql --force --ignore

podman:uninstall

Removes an application and all of its installed services in one go.

php artisan podman:uninstall my-app

php artisan podman:uninstall my-app --force

podman:publish

Publishes a container runtime (e.g. the bundled frankenphp-octane runtime) so it can be customized before you build your application image.

php artisan podman:publish frankenphp-octane

# Overwrite files that were already published
php artisan podman:publish frankenphp-octane --force

The lpod utility

The package ships a lpod CLI script, installed as a Composer binary at vendor/bin/lpod. It's a thin wrapper around podman exec and systemctl for the Quadlet services you installed with podman:install, similar in spirit to Laravel Sail's sail script. Any command it doesn't recognize is passed straight through to the podman binary.

vendor/bin/lpod SERVICE COMMAND [options] [arguments]

SERVICE is the name of a Quadlet service (e.g. your application's service, or a sibling service such as pgsql).

Shortening the vendor/bin/lpod call

Typing vendor/bin/lpod for every command gets old fast, so pick one of the following.

Add a shell alias. This resolves lpod relative to your current directory, so it keeps working correctly no matter which project you're in.

Bash or Zsh, in ~/.bashrc / ~/.zshrc:

alias lpod='[ -f vendor/bin/lpod ] && bash vendor/bin/lpod || bash "$(git rev-parse --show-toplevel)/vendor/bin/lpod"'

Fish, in ~/.config/fish/config.fish:

function lpod
    if test -f vendor/bin/lpod
        bash vendor/bin/lpod $argv
    else
        bash (git rev-parse --show-toplevel)/vendor/bin/lpod $argv
    end
end

Or install it onto your PATH. This is simplest if you're only working with a single Podman-managed application on the machine, since the symlink always points at the vendor/bin/lpod of the project you created it from:

ln -s "$(pwd)/vendor/bin/lpod" ~/.local/bin/lpod

# or, to make it available to every user on the machine
sudo ln -s "$(pwd)/vendor/bin/lpod" /usr/local/bin/lpod

Make sure the target directory (~/.local/bin or /usr/local/bin) is on your PATH. Once installed either way, the examples below can be run as lpod ... instead of vendor/bin/lpod ....

Lifecycle

lpod my-app up        # Start the "my-app" service
lpod my-app down       # Stop the "my-app" service
lpod my-app restart    # Restart the "my-app" service
lpod my-app status     # Show the status of the "my-app" service

Artisan, PHP, and Composer

lpod my-app artisan queue:work
lpod my-app art queue:work     # Alias for "artisan"
lpod my-app a queue:work       # Alias for "artisan"
lpod my-app php -v
lpod my-app composer require laravel/sanctum
lpod my-app debug queue:work   # Artisan command with Xdebug enabled
lpod my-app tinker

Node, npm, pnpm, Yarn, and Bun

lpod my-app node --version
lpod my-app npm run prod
lpod my-app npx ...
lpod my-app pnpm run prod
lpod my-app pnpx ...
lpod my-app yarn run prod
lpod my-app bun run prod
lpod my-app bunx ...

Testing

lpod my-app test               # php artisan test
lpod my-app phpunit ...
lpod my-app pest ...
lpod my-app pint ...
lpod my-app dusk                # Requires laravel/dusk
lpod my-app dusk:fails

Container CLI and binaries

lpod my-app shell        # Alias: bash
lpod my-app root-shell   # Alias: root-bash
lpod my-app bin phpstan  # Run vendor/bin/phpstan
lpod my-app run whoami   # Run an arbitrary command in the container

Other

lpod my-app open                     # Open the application URL in your browser
lpod my-app artisan podman:publish   # Publish the Podman container runtime files
lpod --help                          # Print the full list of commands

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• francoism90
• All Contributors

Disclaimer

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

The MIT License (MIT). Please see License File for more information.