Skip to content

Proxies ​

A reverse proxy fronts an already-running service with a Yerd .test address, so it gets the same DNS, HTTPS, and browser experience as a PHP site - without Yerd running the service itself. Two shapes:

  • A whole-host proxy maps a new host to a service: reverb.test → a Reverb, Node, Vite, or Docker service on some port.
  • A path rule maps a path on an existing site to a service: myapp.test/app → a service, while every other path on myapp.test keeps being served by PHP. This is the same-origin setup Laravel Reverb wants (wss://myapp.test/app), so cookies and CORS just work.

yerd proxy add's two forms are distinguished by argument count: two arguments create a whole-host proxy, three attach a path rule to a site. yerd proxy edit follows the same convention to change an existing proxy's upstream.

Looking for a path that maps to a file instead?

A proxy path rule forwards to a separate running service. To send unmatched URIs under a prefix to a file inside the site - a nested api/index.php, or index.html for a JavaScript SPA - use yerd route instead. When a site has both on the same prefix, the proxy rule wins.

CommandDescriptionExample
yerd proxy add <NAME> <URL>Create a whole-host proxy (<NAME>.test → <URL>).yerd proxy add reverb http://localhost:8080
yerd proxy add <SITE> <PREFIX> <URL>Add a path rule: requests under <PREFIX> on <SITE>.test proxy to <URL>.yerd proxy add myapp /app http://127.0.0.1:8080
yerd proxy edit <NAME> <URL>Change a whole-host proxy's upstream; its domains, wildcards and HTTPS are kept.yerd proxy edit reverb http://localhost:8081
yerd proxy edit <SITE> <PREFIX> <URL>Change a path rule's upstream.yerd proxy edit myapp /app http://127.0.0.1:8081
yerd proxy remove <NAME>Remove a whole-host proxy.yerd proxy remove reverb
yerd proxy remove <SITE> <PREFIX>Remove a path rule from a site.yerd proxy remove myapp /app
yerd proxy listList every whole-host proxy and per-site path rule.yerd proxy list
sh
# Whole-host: front a Reverb server on its own .test domain
yerd proxy add reverb http://localhost:8080
curl http://reverb.test/          # → the Reverb service

# Serve it over HTTPS - a proxy secures exactly like a site
yerd secure reverb
curl https://reverb.test/

# Path rule (the Reverb same-origin case): /app on an existing Laravel site
yerd proxy add myapp /app http://127.0.0.1:8080
# https://myapp.test/        → PHP (Laravel)
# https://myapp.test/app     → Reverb (websockets included)

# Point the path rule at a different port, keeping everything else
yerd proxy edit myapp /app http://127.0.0.1:8081

# List, then remove
yerd proxy list
yerd proxy remove myapp /app
yerd proxy remove reverb

A path rule inherits its parent site's TLS: securing myapp (yerd secure myapp) also secures its /app rule. A whole-host proxy is secured on its own name (yerd secure reverb / yerd unsecure reverb), exactly like a site.

Names and domains ​

A whole-host proxy's name may be dotted, so the proxy's own address can be a subdomain. Beyond that address, a proxy carries extra domains, subdomains, and wildcards exactly as a site does, through the same yerd domain commands - pass the proxy name where a site name would go.

sh
# A dotted name gives the proxy a subdomain address of its own
yerd proxy add api.account http://127.0.0.1:9011
curl http://api.account.test/

# Extra domains and wildcards, exactly as for a site
yerd proxy add account-dev http://127.0.0.1:48087
yerd domain add account-dev custom-domain.test
yerd domain add account-dev '*.account-dev.test'
yerd domain primary account-dev custom-domain.test

yerd proxy list shows a customized proxy's domains on an indented line beneath it, marking the primary when you have set one away from the default <name>.<tld>. yerd domain list remains site-only.

Upstreams ​

The upstream <URL> is http://host:port or https://host:port. The port is required for anything but the default (80/443). For an https:// upstream, Yerd verifies the certificate for a genuine public host, but skips verification for a local host (localhost, a loopback/private IP, or a .test name) - self-signed dev backends are the norm there.

The request path is passed to the upstream unchanged (an nginx proxy_pass with no trailing path), so a path rule's prefix reaches the upstream too: myapp.test/app/foo → <URL>/app/foo. Yerd preserves the original Host header and adds the usual X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Real-IP headers. Websocket (Connection: Upgrade) traffic is tunnelled through, so Reverb/Vite HMR work.

If the upstream is down, a proxied request returns 502 Bad Gateway rather than hanging.

How a request routes ​

For an incoming host, Yerd resolves it to a site or a whole-host proxy, then:

  • a whole-host proxy forwards every request to its upstream (no PHP);
  • a site with a matching path rule forwards that request to the rule's upstream; every other path is served by PHP as usual. Matching is longest-prefix with path boundaries, so /app matches /app and /app/x but not /apple.

If a whole-host proxy's name collides with a real site's apex, the site wins and the proxy is dropped. Every other contested domain is settled one domain at a time: a domain added explicitly beats a claim on a default apex, and among equal claims the earlier claimant wins - every site is considered before any proxy, and proxies among themselves in config order. A proxy that loses one domain keeps its others. yerd doctor reports each contested domain with its winner and the claimants that lost it.

Client-side validation & guards

proxy add validates the upstream URL and, for a path rule, that the prefix begins with /, before connecting - a malformed value fails with a usage error (exit code 2). The daemon rejects a target that would loop back into Yerd: a .test host, or a loopback host on one of Yerd's own bound proxy ports. A proxy name that collides with an existing site or proxy is rejected as "already exists".

proxy edit validates exactly as add. An unknown proxy or path rule is reported as not found, and a rejected edit leaves the existing upstream in place. Rules a service manages (such as Reverb's /app) follow the service's port and can't be edited directly; use yerd service set-port <service> <port> instead. proxy list marks them (managed by <service>).

See also ​

A Forjed project. Released under the MIT License.