Site Management¶

Commands¶

Domain naming¶

Directories with real TLDs are automatically normalised — dots are replaced with dashes and the TLD is stripped before appending .test.

For example: admin.astrolov.com → admin-astrolov.test

Name collision handling¶

When a directory is parked or linked and another site is already registered with the same name:

• Same path — treated as a re-link of the same site. The existing registration is updated and the TLS state is preserved.
• Different path — the new site is registered with a numeric suffix (myapp-2, myapp-3, …) so both sites can coexist.

Unlink behaviour for parked sites¶

When you unlink a site that lives inside a parked directory, the vhost is removed but the registry entry is kept and marked as ignored — the watcher will not re-register it on its next scan. Running lerd link in that directory clears the ignored flag and restores the site.

Pausing sites¶

Pausing a site frees up resources without removing it from lerd. It is useful when you're switching focus between projects and want to stop workers and silence a site without fully unlinking it.

lerd pause              # pause the site in the current directory
lerd pause my-project   # pause a named site

When a site is paused:

• All running workers for that site are stopped (queue, schedule, reverb, stripe, and any custom workers)
• The nginx vhost is replaced with a minimal landing page that shows a Resume button
• Services no longer needed by any other active site are auto-stopped
• The paused state is persisted — the site stays paused across lerd start / lerd stop cycles

The landing page's Resume button calls the lerd dashboard API directly, so you can unpause from the browser without opening a terminal.

lerd unpause              # resume the site in the current directory
lerd unpause my-project   # resume a named site

When a site is unpaused:

• The original nginx vhost is restored (including HTTPS if the site is secured)
• Any services referenced in the site's .env are started
• Workers that were running before the pause are restarted

Paused sites still appear in lerd sites output and the web UI. Their status is shown as paused.

Running CLI commands on a paused site¶

You can run php artisan, composer, lerd db:export, and other exec-based commands on a paused site without unpausing it first. If any services the site needs (MySQL, Redis, etc.) were auto-stopped when the site was paused, lerd starts them automatically before running the command:

$ php artisan migrate
[lerd] site "my-project" is paused — starting required services...
  Starting mysql...

   INFO  Nothing to migrate.

On subsequent commands the services are already running, so no notice is printed. The site stays paused — the nginx vhost remains as the landing page and workers are not restarted.

Commands that benefit from this auto-start:

Git worktrees¶

Lerd automatically creates a subdomain for each git worktree checkout. See Git Worktrees for details.

Sharing sites¶

lerd share exposes the current site via a public tunnel. Requires ngrok or Expose to be installed.

The tunnel forwards to nginx's local port with the site's domain as the Host header, so nginx routes the request to the right vhost even though the incoming request has the public tunnel URL as its host.