An app's own domain: cut-over and the way back
The step of a move that can strand a
shop (platform-app-move.md). The forge serves a verified name
and its proxy fetches the certificate; it writes DNS only when asked (below), so the revert is
the owner's records, put back by hand in one edit. In order:
- Write the old records down first. Every record at the name (A, AAAA,
CNAME, ALIAS, and the TTL of each) as the old host serves them today,
in the migration issue and with the domain: pass them as old_records
([{type, name, value, ttl?}]) when adding, or later PUT
…/app/domains/<host>/old-records with {records} (MCP app_domains
keep, with records; in the terminal, o on the domain's screen, type name value [ttl]; …), up to 50, replaced whole. Types: A, AAAA, CNAME, ALIAS, TXT, MX, NS, CAA, SRV. list then shows them
as oldRecords. The forge cannot read them for you after the cut.
- Add the name (Settings → App → Domains,
app_domainsadd, or
POST …/app/domains). The answer lists the TXT proof and the CNAME or
ALIAS to publish. Publish the TXT only; the old A/CNAME stays.
- Check (
check). The sentence says verified, or what is missing. The
old site still answers: nothing has moved. GET /__forge/domains/ask?domain=<host>
answering 200 is what lets the proxy issue the certificate on the first
request (docs/APPS.md, _Your own domain_). On a verified name the check
also asks the name for its certificate over TLS and appends the expiry to
the sentence (Certificate valid until …, or expired / due within 14
days, or not read yet). The proxy renews on its own; this is where a
failed renewal shows. It updates when someone presses Check.
- Cut: replace the old A/CNAME with the CNAME/ALIAS the forge gave. The
first request to the new name pays for issuing the certificate (a second or two); request it once yourself, over https, before telling anyone.
- Revert, one step: read
oldRecordsfrom the domain (list) and put those records back. Traffic returns to the old
host as each resolver's cache of the new record expires, so keep the TTL
low (platform-app-move.md, §6) until the shop is settled.
The forge keeps answering at the name until the domain is removed
(remove); removing it is only tidiness once DNS no longer points here,
and the old host's certificate was never touched.
Editing DNS at the registrar (optional)
The forge edits DNS only when asked, with a credential you hand it by name:
set the secret DNS_API_TOKEN (a Cloudflare API token that edits DNS in the
zone) for the repository itself. A forge-wide or organization token is not
used: it would reach other tenants' zones. Then, as an admin of the
repository, the MCP tool app_domains takes three more actions:
dns_proofpublishes the TXT proof (step 2);dns_cut(verified domains only) replaces the A, AAAA and CNAME at the name
with the CNAME to the app (step 4) and answers the records it removed: paste them in the migration issue, they are the way back;
dns_revert(verified domains only) withrecords: [{type, value, ttl?}]
puts your step-1 list back (step 5).
The terminal has the same three, on the domains screen (n on an app's
deploys screen), for the same admins:
ppublishes the TXT proof of the selected domain;xaskscut <host> over to the app? y/n, then cuts it over and keeps
Removed: A 203.0.113.5 ttl 60; … on the screen's foot;
vasks for the old records and puts them back; type them as the cut
listed them (A 203.0.113.5 ttl 60; AAAA 2001:db8::1).
Every edit is audited (app.domain.dns, and the secret read). A failed edit
deletes what it put and puts back what it removed; any record it could not
put back is named in the answer, to add by hand. Only Cloudflare is
supported; the adapter is src/apps/dns_provider.ts. The settings page has
no registrar button yet.
Left out, on purpose: other registrars, or read the old records itself: it keeps only what you wrote down (#11719). This closes #11700 as a runbook over a feature that already ships, not as new code.
What keeps these claims true
All in test/app-domains.test.ts:
- the ask endpoint answers 200 only for a verified host (also with case and a
trailing dot) and 404 for an unverified, unknown or missing name: "verified, the forge serves the app at the host and every URL follows";
- before verification the forge answers for itself and the ask says 404:
"before verification the forge answers for itself at the host";
- the old records are checked, kept with the row, listed back, replaced whole
and admin-only (also test/core-domains.test.ts): "the old records are kept
with the domain";
- removal makes the host unknown again and the ask 404: "removal makes the
host unknown again".