link,[object Object]
ACQM Docs

Appearance

Deployment Guide ​

Purpose: Explain how to build and deploy the app across environments. Audience: Owner, Developer Prerequisites: Access to hosting (e.g., Netlify/Vercel/S3+CloudFront) and Supabase project.

Environments

  • Local: Vite dev server with Supabase CLI or remote Supabase.
  • Staging/Prod: Static hosting for SPA + Supabase (DB/Auth/Storage/Functions).

Branch → Environment mapping (current)

  • Stage: branch stage → https://dev.acqmarketplace.com
    • Deploy: auto on push to stage
    • Robots: Disallow (no indexing). Build with NODE_ENV=staging
    • Sitemap: optional/off (skip or generate with staging base URL)
  • Production: branch main → https://acqmarketplace.com
    • Deploy: manual or by tag v* after merge from stage
    • Robots: Allow. Build with NODE_ENV=production
    • Sitemap: generate and publish

Build

  • Install deps: pnpm i (or npm i)
  • Generate robots: pnpm generate-robots
  • Production build: pnpm build
  • Preview locally: pnpm preview

Recommended build commands per environment

  • Stage (static hosting or Coolify Static Site):
    • pnpm install --frozen-lockfile
    • NODE_ENV=staging pnpm build (generates robots.txt with Disallow)
    • Optional: skip sitemap, or run node scripts/generate-sitemap.js with staging base URL
  • Production:
    • pnpm install --frozen-lockfile
    • NODE_ENV=production pnpm build (robots Allow) && node scripts/generate-sitemap.js

Static hosting

  • Output directory: dist/
  • SPA fallback: Configure 404 to serve index.html (React Router).
  • CDN caching: Long-cache hashed assets; short-cache index.html.

Hosting (Coolify example)

  • Type: Static Site
  • Repo branch: stage (Stage) / main (Prod)
  • Install: pnpm install --frozen-lockfile
  • Build: see "Recommended build commands per environment"
  • Publish directory: dist
  • Health check: /index.html (or a custom /health endpoint if served by a backend)

Supabase

  • Project: Use an existing Supabase project (redacted).
  • Link CLI (redacted ref): supabase link --project-ref YOUR_SUPABASE_PROJECT_REF
  • Migrations: supabase db push or supabase migration up if you maintain SQL migrations.
  • Edge Functions: supabase functions deploy <name> for each function in supabase/functions/*.

Recommended separation

  • Use distinct Supabase projects for Stage vs Prod (separate URLs/keys).
  • Stripe: Test keys in Stage, Live keys in Prod; separate webhook endpoints.

Environment variables (hosting)

  • VITE_SUPABASE_URL: https://YOUR_SUPABASE_PROJECT_REF.supabase.co
  • VITE_SUPABASE_PUBLISHABLE_KEY: Your Supabase anon key
  • VITE_STRIPE_PUBLISHABLE_KEY: Your Stripe publishable key
  • Do not store secrets in client env; Stripe secret and Supabase service role belong server-side (Edge Functions).

Base URL

  • Stage: VITE_BASE_URL=https://dev.acqmarketplace.com
  • Production: VITE_BASE_URL=https://acqmarketplace.com

Dev server proxy

  • Functions proxy: vite.config.ts:12-17 proxies /functions/v1 to local Supabase.
  • If hosting functions separately, ensure VITE_SUPABASE_URL points to right origin.

Security and headers

  • Enforce HTTPS and HSTS.
  • CSP: Restrict to Supabase, Stripe, your CDN, and fonts.
  • Cache-Control: index.html no-cache; assets immutable.

Rollback

  • Keep previous deployment bundle.
  • Use CDN versioning or hosting platform’s rollback.

Next steps

  • See docs/operations/monitoring.md for health checks and alerting.
  • See docs/setup/environment.md for full env config.

DNS & SSL (summary)

  • dev.acqmarketplace.com → Stage app (automatic SSL via platform)
  • acqmarketplace.com (and www) → Prod app (automatic SSL via platform)

Docs (VitePress) on Cloudflare Pages — manual deploy (decoupled from app) ​

Disable automatic deploys in Cloudflare Pages UI for the docs project:

  • Production branch: main (or your choice)
  • Uncheck: “Enable automatic production branch deployments”
  • Preview branch: None (Disable automatic branch deployments)

Local commands (PowerShell):

powershell
# one-time: add CLI
pnpm add -D wrangler

# one-time: scripts for docs
pnpm pkg set "scripts.docs:build=vitepress build docs" "scripts.docs:deploy:cf=wrangler pages deploy docs/.vitepress/dist --project-name acqm-docs --branch docs"

# one-time: authenticate
pnpm dlx wrangler login

# manual publish (only docs)
pnpm docs:build
pnpm docs:deploy:cf

Recommended (avoid local binary issues):

powershell
# Use dlx in the deploy script
pnpm pkg set "scripts.docs:deploy:cf=pnpm dlx wrangler pages deploy docs/.vitepress/dist --project-name acqm-docs --branch docs"

# Login (if not logged in)
pnpm dlx wrangler login

# Deploy
pnpm docs:deploy:cf

Non-interactive (CI or without browser login):

powershell
$env:CLOUDFLARE_ACCOUNT_ID="<ACCOUNT_ID>"
$env:CLOUDFLARE_API_TOKEN="<PAGES_API_TOKEN>"
pnpm docs:build
pnpm docs:deploy:cf

Custom domain for docs (optional):

powershell
pnpm dlx wrangler pages custom-domains add docs.acqmarketplace.com --project-name acqm-docs

Notes:

  • Docs build output: docs/.vitepress/dist
  • App build output: dist/ (separate hosting/deploy)
  • Keep docs/.vitepress/cache/ out of git (.gitignore).