Moving the address

A move that fails quietly

Partway through this system’s life the publication moved to its own domain.

Domain moves are worth a chapter because of how they fail. Nothing crashes. Every page still loads. The site looks perfect. And weeks later you notice the traffic never arrived, because a search engine was told — by your own pages — that the new address was a duplicate of an old one that now redirects to it.

The mechanism is the canonical URL. It is a single tag, it is easy to forget, and it is the difference between carrying your search ranking across and throwing it away.

One value, everything derives from it

The reason this move was mostly painless is a decision made much earlier: the site’s own address is written down in exactly one place.

Everything absolute derives from it — the canonical tag on every page, the social card URLs, the entire sitemap, every share link. There is no second copy to fall out of step.

Which means changing the domain is changing one value. It also means getting that one value wrong breaks all of them at once, which is why it is changed by a script rather than by hand.

Why a script for a one-line change

Because it is not one line. The origin appears in the front end’s configuration, in the editing application’s search-result preview, in the address the editor opens for “view live”, and in the documentation.

A half-applied change is worse than none. A canonical tag pointing at the old host tells search engines the new pages are duplicates. A social card image on a dead host silently blanks every preview card.

So one command changes all of them together, and reports exactly what it touched. It is also written to be safely re-runnable: an already-correct value is not an error, because treating “no change needed” as failure once aborted the script before it reached the later steps and left half the system on the old host.

The order of operations

The sequence matters, and it is ordered so nothing is live on the new domain until the metadata describing it is already correct.

1. Connect the domain and make it primary. Primary is what decides which address the platform treats as canonical, and whether the old one redirects or serves a duplicate.
2. Wait for the certificate. Not instant, and there is no point continuing until the new address loads without a warning.
3. Repoint the build — the one command above.
4. Build, and publish.
5. Verify from outside: routes answer, canonical and social tags name the new host, the sitemap is complete, no draft is reachable.
6. Confirm the old address returns a permanent redirect rather than serving the same pages twice.
7. Submit the sitemap, and tell the search engine about the change of address.

Two things I got wrong

Worth recording, because both are easy to repeat.

I checked the wrong host. The platform provides several addresses — the site’s own, and branch or preview addresses. I checked a preview address, found it serving pages happily rather than redirecting, and concluded the move was incomplete. It was not; preview addresses do not redirect and never will. The address that matters is the site’s own.

A deploy silently did not take. A publish reported something other than the usual confirmation, and the live site kept serving the previous build. Nothing said “failed”. I only caught it because I checked the deployed page for the change rather than trusting the command that claimed to have deployed it.

The lesson from both is the same, and it is the lesson of the whole operational half of this system: verify the outcome, not the command.