herdomain

Change Laravel Herd configuration so a local Herd site can use a real public domain with a Let's Encrypt HTTPS certificate.

What It Does

herdomain wires a public domain to an existing Herd project without changing Herd's global .test TLD and without renaming your project folder.

It creates a Herd alias, writes a generated Nginx vhost, requests a Let's Encrypt certificate through Certbot, installs a renewal hook, and updates Laravel APP_URL.

Requirements

• macOS with Laravel Herd installed.
• A Herd project in ~/Herd/<project>.
• A real domain with DNS pointing to this Mac, or to a router forwarding public TCP 80 and 443 to this Mac.
• Certbot installed:

brew install certbot

Example DNS:

realdomain.com      A  80.90.100.200
www.realdomain.com  A  80.90.100.200

Usage

Run a generic preflight check:

./herdomain check

Apply a real domain to a Herd project:

./herdomain apply localapp realdomain.com --email you@example.com

By default, the certificate covers both realdomain.com and www.realdomain.com.

Use an apex-only certificate:

./herdomain apply localapp realdomain.com --email you@example.com --no-www

Use an apex plus wildcard certificate:

./herdomain apply localapp realdomain.com --email you@example.com --wildcard

Wildcard mode uses Certbot's interactive manual DNS challenge. The tool does not create DNS records or use a DNS provider plugin. Certbot will print the _acme-challenge TXT values you need to add manually. If your DNS provider requires CNAME delegation, create that CNAME in DNS first, then add the requested TXT values at the delegated target. Renewing a manual wildcard certificate requires rerunning the DNS challenge.

If IP detection fails, pass the bind IP explicitly. If this Mac owns the public IP directly:

./herdomain apply localapp realdomain.com --email you@example.com --bind 80.90.100.200

Remove all local artifacts for a domain:

./herdomain remove realdomain.com

Safety

• The domain argument must be an apex domain like realdomain.com.
• Use --no-www if www.realdomain.com should not be configured.
• Use --wildcard for realdomain.com and *.realdomain.com; wildcard certificates require manual DNS-01 TXT validation.
• Local-only domains like .test and .localhost are rejected.
• Existing Nginx files are not overwritten unless they were generated by this tool.
• remove deletes local domain artifacts, copied certificates, Certbot lineage, renewal hooks, and Certbot logs managed by this tool.
• remove restores APP_URL to the local Herd URL only when it still exactly matches the real domain set by apply.

Files Changed

For ./herdomain apply localapp realdomain.com --email you@example.com, the tool manages:

~/Library/Application Support/Herd/config/valet/Sites/realdomain.com
~/Library/Application Support/Herd/config/valet/Nginx/realdomain.com
~/Library/Application Support/Herd/config/letsencrypt
~/Library/Application Support/Herd/config/certbot
~/Library/Application Support/Herd/config/certificates/realdomain.com
~/Herd/localapp/.env

Notes

Herd's built-in secure command creates local Valet/Herd certificates. This tool uses Certbot because public domains need a publicly trusted certificate.

AI Disclosure

This project was generated with AI assistance from OpenAI Codex, a GPT-5 coding agent, on 2026-04-26.