Connect a custom domain to a site

A domain opens a site only when four things are true. Each has its own owner and its own failure:

Connect (Site Config › Address) does 2, 3 and 4 in one call. 1 is always the owner's job. This page connects, checks, changes, removes and repairs. For what a URL path shows once the domain works, see How a site's addresses route. The site record's fields are in Sites.

How a request finds its site

Tested on the local engine and on live sites, read-only.

1. DNS sends example.com to the platform's edge (today 38.107.233.133; every *.site.appmint.app name resolves there too).
2. The edge (Traefik) looks for an ingress whose host is example.com or www.example.com. None: it answers with its own default certificate and a plain 404 page not found. The request never reaches a site. (appengine resources/deploy-template/domain-ingress.tp; tested on live with an unmapped name.)
3. The site renderer asks the engine for the site: GET /site/get-site/<renderer's site>/<Host header> (base-app src/lib/appmint-client.ts 286–289, called from lib/get-page-data.ts 149).
4. The engine strips a leading www. and looks up a site_domain record whose domainName equals the host (appengine src/site/site.service.ts 467–480, src/repositories/repository.org.service.ts 280–289). Upper case still matches. The port is part of the host, so a local mapping looks like phasite-phazzer.localhost:3200.
5. No mapping: the engine falls back to the renderer's own site name, then to its org's Default site (site.service.ts 102–117). On live, an unmapped platform address shows the renderer org's not-found screen ("Welcome to Wemeant") with a 404. Tested.

So www.example.com and example.com open the same site from one mapping. Tested: GET /site/get-site-by-hostname/www.phasite-phazzer.localhost:3200 returns phasite, and the rendered home page is identical on both names.

Which address links use

Tested on live: https://reesite-reelmoment.site.appmint.app/ and https://www.reelmoment.io/ both carry <link rel="canonical" href="https://reelmoment.io"/>. Neither redirects; they serve the same page.

Ask first

• Which site? By its name (data.name, e.g. phasite), not its id. The platform address is built from the name you send.
• The exact domain, without https://, without a path, and without www.: example.com, or a subdomain like shop.example.com. www. is served automatically.
• Does the person already own it? If not, do they want to buy one here (step 2)? That costs money.
• Who runs its DNS? Their registrar, Cloudflare, or Home › Domains for a domain bought here. Can they log in there today?
• Is the domain serving something now (an old website, a shop, email)? Moving its address records takes that old site offline. Don't touch MX or TXT records: email lives there.
• Is another Appmint site already on it? One domain belongs to one site.

Steps

1. Site Config: what's there now

Read before changing anything.

• The site: call_appengine GET /site/get-site/<site name>. Note data.domain, data.hostName, data.aliases, data.isDefault, and domainRecord (the site's mappings, attached by getSite, site.service.ts 119–124).
• Its mappings: call_appengine GET /site/get-site-host-mappings/<site name>. Each row is a site_domain: domainName, orgId, siteId, siteName, status. A healthy site with a domain has two: the platform address and the domain.
• The address links use: GET /site/base-url?siteName=<site name> → { "url": "https://example.com" }.
• Who owns a host: GET /site/get-site-by-hostname/<host> returns the site that answers it, or an empty body.
• DNS today, from any shell: dig +short example.com A, dig +short www.example.com, dig +short NS example.com.

repo_find on site_domain finds nothing: the mappings live in the platform's root org, not the business's. Use the site/… routes above.

Tested on local (phazzer): get-site/phasite shows domain: null, hostName: "phasite-phazzer.localhost:3200", isDefault: true, one mapping; base-url answers http://phasite-phazzer.localhost:3200.

Hands on: the site's name, its current domain and hostName, and its mappings. Check: Site Config › Address shows the same domain (with Edit Domain, Show DNS Settings, Remove Domain) and the Platform host.

2. Domains: buy a domain (only if they don't own one)

Home › Domains (/domains, admin users only, websitemint ui/sidebars/links.ts 21) lists the org's domains and buys new ones. Site Config's Buy Domain opens the same app on its Buy a domain drawer (site-domain-connect.tsx 131–141, components/domain/app.tsx 12–17).

Stop: buying charges the org's card and registers a domain for a year in the owner's name. Show the domain, the price and the registrant details, and wait for yes. Don't buy through the API yourself: the payment is taken by the screen, not by POST /tools/domain/buy, which registers the domain at once (appengine src/tools/tools.domain.service.ts domainBuy), and call_appengine doesn't ask for confirmation on it.

The person's path:

1. Buy Domain › search a name. Search (GET /tools/domain/search/<name>?suggest=true&provider=cloudflare, public) checks .com .net .org .io .co when no ending is given. The suggestions are always shown as Taken, and a name with no price from the registrar shows $0.00.
2. Registration Info: first and last name, email, phone, address line 1, city, state, postal code and country (one of US, CA, GB, AU, DE, FR, IN) are required; organization and address line 2 are optional. It is filled from the org's locations and saved back as the business address.
3. Review & Pay: tick the registration terms, Proceed to Payment (Stripe), then the domain is registered.

What it really does (modern-domain-purchase.tsx 170–261, org-management.service.ts 470–573, tools.domain.service.ts 176–249):

• The card payment is recorded as a credit top-up to the org, not as a domain purchase. The registrar fee is paid from the platform's registrar account.
• The Cloudflare registrar path sends only the user's name and the org's system email as the registrant; the address and phone typed in step 2 aren't sent.
• On success it writes a domain_registration record: domain, registrar, status: "active", purchasedThroughUs: true, autoRenew: true, expiresAt (a year), nameservers, orderId. No monthlyPrice, so renewal billing never picks it up.
• It creates no DNS records and connects no site. Do step 3, then add the records of step 4.

Other parts of the app, and what they do:

There is no screen for transfers in or out, nameservers or SSL modes; their API routes exist under /tools/domain/cloudflare/* and nothing calls them. A site's certificate comes from the platform's edge, never from these.

Hands on: the domain, now owned, and who runs its DNS (Home › Domains for a domain bought here). Check: it appears in Home › Domains with "Ours".

3. Site Config: connect the domain

Stop: this changes the live site. It creates the domain's route and certificate request on the platform, and from then on the site's emails, canonical tags and sitemap use the new domain, even before DNS points there. If the site already had a domain, the old one stops working at once. Say exactly that, and wait for yes.

In Studio: Site Config › Address › Custom domain › Connect (websitemint components/welcome-screens/site-domain-connect.tsx 25–57). The same box is on the welcome screen. By API, the call Studio makes:

POST /site/update-domain
{
  "siteOrgId": "<org id>",
  "siteName": "phasite",
  "domainName": "example.com"
}

With call_appengine, orgid and the token are added; send only the body.

What it does, in order (site.service.ts 2132–2210):

1. Checks the org may use custom domains (validateCustomDomainUsage, plan-validation.service.ts 90–101). Every plan allows them today (usage/pricing-plan.ts; allowCustomDomains: true on Free, Starter, Professional, Business, Enterprise and every BusinessMade plan). What really fails here is an org that is not active (403 Organization <org> is not active) or missing (404).
2. Finds the site (404 site <name> not found in org <org>).
3. 409 Domain <name> is already registered to another site when a mapping for that name belongs to any other site, in any org.
4. If the site had a different domain: deletes that domain's ingress and its mappings. The old domain stops working now.
5. Makes sure the platform mapping <siteName>-<org>.site.appmint.app exists and writes it to data.hostName.
6. Saves data.domain, creates the domain's mapping (status: "active"), and deploys the ingress from resources/deploy-template/domain-ingress.tp.

The answer:

{
  "sharedMapping": { "…": "the platform address's site_domain" },
  "shareHost": "phasite-phazzer.site.appmint.app",
  "siteMapping": { "…": "the domain's site_domain" },
  "site": { "…": "the site record" },
  "domainName": "example.com",
  "siteName": "phasite",
  "deploy": { "…": "present when the ingress was created" },
  "deployError": "present when it was not"
}

What the ingress is (resources/deploy-template/domain-ingress.tp): name <domain with dots as dashes>-ingress, namespace base-app, Traefik on the web and websecure entry points, with both example.com and www.example.com sent to the site renderer, and the certificate resolver le-http. That resolver is Let's Encrypt's HTTP challenge: Let's Encrypt must reach the name over plain HTTP on port 80 at the platform before it issues. Each name gets its own certificate. Tested on live: reelmoment.io and www.luxesaver.com each carry a Let's Encrypt certificate for that one name. Deploying again deletes the ingress and creates it fresh (k8s-management.service.ts 197–215).

Hands on: shareHost (the platform address, for the DNS record) and whether deployError is empty. Check: GET /site/get-site-host-mappings/<site name> lists both the platform address and the domain. Site Config › Address shows the domain as a link.

4. DNS: point the domain at the platform (the person's part)

Stop: DNS is the owner's, at their DNS host. Give them the records; don't log in for them. For a domain bought in Home › Domains, its DNS can be edited there (step 2), still only on their yes.

Use these records. They are what working live sites use (dig on reelmoment.io, www.reelmoment.io, www.luxesaver.com, all A 38.107.233.133):

Then:

• Delete any other A, AAAA or CNAME record on @ and www (the old host, a parking page). Two A records means half the visitors reach the old one, and Let's Encrypt can fail.
• Leave MX, TXT (SPF, DKIM, verification) and other names alone.
• Cloudflare: set these records to DNS only (grey cloud) until the site opens on https. A proxied record hides the platform from Let's Encrypt's HTTP check.

How long:

• DNS: as long as the old record's TTL, then the time the DNS host takes to publish. Minutes to an hour is usual; Studio says "15 minutes to 48 hours" (dns-instructions-popup.tsx 99). A brand-new domain can take a few hours to resolve at all.
• Certificate: Let's Encrypt can only issue once DNS points at the platform. Usually within a few minutes after that. If DNS was wrong when the route was made and the browser still warns an hour after DNS is right, re-make the route once with step 6. Let's Encrypt blocks a name after 5 failed checks in an hour, so don't repeat it.

Hands on: the records the person added, and when. Check: step 5.

5. Check it, live

From any shell (read-only):

dig +short example.com A            # the platform's address, e.g. 38.107.233.133, and nothing else
dig +short www.example.com          # the hostName then the address, or the address
dig +short phasite-phazzer.site.appmint.app   # the address to compare against
curl -sI https://example.com/ | head -1          # HTTP/2 200 (or 404 if the home page is missing — see site routing)
curl -s https://www.example.com/ | grep -o '<link rel="canonical"[^>]*>'   # href="https://example.com"
echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null \
  | openssl x509 -noout -issuer -subject   # issuer: Let's Encrypt; subject: CN = example.com

Read the result:

Hands on: the working https:// address. Check: open it in a browser. Studio's Site Config › Address shows the domain as a link that opens it.

6. Site Config: Repair Site Domain

Studio: Site Config › Address › Repair Site Domain ("Point this site's domain at BusinessMade again. Use it if the site stops opening.", site-action-buttons.tsx 156). Older docs and the API call it fix domains.

POST /site/fix-domains
{ "siteName": "phasite" }

siteOrgId defaults to the orgid header; another org's is refused with 403 Cannot change a site in another organization. It is staff only, with the ConfigAdmin or ContentAdmin role and the content.update permission (site.controller.ts fix-domains).

Stop: it briefly takes every name the site answers on offline while it remakes them. Ask first.

What it does (site.service.ts 1942–2034):

1. Finds the site.
2. Deletes every mapping the site has: the platform address, the domain, and any extra name attached by a platform operator.
3. Re-creates the platform mapping <siteName>-<org>.<SITE_HOST_NAME> (site.appmint.app on live) and writes it to data.hostName.
4. If data.domain is set, re-creates its mapping and deploys its ingress again (through registerSiteDomainName, 859–902). This is how it fixes a missing route or a stuck certificate.
5. Answers { success, message, site, removedDomains, addedDomains, cloudflareResults, errors }.

What it doesn't do:

• Change DNS. The Cloudflare step is commented out (2002–2005); cloudflareResults is always empty. Its API description still says it syncs with Cloudflare.
• Report the route. An ingress that fails to deploy is logged only; the answer still says success: true and lists the domain in addedDomains.
• Keep extra names. Anything not the platform address or data.domain is gone after it. Aliases were never mapped, so they lose nothing.
• Touch data.domain. A domain removed in Sites & Dev Environments (which leaves data.domain) comes back, route and all.

When to use it: the domain shows the certificate warning or the wrong site while DNS is right; the platform address stopped opening; data.hostName is empty (Studio's DNS window then shows your-site.websitemint.com). Not for DNS problems, a 409, or "it still shows my old host".

Hands on: addedDomains and errors. Check: step 5 again, and get-site-host-mappings shows the platform address and the domain.

7. Site Config: change or remove the domain

Stop for either: the old domain stops working the moment the call returns.

Change: Site Config › Address › Edit Domain › type the new one › Connect is the same POST /site/update-domain with the new domainName. It deletes the old domain's route and mappings, then does all of step 3 for the new one. Then the owner points the new domain's DNS (step 4). Studio does nothing if the new name equals the current one (site-domain-connect.tsx 32).

Remove: Site Config › Address › Remove Domain:

POST /site/remove-domain
{ "siteOrgId": "<org id>", "siteId": "<site sk>" }

It deletes the domain's ingress and mapping, and sets data.domain to "" (site.service.ts removeSiteDomain). The platform address and hostName stay, so the site still opens there, and links fall back to it. { "domainName": "example.com" } instead of siteId works only for a domain connected to one of this org's sites (else 404 Domain … is not connected to a site in this organization); a domain another org also holds is refused with 403 Domain … belongs to another organization. It is staff only (ConfigAdmin or ContentAdmin). Answer: { message, domain, results: { ingress, database, site }, site }.

call_appengine treats /site/remove-domain as a delete: the first call comes back asking for the person's confirmation; repeat it with "confirmed": true after their yes (ai/agents/base-agent.ts 914–935).

Tell the person to remove or repoint the DNS records afterwards. Left pointing at the platform, the bare name just shows the certificate warning.

Hands on: the site's new data.domain (or none) and its mappings. Check: get-site-host-mappings and get-site/<site name>; for a change, step 5 on the new domain.

Aliases

Site Config › Address › Aliases ("Other hostnames that should serve this site", site-config-form.tsx 799) saves a list to data.aliases. Nothing routes with it. No code registers a mapping or route for an alias, and the renderer doesn't read it; the only reader is analytics, which counts visits on those names as the site's (appengine src/analytics/analytics-site.ts 44).

What actually serves another name:

Troubleshooting

When it's done

Tell the person, in a few lines:

• the domain and the site it opens, and the https:// address that now works (or what's still pending: DNS, certificate);
• the DNS records they added, and any old ones they should delete;
• that www. works too, and that links, emails, the canonical tag and the sitemap now use the domain;
• for a change or removal, what the old domain does now.

Open Site Config › Address and the domain in a browser.

What it can't do yet

• No status for the route or certificate. Nothing in Studio or the API says whether the ingress exists or the certificate issued. site_domain.status is active the moment it's created. Check with curl and openssl (step 5).
• No DNS check. Connect doesn't look at DNS; it succeeds for a domain nobody pointed.
• Studio's DNS windows give wrong IP addresses (step 4) and the first one opens empty.
• Plain http:// is broken on live (redirect to port 8443).
• One domain per site. Aliases do nothing; a second domain is operator-only and lost on Repair.
• Repair doesn't sync Cloudflare and can't report a failed route.
• Dev environments: Sites & Dev Environments › Attach Domain on a dev environment only adds the name to its domains list. The route is commented out (dev-environment.service.ts 399–413) and removal says "not yet implemented".
• Connect may leave hostName as it was. It writes data.hostName, then saves the whole site from a copy read before that write (site.service.ts 2151, 2181, 2195). A site with no hostName keeps none; Repair sets it.

Don'ts

• Don't call Connect, Repair or Remove without the person's yes. Each changes what the live site answers on at once.
• Don't write data.domain with repo_update. It routes nothing.
• Don't enter www., https:// or a path.
• Don't give the IP addresses from Studio's DNS windows. Read the platform host's address with dig.
• Don't touch the owner's MX, TXT or other records, and don't log in to their DNS host for them.
• Don't use Sites & Dev Environments' Remove Domain for a site.
• Don't run Repair over and over. A few times an hour at most, and only once DNS is right.
• Don't promise an alias will open the site.
• Don't call site/fix-domains with a site name you haven't read back from get-site.