Danncode10 / Danncode10/business-template

[Docs] Document the required setup (env vars, first-admin, deployment) before editing a new client site

Open
#7 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Goal
The template is missing a clear "before you build" setup guide. A new client site should have a documented checklist of what to configure **first** — env vars, Supabase wiring, the first admin account, and per-deployment values — so we (or future contributors) don't start editing the website before the tenant plumbing is correct.

> 📌 Tracking/note only — **not** to be solved now. Captured so we don't lose it.

## Why this matters
While fixing #5 we found several env vars the code already depends on are **undocumented** in `.env.example`, and one (`NEXT_PUBLIC_APP_ID`) is used with a non-null assertion (`process.env.NEXT_PUBLIC_APP_ID!` in `src/services/logs.ts`, `src/services/overview.ts`) that will **throw at runtime if unset**. A new deployment can silently break or — worse — skip tenant isolation if `NEXT_PUBLIC_ORG_ID` is forgotten.

## What to document

### 1. `.env.example` — add the missing vars (still NOT done — blocked in agent env)
```bash
# Multi-Tenant / Project Namespace
NEXT_PUBLIC_APP_ID=business-template # project namespace slug (shared Supabase across projects)
NEXT_PUBLIC_ORG_ID= # THIS client's organization UUID — required for strict tenant isolation
NEXT_PUBLIC_ALLOW_PUBLIC_SIGNUP=false # true = open registration; default = invite-only
```
Existing documented vars: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `NEXT_PUBLIC_SITE_NAME`, `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_GITHUB_URL`.

Also referenced in code but worth auditing for `.env.example` coverage: `SUPABASE_PROJECT_ID` (used by `scripts/update-types.sh`), Upstash Redis vars (rate limiting), any SMTP/email vars.

### 2. A "New Client Setup" guide (README and/or `docs/`)
A step-by-step, ordered checklist:
1. Create / point to the Supabase project; copy URL + anon + service-role keys.
2. Create the client's `organizations` row → capture its `id`.
3. Set per-deployment env: `NEXT_PUBLIC_APP_ID`, `NEXT_PUBLIC_ORG_ID`, branding vars.
4. Provision the **first admin** `profiles` row (org membership) — without it the dashboard gate denies everyone (see #5). Document the seed/invite path.
5. Decide signup policy (`NEXT_PUBLIC_ALLOW_PUBLIC_SIGNUP`).
6. Verify RLS isolation (`/rls-check`) before going live.
7. Enable Auth leaked-password protection.
8. Vercel deployment env checklist.

### 3. Cross-references to reconcile
- `CLAUDE.md` mentions a `team_members` table for membership, but membership actually lives in `profiles` (`organization_id` + `app_id` + `role`). Pick one source of truth and fix the docs (likely run `/no-conflict`).
- Link the tenant-isolation model (gate + RLS) from #5 / PR #6.

## Acceptance criteria (for when we do tackle it)
- [ ] `.env.example` lists every env var the app reads, with inline comments.
- [ ] A discoverable "New Client Setup" checklist exists (README or `docs/`).
- [ ] First-admin provisioning is documented (and ideally scripted, e.g. a seed command).
- [ ] `CLAUDE.md` / docs no longer reference a non-existent `team_members` table.
- [ ] Note which vars are required vs optional, and which are per-deployment vs shared.

## Related
- Depends on the model introduced in #5 / PR #6.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.