Getting started

This gets a new developer from nothing to a running configurator, and explains how a change reaches production.

1. Prerequisites

Tool	Why	Install (macOS)
Node 18+ (22 recommended)	run the app / local dev server	brew install node
git	version control	brew install git
GitHub CLI (gh)	clone + repo access	brew install gh
Vercel CLI	deploys / env / domains	npm i -g vercel
Docker + colima (optional)	a local Odoo for full end-to-end testing	brew install docker colima

2. Authenticate & clone

# GitHub — sign in as the account with access to the private repos
gh auth login                       # GitHub.com → HTTPS → tech-goask (or your team account)

gh repo clone tech-goask/goask-3d-configurator
cd goask-3d-configurator

Commit author must be a Vercel team member

Vercel blocks the deploy if the commit author’s email is not on the Vercel team (“the commit author doesn’t have permission”).

• Adam owns the team → your own email works, nothing to change.
• On the shared tech-goask account, set it once per clone:

git config user.email "tech@goask.com.au"
git config user.name  "tech-goask"

3. Run it locally

serve.mjs is a local dev server that actually runs the /api/* functions (a plain static server like python http.server can’t). It auto-issues a demo session cookie and stubs email/SMS so the GUI shows a clean success.

node serve.mjs        # http://localhost:8123 — runs the /api functions + serves static

To exercise the Odoo price sync and quote push, point it at an Odoo:

export ODOO_URL=http://localhost:8069 ODOO_DB=chivalry ODOO_USER=admin ODOO_PW=admin
node serve.mjs

localhost resolves to the default tenant (DEFAULT_TENANT, ozchivalry). To test another tenant locally, add localhost to that tenant’s hosts in tenants/<slug>.json, or send a Host: header.

4. Environment variables

The app is inert without configuration — each integration only fires when its env vars are set.

Var	Purpose
VIZ_SECRET	required — signs the session cookie; without it the gate fails closed
SUPABASE_URL, SUPABASE_SERVICE_KEY	leads + people + analytics store
ODOO_URL_<ENV>, ODOO_DB_<ENV>, ODOO_USER_<ENV>, ODOO_PW_<ENV>	per-tenant Odoo (unsuffixed vars are a local single-tenant fallback)
RESEND_API_KEY, EMAIL_FROM, LEAD_NOTIFY_TO	email lead backup
ANSWER_INTAKE_URL, ANSWER_INTAKE_TOKEN	forward leads to GoAsk Answer
HUBSPOT_TOKEN	HubSpot contact/deal push
VIZ_DEMO_CODES, VIZ_STAFF_CODES, VIZ_DEALER_CODES, VIZ_MFR_CODES	legacy shared access codes (prefer per-user accounts)
DEFAULT_TENANT	tenant used when the host matches none (default ozchivalry)

Never commit secrets

Credentials live in Vercel env vars, never in files. .env* is gitignored — keep it that way.

5. The deploy model (read this once)

Push to main = deploy to production. There is no separate deploy step — Vercel auto-deploys every push to main.

flowchart LR
  A[edit locally] --> B[node serve.mjs<br/>test the real flow]
  B --> C[commit<br/>author = Vercel team member]
  C --> D[git push main]
  D --> E[Vercel builds & deploys<br/>production]

• The live demos (ozchivalrydemo.goask.com.au, duratraydemo.goask.com.au) are shown to clients — never push half-finished work to main. Use a branch + PR for anything risky.
• Do not run vercel deploy from a laptop — that reintroduces drift (local ≠ GitHub). GitHub is the single source of truth.

Before you push — checklist

1. node serve.mjs, unlock with demo, build a ute, click Get my build.
2. Confirm the quote appears in the tenant’s Odoo (Sales → Quotations).
3. Commit author email is a Vercel team member.
4. No secrets in the diff.