lerd

Lerd, a local PHP development environment

This project runs on lerd, a Podman-based PHP development environment. It is framework-agnostic: Laravel, Symfony, WordPress, Drupal, Magento, CakePHP and any custom framework are all driven by a framework definition (YAML), never by lerd hardcoding a framework's name. The lerd MCP server is available — use it to manage the environment without leaving the chat.

The MCP surface is twelve grouped tools, each driven by an action argument: site, service, db, env, runtime, worker, exec, framework, diag, logs, worktree, workspace. Always pass action. Most actions also accept an optional path that defaults to the directory the assistant was opened in (then LERD_SITE_PATH if set), so you can usually omit it. Start by calling site with action: "list" to discover sites.

Architecture

• PHP runs in Podman containers named lerd-php<version>-fpm (e.g. lerd-php84-fpm); each container includes composer and node/npm; the PHP version is resolved from .lerd.yaml → .php-version → composer.json require.php constraint (matched against installed versions) → global default
• Nginx routes *.test domains to the correct PHP-FPM container
• Services (MySQL, Redis, PostgreSQL, etc.) and custom services run as Podman containers via systemd quadlets
• Node.js versions run through a version manager, fnm (bundled, fetched on demand) or user nvm (declining managed Node picks nvm; node.manager + node.nvm_dir; node:manager/dashboard; nvm keeps PATH, fnm uses shims); per-project version via a .node-version file. The package manager is the project's, not lerd's: a packageManager pin in package.json wins, then the lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lock* → bun, else npm). pnpm and yarn run through corepack, and installs use the manager's frozen-lockfile mode (pnpm install --frozen-lockfile, yarn install --immutable, npm ci). Never assume npm run dev/npm ci — the worker command and the setup steps follow the detected manager
• Framework workers (queue, schedule, reverb, horizon, messenger, vite, etc.) run as systemd user services named lerd-<worker>-<sitename>; commands are defined per-framework in YAML; Laravel Horizon is auto-detected from composer.json and replaces the queue toggle when installed; Laravel ships with a vite host worker that runs the project's dev script on the host for HMR, through whichever package manager the project pins; workers and setup commands support optional check (file or composer) for conditional visibility; workers with conflicts_with auto-stop conflicting workers on start. Per-worker flags: host: true (run on host via the version manager instead of in FPM container — HMR-sensitive Node tools), per_worktree: true (worker runs independently per worktree under lerd-<worker>-<site>-<branch>), replaces_build: true (worker provides asset manifest while running, so a worktree add skips the static npm run build step when this worker is opted in)
• Custom workers can be added per-project (.lerd.yaml custom_workers) or globally (~/.config/lerd/frameworks/<name>.yaml); use the worker tool's add/remove actions — both survive framework store updates
• Framework setup commands (one-off bootstrap steps like migrations, storage links) are defined in the framework YAML and shown by framework action: "setup"; Laravel has built-in storage:link/migrate/db:seed; custom frameworks can define their own
• Service version placeholders ({{mysql_version}}, {{postgres_version}}, {{redis_version}}, {{meilisearch_version}}) are available in framework env vars and resolved from the service image tag at env-setup time
• Custom containers: non-PHP sites (Node.js, Python, Go, etc.) can define a Containerfile.lerd and a container: section in .lerd.yaml with a port; lerd builds a per-project image, runs it as lerd-custom-<sitename>, and nginx reverse-proxies to it; the project directory is volume-mounted at its host path with --workdir set automatically — do NOT add WORKDIR or COPY to the Containerfile; workers exec into the custom container; services are accessible by name on the shared lerd Podman network; hot-reload file watchers must use polling on macOS (inotify does not fire across Podman Machine's virtiofs mount) — nodemon: --legacy-watch, Vite: server.watch.usePolling: true, webpack: watchOptions: { poll: 1000 }
• Custom-image PHP sites (custom-FPM): a PHP project can define a Containerfile.lerd (must build FROM lerd-php<ver>-fpm:local) plus a container: section with no port; lerd builds a per-site image (lerd-custom-<site>:local), runs a dedicated FPM container lerd-cfpm-<site>, and serves it by fastcgi instead of the shared lerd-php<ver>-fpm. It is a normal PHP site otherwise (xdebug, dumps, profiler, lerd shell, php/artisan/composer/tinker, queue/horizon all run in the per-site container). The PHP version is fixed by the FROM line (the UI version selector is read-only); lerd rebuild rebuilds the image. Same key as custom containers, the port is the discriminator: with a port it is a reverse-proxied non-PHP app, without a port it is a fastcgi PHP image. runtime for these reports fpm-custom.
• Git worktrees automatically get a <branch>.<site>.test subdomain (deep *.<branch>.<site>.test wildcard cert + nginx server_name on secured sites); vendor/, node_modules/, .env are seeded from the main checkout. .lerd.yaml env_overrides declares templated env vars ({{domain}}, {{scheme}}, {{site}}) layered on the default APP_URL rewrite — for multi-tenant apps (per-branch cookies, signed-URL hosts, tenant routing)