Deploying the docs site

This page covers this documentation site only. For the CMS and the public website, see Deploying Umbraco.

The site is a static build served by a Cloudflare Worker using static assets — there is no Worker script, so wrangler.jsonc has no main entry. Cloudflare serves dist/ directly.

Deploy

cd src/docs.nri-inc.org
npm run deploy

That runs astro build and then wrangler deploy. You need to be authenticated against the Cloudflare account first:

npx wrangler login

To see what a deploy would do without touching the account:

npm run deploy:dry-run

Configuration

wrangler.jsonc holds everything:

Setting	Value
Worker name	docs
Account ID	6e62a7dc4b6c5726a844a0e0a5d88cb5
Assets	./dist
workers.dev URL	docs.nri-inc.workers.dev
Custom domain	docs.nri-inc.org

Caution

workers_dev: true has to stay in wrangler.jsonc. When the key is absent, wrangler disables the workers.dev subdomain on every deploy — the custom domain keeps working and docs.nri-inc.workers.dev silently starts returning 404. Removing the line does not preserve the status quo; it turns the subdomain off.

preview_urls: false is set for the same reason in reverse. Enabling workers_dev turns per-version preview hostnames on by default, which would publish every deployed version at its own public URL outside the two intended ones. Only docs.nri-inc.org and docs.nri-inc.workers.dev should serve this site.

The site is public. There is no authentication in front of it, so anything written here — server addresses, account identifiers, staff email addresses — is world-readable. Gate it behind Cloudflare Access before adding anything that should not be.

The workers.dev hostname is <worker-name>.<account-subdomain>.workers.dev, so the Worker is named docs under the nri-inc account subdomain. Worker names cannot contain dots.

Caution

The routes entry uses custom_domain: true. The first deploy provisions the DNS record for docs.nri-inc.org on the Cloudflare zone. Make sure the zone is on the same account before deploying.

not_found_handling is set to 404-page, so Astro’s generated 404.html is served for unknown paths rather than a bare Cloudflare error.

Local preview of the deployed shape

npm run preview runs wrangler dev, which serves dist/ through the same Workers runtime and asset router used in production. Build first — it serves whatever is currently in dist/.