Lerd

Appearance

HTTPS / TLS ​

Lerd uses mkcert, a locally-trusted CA that your browser will accept without warnings.

NOTE

HTTPS is only available when lerd is managing DNS. If you installed in disabled-DNS mode (dns.enabled: false, sites under *.localhost), the mkcert root CA was never installed, the lerd init wizard skips the "Enable HTTPS?" question, the per-site HTTPS toggle in the dashboard becomes a muted lock icon, and lerd secure refuses with HTTPS requires lerd-managed DNS, set dns.enabled: true and re-run lerd install. A project whose committed .lerd.yaml carries secured: true is linked over http on a disabled-DNS install rather than registered as a non-functional HTTPS site. See DNS for the toggle and how to switch back.

bash
cd ~/Lerd/my-app
lerd secure
# Issues a cert for my-app.test, regenerates the SSL vhost, reloads nginx
# Updates APP_URL=https://my-app.test in .env if it exists
# Updates secured: true in .lerd.yaml if it exists
# Visit https://my-app.test with no certificate warning

lerd unsecure
# Removes the cert, switches back to HTTP vhost
# Updates APP_URL=http://my-app.test in .env if it exists
# Updates secured: false in .lerd.yaml if it exists

HTTPS can also be enabled during lerd init or lerd setup, the wizard asks the question upfront and applies it as part of the configuration step.

Certificates are stored in ~/.local/share/lerd/certs/sites/.

From the Web UI ​

The Sites tab has an HTTPS toggle per site; clicking it runs lerd secure or lerd unsecure inline and updates the vhost without touching the terminal. If .lerd.yaml exists in the project, the secured field is updated there too so the state is preserved for future lerd init runs.

Git worktrees ​

When a site has git worktrees, securing the parent automatically enables HTTPS for all its worktrees too. The parent's certificate is issued with *.myapp.test to cover worktree subdomains. When a new worktree is created on a secured site, the certificate is reissued to also include *.branch.myapp.test SANs, so deep subdomains like app.branch.myapp.test (common in multi-tenant apps) are covered without manual cert regeneration.

Unsecuring the parent switches all worktree vhosts back to HTTP and updates their .env files accordingly.

Stripe listener ​

If a Stripe webhook listener is running for the site, toggling HTTPS automatically restarts it so --forward-to points at the correct http:// or https:// URL. No manual intervention required.

How it works ​

  1. lerd install generates a local CA with mkcert and installs it into the system trust store (NSS databases for Chrome/Firefox, and the system root store).
  2. lerd secure <site> issues a certificate signed by that CA for <site>.test and *.<site>.test (wildcard), so all subdomain worktrees are covered. When worktrees exist, *.branch.<site>.test SANs are included so deep subdomains work too. The certificate is reissued automatically when new worktrees are created.
  3. The nginx vhost is regenerated to listen on port 443 with the new cert, and port 80 redirects to HTTPS (302, not 301, so the redirect is not cached by browsers).
  4. APP_URL in the project's .env (and any worktree .env files) is updated to https://.
  5. If a lerd stripe:listen service is active for the site, it is restarted with the updated forwarding URL.

Released under the MIT License.

Lerd