Website and data storage operations

The application, documentation, and dataset files have separate responsibilities. ADR 0015 records the decision.

Address	Source	Build output	Cloudflare resource
`usdata.dev`	`web/public/`, `web/src/`	`web/dist/`	`usdata-home` Worker + Static Assets
`docs.usdata.dev`	`docs/`, Python references, saved examples	`.build/docs-site/`	`usdata-docs` Worker + Static Assets
`data.usdata.dev`	Future published datasets/cache objects	Uploaded objects	`usdata` R2 bucket

Both build outputs are ignored and disposable. .build/docs/ is intermediate MkDocs staging. site/ was the previous combined build output and is no longer used. Neither website reads R2 or packages its HTML in the Python wheel. Documentation styles and hosting configuration live in docs/theme/ and docs/hosting/. web/ supplies the shared npm/Wrangler toolchain.

Build and preview

Follow the development setup, then run:

just check-docs
npm ci --prefix web
npm run build --prefix web
npm run check --prefix web

Preview the homepage with npm run dev --prefix web (port 8787), and documentation with npm run dev:docs --prefix web (port 8788). The Worker previews exercise redirects. Links between sites use the production hostnames; inspect each local preview directly when validating an unmerged change. just docs-serve previews current documentation with reload on port 8000. Builds do not execute notebooks, fetch scientific data, or require R2 credentials.

Automatic deployment

Two Workers Builds triggers connect to jakeryderv/usdata, include only main, and use root directory web. All repository paths trigger a build, so changes to Python signatures, examples, docs, or shared tooling cannot leave stale output.

Worker	Build command	Deploy command
`usdata-home`	`npm run build && npm run check:home`	`npm run deploy`
`usdata-docs`	`python3 -m pip install uv==0.12.5 && npm run build:docs && npm run check:docs`	`npm run deploy:docs`

The docs build explicitly bootstraps uv, then uses the locked Python environment. Each site deploys only after its own checks pass. Required PR CI validates both sites and the SDK before merge; Workers Builds does not wait for a separate main GitHub Actions run. Cloudflare's managed build token deploys the Workers. R2 credentials are not passed to either site build. Package releases remain independent.

For a dry run, use npm exec --prefix web -- wrangler deploy --config web/wrangler.jsonc --dry-run, or select docs/hosting/wrangler.jsonc instead.

Compatibility URLs

Former documentation paths on usdata.dev redirect to docs.usdata.dev. The docs Worker maps /start/, /latest/, and /0.10.0/ to current docs. Deeper latest/version paths preserve their suffixes. Query strings and browser fragments survive redirects. These URLs no longer select release-specific documentation. There is no hosted archive or versions.json; missing paths return 404.

Migration redirects use 302 with Cache-Control: no-store. A browser that cached the earlier permanent docs-to-home redirects may need its site cache cleared. Existing GitHub release attachments and Git history remain historical records; they are not downloaded by site builds. The retired usdata Worker and R2 docs/ objects are removed after successful cutover.

R2 dataset storage

infra/r2-data.json records the intended bucket domain and CORS configuration. data.usdata.dev exposes objects for public reads, with GET/HEAD CORS for https://usdata.dev and https://docs.usdata.dev. CORS does not restrict access outside browsers. All objects placed in this bucket must be suitable for public access. No browser receives upload credentials. Keep the managed r2.dev endpoint disabled; the custom domain is the public interface.

GitHub retains R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY. Authenticated uploads use the account's R2 S3 endpoint and require Object Read & Write access to usdata. Do not rotate or remove these credentials merely because the former docs workflow is gone. Reassess their scope when a future uploader needs different access.

Run the manual Check R2 data storage GitHub Actions workflow from main to verify the stored credentials, an authenticated upload/download, public delivery, and CORS. It uses a unique checks/github-<run>-<attempt>.txt object and always attempts to delete that exact object. It does not upload any dataset or alter other objects. A failed cleanup must be resolved using the key shown in the run.

The bucket is ready for data; SDK remote caching is not implemented. Before a first dataset upload, define stable object identities, provenance, checksums, upload ownership, and retention. Published example inputs must survive disposable cache eviction. The roadmap keeps exploration in Next and general remote caching in Later without dates or release commitments.

Verification and recovery

Verify both custom domains, homepage links, docs navigation/search, references, notebook plots, mobile layout, legacy redirects, and 404/HEAD behavior. Check each Workers Builds run against the merged commit. Verify R2 using the manual workflow.

For a site rollback, redeploy a compatible Worker/assets version or revert through a PR. A site rollback does not restore deleted R2 objects. Versions from before this split may contain incompatible domain routing; avoid rolling back only one side of that migration. Do not restore a dependency on the retired R2 docs objects. Unrelated Cloudflare resources are outside this setup.