diff --git a/docs/DEPLOYING.md b/docs/DEPLOYING.md index 88dbdbf..84b341b 100644 --- a/docs/DEPLOYING.md +++ b/docs/DEPLOYING.md @@ -37,11 +37,27 @@ resolve yet — js.org's most common rejection reason is no content on the page. for the domain to be set anyway, nobody replied, and it was closed for inactivity. **The lesson: follow their documented order, and answer the thread.** Their README puts the custom -domain at step 3 and the pull request at step 4. Accept that the site is unreachable in between — -`lintdeveloper.github.io/resilix` 301-redirects to `resilix.js.org`, which serves js.org's -wildcard placeholder until the entry is merged. +domain at step 3 and the pull request at step 4. The site is unreachable in between — +`lintdeveloper.github.io/resilix` 301-redirects to `resilix.js.org`, which serves js.org's wildcard +placeholder until the entry is merged. That gap is the cost of their ordering, and it is smaller +than the cost of arguing with it: the second request, +[#12379](https://github.com/js-org/js.org/pull/12379), did exactly what they asked and merged the +same day. + +A trap while waiting: `resilix.js.org` returns **HTTP 200 even before the entry is merged**, because +js.org wildcards `*.js.org` and serves a yellow placeholder. Neither a status code nor a successful +`curl` tells you whether the subdomain is yours. The only reliable check is the entry appearing on +`master`: + +```bash +curl -s https://raw.githubusercontent.com/js-org/js.org/master/cnames_active.js | grep '"resilix"' +``` + +## The cutover — done 2026-08-26 -## The cutover, in order +`resilix.js.org` is live: [js-org/js.org#12379](https://github.com/js-org/js.org/pull/12379) merged +and `lintdeveloper.github.io/resilix` now 301-redirects to it. This is kept as a record, because +the same five steps apply to any future move — to `resilix.dev`, for instance. 1. **Set the custom domain** on the Pages config. An artifact `CNAME` file is ignored when publishing via a workflow, so it must be set on the repo: @@ -50,8 +66,8 @@ wildcard placeholder until the entry is merged. gh api -X PUT repos/lintdeveloper/resilix/pages -f cname=resilix.js.org ``` - Or Settings → Pages → Custom domain. Expect a DNS-check warning: correct, DNS does not point - here until js.org merges. + Or Settings → Pages → Custom domain. Expect a DNS-check warning until the entry is merged; + that is correct, not a mistake. 2. **Set `SITE` and `base`** in `docs/.vitepress/config.ts`, and update the plain-text links in `README.md`, `CONTRIBUTING.md`, `READING.md` and `docs/public/robots.txt`. @@ -72,12 +88,45 @@ wildcard placeholder until the entry is merged. curl -s https://resilix.js.org/ | grep -c 'href="/assets' # assets at root, not /resilix/ ``` - Until the certificate is issued HTTPS fails while HTTP works. That resolves itself; enforce - HTTPS in the Pages settings once it does. +## HTTPS: do not wait for a GitHub certificate + +**"Enforce HTTPS" is permanently unavailable for a js.org subdomain, and that is fine.** An earlier +version of this page said HTTPS would fail until GitHub issued a certificate and to enable +enforcement "once it does". That instruction can never be followed, and following it wastes time +looking for a certificate that will never appear. + +js.org runs its subdomains through **Cloudflare**, which terminates TLS itself: + +``` +$ dig +short resilix.js.org +104.26.8.84 104.26.9.84 172.67.73.64 ← Cloudflare, not GitHub Pages + +$ curl -sI https://resilix.js.org/ | grep -i '^server\|cf-ray' +server: cloudflare +cf-ray: a31a78d62925bb01-AMS +``` + +GitHub therefore cannot complete an ACME challenge for the hostname, and the API says so plainly: + +``` +$ gh api -X PUT repos/lintdeveloper/resilix/pages -F https_enforced=true +The certificate does not exist yet (HTTP 404) +``` + +HTTPS already works, served by Cloudflare rather than by GitHub. `https_enforced` stays `false`. + +The one visible consequence: `lintdeveloper.github.io/resilix` 301s to `http://resilix.js.org`, +which then upgrades to HTTPS. Cosmetic, and not fixable from this side. + +**This does not apply to a domain you own.** On `resilix.dev` with DNS pointed straight at GitHub's +A/AAAA records, GitHub does issue a certificate, and enforcement should then be switched on. If you +put such a domain behind Cloudflare's proxy, set those records to **DNS only** (grey cloud) until +the certificate issues — an orange-cloud proxy is the most common reason Pages certificate +provisioning never completes. -## If it is rejected again +## It is free, but it is not ownership -js.org is free but it is not ownership — their +The request was accepted, and that is not the same as owning the name. Their [naming-conflict policy](https://github.com/js-org/js.org/wiki/Naming-Conflicts) breaks ties on GitHub stars after a three-month grace period. `resilix.dev` is unregistered (~$14/yr) and is the only route that actually locks the name down. The steps above are identical for it, minus the PR