Feature Idea: Host Alias for Multi-Tenant SaaS Custom Domain Development

[sandikodev]

Problem

When developing multi-tenant SaaS applications, we need to test custom domain resolution locally. For example:

• [tenant].[custom].test → Tenant A
• [another].[custom].test → Tenant B

Currently, I have to manually add entries to /etc/hosts for each custom domain:

echo "127.0.0.1 tenant-a.custom.test" | sudo tee -a /etc/hosts
echo "127.0.0.1 tenant-b.custom.test" | sudo tee -a /etc/hosts

This is tedious and doesn't scale well when you have many tenants to test.

Proposed Solution

Add a host_aliases configuration in .lerd.yaml or site config:

# .lerd.yaml
host_aliases:
  - tenant-a.custom.test
  - tenant-b.custom.test

Or per-site:

# .lerd.yaml
sites:
  myapp:
    host_aliases:
      - tenant-a.custom.test
      - tenant-b.custom.test

Lerd would then automatically:

1. Add these aliases to /etc/hosts (or DNS equivalent)
2. Route them to the same site
3. Clean up on lerd site remove

Use Case

Multi-tenant SaaS platforms that resolve tenants via:

1. Custom domain (e.g., app.tenant.custom.test)
2. Subdomain (e.g., tenant.custom.test)
3. Path-based (e.g., custom.test/tenant)

Lerd already handles *.custom.test via its DNS, but custom domains outside the wildcard need manual /etc/hosts entries.

Alternative

Could also be useful for:

• Testing third-party webhook callbacks (Stripe, Midtrans, etc.)
• Local development with multiple client domains
• Simulating production-like domain setups

Environment

• Lerd version: v1.29.0
• OS: Linux (Ubuntu/Debian)
• Multi-tenant app with dynamic host resolution

[geodro]

Good news, this mostly works already in v1.29.0, and you shouldn't need to touch /etc/hosts at all.

lerd never writes to /etc/hosts. DNS is a single wildcard record covering the whole .test TLD, so every .test name at any depth already resolves to localhost with nothing registered per host. On top of that, every site's nginx vhost is generated with both the domain and a wildcard, so a site called custom gets server_name custom.test *.custom.test, and the TLS cert gets the same wildcard SAN. That means your exact example, tenant-a.custom.test and tenant-b.custom.test hitting the custom site, works today over http and https with no config whatsoever. Just link the site and the tenant subdomains resolve and route.

If you want genuinely separate hostnames rather than subdomains, the key already exists, it's just called domains rather than host_aliases. In .lerd.yaml you write domains with a list, entries go in without the TLD since lerd appends it at link time, so domains of myapp and api gives you myapp.test and api.test. There's a CLI for it too, lerd domain add, remove and list. Worth noting our Herd and DDEV importers already map their aliases and additional_hostnames keys onto this, so if you're coming from either one your aliases carry over. Cleanup on site removal is handled.

Two limits worth knowing. A domain can only belong to one site, so you can't alias the same name onto two. And the wildcard is single label, so tenant-a.custom.test matches but a.b.custom.test doesn't and falls through to the catch all. If you need subdomains routing to different sites rather than the same one, that's what site groups are for, see the site groups page in the docs.

Does the subdomain wildcard cover your multi tenant case, or are you after custom domains that aren't subdomains of the site?

[geodro]

@sandikodev ☝🏻 ?