Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
69 lines (56 loc) · 3.31 KB

DEPLOYMENT.md

File metadata and controls

69 lines (56 loc) · 3.31 KB
Raw

Website deployment

The marketing and documentation site is deployed to Vercel from this monorepo. The application configuration in apps/web/vercel.json is the source of truth for framework detection, build and development commands, and output location. Vercel derives pnpm from the repository lockfile. Do not add an install override with plain pnpm install: Vercel uses its oldest available pnpm runtime for that override, while this repository requires pnpm 9 or newer.

Production contract

  • Production branch: main.
  • Production URL: https://headless-web-pi.vercel.app.
  • Project root: apps/web.
  • Application: @headless/web.
  • Security headers: apps/web/next.config.ts. Do not duplicate them in vercel.json, where they could drift from local and CI builds.

The Vercel project alias is the canonical domain for now. The LockInTime organization does not publish a verifiable custom domain in repository or organization metadata, so this project must not claim one. A custom domain can replace the alias only after a maintainer confirms control of its DNS. That change must update apps/web/lib/site-metadata.ts, the GitHub repository homepage, this document, and the Vercel production-domain assignment together.

GitHub integration

Connect the LockInTime/headless repository through Vercel for GitHub with these project settings:

  1. Set Root Directory to apps/web so Vercel reads the application-local vercel.json and detects Next.js from the application package.
  2. Enable "Include source files outside of the Root Directory in the Build Step". The site imports checked-in documentation and package metadata from the repository root, apps/headless, and packages during its build.
  3. Set the production branch to main.
  4. Keep preview deployments enabled for pull requests and branch pushes.
  5. Keep pull-request comments enabled so each PR receives its immutable preview URL. Keep deployment status events enabled so the URL also appears in the GitHub deployment timeline.
  6. Do not add a second token-driven GitHub Actions deployment. Two independent deployers can race production aliases and make rollback history ambiguous.

The integration is an account-level control and cannot be stored in git. If a PR has no Vercel deployment or preview link, treat that as a disconnected or disabled integration. A Vercel project maintainer must reconnect the repository under Project Settings, Git before the PR is considered deployment-verified.

Verification

Run the same web gates locally before pushing:

pnpm install --frozen-lockfile --filter @headless/web
pnpm --filter @headless/web lint
pnpm --filter @headless/web build

For a pull request, open the Vercel preview from the PR deployment entry and check the homepage, one docs route, robots.txt, and sitemap.xml. Confirm the response still carries the CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy headers declared in apps/web/next.config.ts.

After merging, verify that the production deployment points at the merge commit and that https://headless-web-pi.vercel.app serves it. Vercel keeps prior production deployments available for rollback. Roll back in Vercel, then revert the faulty commit in git so repository history and production converge.