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:

  1. 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.

  1. Add the name (Settings → App → Domains, app_domains add, 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.

  1. 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.

  1. 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.

  1. Revert, one step: read oldRecords from 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:

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;

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:

Removed: A 203.0.113.5 ttl 60; … on the screen's foot;

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:

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 at the host";

and admin-only (also test/core-domains.test.ts): "the old records are kept with the domain";

host unknown again".

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs