Child Hosts

Child hosts let one domain you own carry a separate site for each of your locations — for example, practice-a.enroll.example.com and practice-b.enroll.example.com, each serving its own site. You publish two DNS records once, on a parent domain. After that, adding a host takes a label and a click: no DNS changes, and each host gets its own certificate automatically.

Organization admins set up the parent domain and its hosts on the organization's Domains page. Workspace members who can edit sites then assign each host to a site.

When to Use Child Hosts

You want	Use	DNS work
A site with no setup	The platform address, {site-slug}--{workspace-slug}.sites.gravityrail.com	None
One site on your own address, such as portal.example.com	This domain only on that domain	Three records for each domain
A site for each location, clinic, or program under one domain	Host many sites under this domain (child hosts)	Two records, once

Child hosts suit anything that grows one site at a time: adding the twentieth location is the same single step as adding the first.

Choose a Parent Domain

The parent is the domain your hosts sit under. Use a dedicated subdomain, such as enroll.example.com, rather than your root domain (example.com):

• The wildcard record you publish sends every name under the parent that has no record of its own to Gravity Rail. On a root domain, that would include stray names across your whole domain.
• If your root domain already has a wildcard record (*.example.com), it would conflict with the one child hosting needs.
• The parent's own address never serves a site. Only the hosts beneath it do.

Hosts are always one level below the parent: practice-a.enroll.example.com, not a.practice-a.enroll.example.com.

Set Up the Parent Domain

Add the Domain and Prove Ownership

1. Open your organization and select Domains in the sidebar.
2. Click Add domain.
3. Enter the parent domain, such as enroll.example.com, check Map a web site, and click Add domain.
4. Publish the TXT record shown (host _gravity-verify.enroll.example.com) at your DNS provider.
5. Click Verify ownership. Domain ownership shows Verified once the record is found.

Use Copy Instructions to send the records to whoever manages your DNS.

Turn On Child Hosting

1. In the domain's Sites section, click Enable sites on this domain.

2. Choose Host many sites under this domain.

3. Publish both records shown at your DNS provider. The TXT record is the one you published to prove ownership.

   Purpose	Type	Host	Value
   TXT (domain ownership)	TXT	_gravity-verify.enroll.example.com	The value shown on the page
   CNAME (sites)	CNAME	*.enroll.example.com	The value shown on the page, such as edge.sites.gravityrail.com

4. Click Verify record & enable.

Gravity Rail checks the wildcard record before it turns anything on. If you see Record not detected yet, leave the records in place, wait a few minutes for DNS to update, and click Verify record & enable again. When it succeeds, the Sites section reads "Wildcard verified" and a Child hosts card appears below it.

Many DNS providers ask only for the part of the name inside your zone. If your zone is example.com and the parent is enroll.example.com, enter *.enroll for the CNAME and _gravity-verify.enroll for the TXT. Enter * and _gravity-verify only when the parent is the zone itself.

Keep both records published for as long as you use the domain. Every host depends on them.

The choice between This domain only and Host many sites under this domain is fixed once sites are enabled. To change it, disable sites on the domain — which removes every host beneath it — and enable it again.

Add Hosts

Add host and Bulk add stay unavailable until the parent is fully verified — both its ownership record and its wildcard record.

Add One Host

1. In the Child hosts card, type a label, such as practice-a, in the host label box. The card shows the full name it will create: practice-a.enroll.example.com.
2. Click Add host.

Add Many Hosts

1. Click Bulk add.
2. Enter one label per line.
3. Click Add N hosts — the button shows how many labels you entered.

Hosts are created one at a time, and each line reports its own result, so one failed label never blocks the rest. Keep the dialog open until it finishes; it shows how many labels it has processed so far.

Label Rules

A label becomes the first part of the host name, so it must be a single DNS label:

• Lowercase letters, digits, and hyphens (capital letters are converted to lowercase for you)
• No hyphen at the start or end
• At most 63 characters

Pick labels you won't need to change. A host can't be renamed — you'd remove it and add the new name.

Host Status

Each host in the Child hosts card shows a status:

Status	What it means
Pending	The host isn't usable yet — its certificate is still being issued. This usually takes a few minutes.
Verified	The certificate is issued and the host is routing. You can assign it to a site.
Failed	The certificate couldn't be issued, or the host no longer reaches Gravity Rail through the parent's wildcard record. See Troubleshooting below.

You don't need to watch new hosts. Gravity Rail checks each one automatically — about 10, 30, and 60 seconds after it's added, then once a minute until about 20 minutes have passed — and the card refreshes every 10 seconds while any host is pending or failed. To check a host right away, click Check now on its row.

Assign a Host to a Site

1. In the workspace, go to Sites and open the site, or create one.
2. On the General tab, open the Domain list and choose the host, such as https://practice-a.enroll.example.com/. Hosts carry a Managed host badge.
3. Save the site.

Visitors can then reach the site at https://practice-a.enroll.example.com/ — the address to put in your emails, texts, and printed materials.

• A host that isn't ready yet is listed but can't be chosen. The reason appears next to it — for example, "DNS verification pending" while its certificate is being issued.
• Parent domains don't appear in the list, because they never serve a site themselves.
• Each host serves one site in one workspace. Hosts under the same parent can serve sites in different workspaces of your organization — for example, one workspace per location.

Before a Site Is Assigned

A verified host with no site assigned shows a plain page that says "Nothing is published here yet", whatever path a visitor opens. The page carries no Gravity Rail branding and no organization or workspace names, and search engines are told not to index it. You can create hosts ahead of a launch and assign sites when they're ready.

Remove a Host

1. In the Child hosts card, click Remove on the host's row.
2. Click Remove host to confirm.

If the host still serves a site, the dialog lists it and asks again; click Remove anyway to go ahead. The site stays in its workspace but stops loading at that address.

Removing a host deletes its certificate, routing, and registration, and can't be undone. Adding the same label again later creates a new host from scratch.

To remove every host at once, click Disable sites on the parent. The confirmation lists every host that will be removed; click Disable sites anyway to continue. On a parent with many hosts, this can take a while.

Limits

Limit	Amount
New hosts under one parent domain	200 per day
New hosts across your organization	500 per day
Domains enabled for sites, either setup	10 per day for your organization

When you reach a limit, adding a host fails with "Too many child hosts created today on this domain" (or "…for this organization"). Try again the next day, or contact support if a rollout needs more. A host that fails to create isn't counted, and removing a host doesn't free up a place for that day.

Hosts serve sites only. They can't send or receive email.

Troubleshooting

Problem	What to do
Record not detected yet when enabling	DNS can take a few minutes to update. Check that the CNAME is on *. plus your parent — *.enroll.example.com, not *.example.com — and points at the value shown, then try again.
Add host and Bulk add are unavailable	The parent isn't fully verified. Make sure both records are still published, then click Verify ownership or Verify DNS on the parent's page, whichever it offers.
A host stays Pending for more than 20 minutes	Click Check now. If it's still pending, contact support with the host name.
A host shows Failed	Check that the parent's wildcard record is still published and unchanged, then click Check now. If it stays failed, remove the host and add it again.
A label is rejected	It isn't a single DNS label. See Label Rules above.
"Host '…' is already registered."	A host with that name already exists. Look for it in the Child hosts card.
"Host '…' is already routed by an existing site."	Another site on Gravity Rail already uses that name. Contact support to release it.
"Too many child hosts created today…"	You've reached a daily limit. See Limits above.
A host can't be chosen in a site's Domain list	It isn't verified yet. The reason is shown next to it.
Visitors see "Nothing is published here yet"	The host has no site assigned. Choose it on the site's General tab and save.
A host's page says "This host is only partly removed."	A removal stopped partway. Click Finish removing this host on that page.

Tips

• Use a dedicated parent. A subdomain such as enroll.example.com keeps the wildcard record away from the rest of your domain.
• Choose stable labels. Short location codes work well, since a host can't be renamed.
• Set up hosts before launch. Each one shows a neutral page until a site is assigned.
• Keep your labels in a file. Bulk add and the command line both take one label per line.

Related

• Organizations — Manage your organization, its members, and its domains
• Sites — Build the sites your hosts serve

For developers

• CLI Getting Started — script the same steps with gr org domains site children, including bulk adds from a file