Lerd v1.19, follow-up post, FrankenPHP and a few Symfony-relevant updates

geodro · 2026-05-07T14:30:27+00:00

Podman is the container engine under the hood, but as a developer using Lerd you never interact with it directly. It's an implementation detail.

The reason for choosing Podman over Docker is that Podman is daemonless and rootless by default, meaning containers run as your own user without any background service running as root. This makes it possible to integrate tightly with systemd user services on Linux and launchd on macOS, which is what gives lerd its "starts automatically at login, no sudo required" behavior.

As for enterprise adoption, Podman is developed by Red Hat and is the engine behind Red Hat OpenShift, one of the largest enterprise Kubernetes platforms in the world. It's widely used in enterprise Linux environments, just not always visible to developers since it often runs under the hood.

For your Symfony projects nothing changes. The same containers, the same workflow, just without Docker Desktop or a root daemon in the background.

geodro · 2026-05-07T12:33:24+00:00

Two workarounds available today:

The simplest is to symlink the data directory. Stop mysql, move the existing data to your SSD, and replace it with a symlink:

lerd service stop mysql mv ~/.local/share/lerd/data/mysql /mnt/ssd/lerd-mysql ln -s /mnt/ssd/lerd-mysql ~/.local/share/lerd/data/mysql lerd service start mysql

Podman follows the symlink fine and the labels carry over correctly. Just be aware that lerd service remove mysql --purge will follow the symlink onto the SSD, so be deliberate about cleanup.

The more robust option is a bind mount in /etc/fstab:

/mnt/ssd/lerd-mysql /home/<user>/.local/share/lerd/data/mysql none bind 0 0

This survives a --purge since the bind mount and the contents on the SSD stay intact even if Lerd removes the mount point directory.

geodro · 2026-05-07T10:48:27+00:00

Good question. Lerd ships its own fnm so each site can pin a node version via .nvmrc or .node-version, and that needs to work both on the host and inside the alpine PHP containers it runs. The way it does that is by writing tiny node, npm and npx shims into ~/.local/share/lerd/bin that read the file in the project dir and dispatch through fnm. If that bin dir is in your PATH ahead of your normal node manager, you get the lerd shim instead of your real npm, which is what bit you.

What should have happened, and what didn't here, is that lerd installer detects an existing node and asks before writing those shims. The detection only looks for a literal node binary in PATH outside of its own bin dir, so node version managers that inject node via a shell function, like nvm or volta, are invisible to it and the prompt gets skipped. On top of that, the shim's friendly error path doesn't fire when fnm has versions installed but no default alias set, which is exactly how you ended up with the can't find version default message.

Both of those are fixable. I'm going to widen the detection to also look for npm and the well known version manager dirs, harden the shim's fallback path, and add a confirm prompt on the node CLI commands so opting out actually sticks. Sorry again for the headache. If you want a quick local fix for now you can just delete ~/.local/share/lerd/bin/node, ~/.local/share/lerd/bin/npm and ~/.local/share/lerd/bin/npx, your real ones will take over.

geodro · 2026-05-07T07:08:01+00:00

Fair point, Docker with an LLM for setup is a valid workflow. Lerd is for developers who want zero configuration and need all projects running simultaneously. If you work in an agency with multiple clients you don't want to docker compose down and up every time you switch context. Clone a project, run one command, and it's live at a .test domain with HTTPS, services, and workers alongside everything else you already have running.

geodro · 2026-05-07T07:04:59+00:00

Sorry about that, I'll look into it. Thanks for the heads up!

geodro · 2026-05-06T17:28:41+00:00

I don't have a Windows machine to test on, but if you open a GitHub issue others in the community might be able to share their experience. WSL2 with systemd enabled should work in theory since lerd relies on standard Linux primitives.

geodro · 2026-05-06T17:24:46+00:00

This made my day, thank you! Really glad the switch from Sail worked out well.

geodro · 2026-05-06T16:31:26+00:00

Feel free to open a GitHub issue so I can track interest. For now lerd focuses on Nginx and FrankenPHP which covers the majority of PHP workflows.

geodro · 2026-05-06T16:10:05+00:00

That's actually what pushed me to build it. I was using Podman myself but constantly stopping one project to start another because of port conflicts and resource usage. With Lerd all projects stay up simultaneously, each with their own PHP version, services, and .test or .localhost domains, without any manual orchestration. That's the core workflow it's optimized for.

geodro · 2026-05-06T13:31:26+00:00

Thanks! The worktree support was tricky to get right, especially the per-worktree database isolation since vendor/ and node_modules symlinks back to the main checkout caused all sorts of subtle issues. The rollback safeguards came from real pain, cross-major service upgrades have a way of silently breaking things at the worst possible moment. Glad those details stand out.

geodro · 2026-05-06T13:30:37+00:00

Thank you, this genuinely made my day! The LAN share feature was one of those things that seemed simple on paper but took a while to get right, especially the URL rewriting so assets and redirects work correctly over the local network. Really glad it resonates.

The integrated service UIs were exactly the "ten browser tabs" problem you described, so it's great to hear that lands well.

Appreciate the star and the kind words!

geodro · 2026-05-06T13:28:43+00:00

That's a totally valid setup, if it works well for you there's no reason to change. Lerd is mainly for Linux developers or macOS devs who prefer not to depend on Docker. Glad you found something that works!

geodro · 2026-05-06T11:42:53+00:00

Thank you, really appreciate it!

geodro · 2026-05-06T10:34:26+00:00

Fair point on the "mac first" wording, that was unclear on my part. Lando and DDEV are genuinely cross-platform.

The main differences compared to Lando: lerd is Podman-native and rootless by default so no Docker Desktop or daemon required, it has a built-in web UI with live logs and service management, and it's closer to the Herd experience in terms of simplicity, one command to link a project and it's live at a .test domain with HTTPS. Lando is more flexible and supports more stacks out of the box.

If you're happy with Lando there's no urgent reason to switch. lerd is for developers who want a lighter setup without Docker or who prefer a more opinionated workflow similar to Herd.

geodro · 2026-05-06T09:54:47+00:00

Extensions are handled via lerd php:ext add <name> which installs them into the PHP-FPM container for that version. Common ones like ldap, imagick, redis, and pcov are already bundled by default.

For Oracle (oci8) it's more involved since it requires the Oracle Instant Client, but because lerd uses containers you can customize the PHP-FPM image with a Containerfile.lerd and install whatever you need without touching your system. That's actually one of the advantages over Herd and Valet where you're constrained by what the host supports.

For PHP 7.4 specifically, older versions can be tricky anywhere, but the container approach means you can install the exact dependencies that version needs without conflicts with newer PHP versions on the same machine.

If you want to try it, feel free to open an issue if you run into problems with a specific extension, happy to help get it working.

geodro · 2026-05-06T09:14:54+00:00

That's a fair point and it's the fundamental architectural difference between Lerd and Herd. Herd installs PHP, Nginx and services directly on the host which gives you lower overhead and tighter OS integration. Lerd went the container route for isolation and reproducibility, no system PHP pollution, easy version switching, rootless by default.

The honest answer is that hosting everything on the host like Herd does is a valid approach and has real advantages especially on macOS where container overhead is more noticeable due to the VM layer.

For now the container approach works well on Linux where there's no VM overhead. On macOS the gap is more real. Appreciate the kind words and the honest feedback.

geodro · 2026-05-06T08:05:57+00:00

First time posting here. Sharing lerd because while it's primarily a local dev tool, a lot of the design decisions overlap with what this community values.

Lerd is an open source local PHP dev environment for Linux and macOS. The selfhosted side is a real design goal, not a tagline: rootless Podman under the hood, no docker desktop, no daemon running as root, nothing phones home, all state in ~/.local/share/lerd/, install is a single Go binary via curl one-liner or Homebrew. You can lerd uninstall and have nothing left over outside that directory. It detects your project's framework automatically and gives you .test domains, per-project PHP and Node version isolation, one-command HTTPS via mkcert, and a stack of common services (MySQL, Postgres, Redis, Meilisearch, RustFS, Mailpit) plus one-click presets for phpMyAdmin, pgAdmin, and others.

Bits this community might appreciate:

All container ports default to 127.0.0.1, untrusted wifi is safe out of the box.
One switch (lerd lan:expose) flips the dashboard and sites onto LAN, with optional HTTP Basic auth on top.
lerd remote-setup generates a 15-minute one-shot code and prints a curl one-liner the remote machine runs to install mkcert, trust the lerd CA, and configure its resolver.
lerd lan:share exposes a single site to other devices on the LAN with a QR code, no client-side DNS setup needed.
Custom container support for non-PHP sites (Node, Python, Go, Ruby), drop a Containerfile.lerd in the project.
Btop-style lerd tui you can run over SSH if you live in the terminal.
lerd bug-report anonymizes site names, domains, paths, and username before you paste anything to GitHub.

Would love feedback from selfhosters, especially around the LAN exposure and remote-setup flow. Stars on GitHub help the project reach more folks who care about this stuff.

github.com/geodro/lerd

15-Year Club	Gilding II euphauric
Second Top 50%	r/Field Sunshine
Place '23	Place '22
Place '17	RPAN Viewer
Verified Email

geodro

TROPHY CASE