Local Development Environment Setup Guide

This document is the authoritative engineering onboarding specification for setting up, configuring, running, and debugging the complete Debelu multi-surface monorepo on a local developer workstation. Grounded directly in [package.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/package.json), the npm workspace configuration, and local Supabase CLI orchestration, this guide transitions a newly cloned repository to an active, fully functional development stack.

1. Prerequisites & Toolchain Verification

Ensure your workstation satisfies the following strict runtime toolchain requirements:

Tool	Required Version	Verification Command	Installation / Reference
Node.js	`>= 22.0.0` (LTS)	`node -v`	Use nvm or fnm: `nvm use 22`
npm	`>= 10.9.2`	`npm -v`	Bundled with Node 22 (`npm install -g npm@10.9.2`)
Docker Desktop	Latest (Compose v2)	`docker --version`	Required to run the local Supabase PostgreSQL container stack
Supabase CLI	`>= 1.150.0`	`supabase -v`	macOS: `brew install supabase/tap/supabase` Windows: `scoop bucket add supabase https://github.com/supabase/scoop-bucket.git && scoop install supabase`
Git	`>= 2.40.0`	`git --version`	Ensure `core.autocrlf` is set to `false` or `input` on Windows

2. Monorepo Clone & Clean Installation

Debelu uses npm workspaces. Dependencies across shared packages (@debelu/core, @debelu/ui) and applications are hoisted and linked automatically at the workspace root.

bash

# 1. Clone the repository
git clone https://github.com/ChisomFrankline/new-debelu.git
cd "new-debelu"

# 2. Perform a clean, reproducible dependency install
# ALWAYS use 'npm ci' rather than 'npm install' to ensure lockfile compliance
npm ci

IMPORTANT

Why npm ci is Mandatory: Running npm install can arbitrarily update transient sub-dependencies or modify package-lock.json, causing subtle React 19 peer-dependency mismatches. npm ci validates the package tree against the lockfile without mutating it.

3. Environment Variable Provisioning

The monorepo requires dedicated environment configurations per surface. Never commit .env or .env.local files to source control.

mermaid

graph TD
    Root[Monorepo Root] --> BackendEnv["debelu-backend/.env<br/>(Server Secrets: Service Role, Paystack Secret, Gemini Key)"]
    Root --> StorefrontEnv["apps/storefront/.env.local<br/>(Client Public: Anon Key, VITE_API_BASE_URL)"]
    Root --> MarketingEnv["debelu-marketing/.env.local<br/>(Next.js Public: NEXT_PUBLIC_SUPABASE_URL)"]

3.1 Backend API (`debelu-backend/.env`)

Copy the backend example template:

bash

cp debelu-backend/.env.example debelu-backend/.env

Key configuration values for local development:

dotenv

PORT=8000
NODE_ENV=development

# Local Supabase credentials (obtained after running 'supabase start')
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Google AI Studio API Key for Nduzi AI Assistant
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash

# Paystack Test Gateway Credentials (use sk_test_...)
PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
PAYSTACK_DVA_BANK=test-bank

# CORS Allowlist (include local dev origins)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost:5174

# Background maintenance daemon
MAINTENANCE_JOBS=on

3.2 Storefront Application (`apps/storefront/.env.local`)

bash

cp apps/storefront/.env.example apps/storefront/.env.local

dotenv

# Supabase Local Stack
VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Paystack Public Key (NEVER use secret keys here)
VITE_PAYSTACK_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Local Service Base URLs
VITE_API_BASE_URL=http://localhost:8000/api
VITE_MARKETING_URL=http://localhost:3000
VITE_APP_URL=http://localhost:5173
VITE_VENDOR_URL=http://localhost:5173/sell
VITE_ADMIN_URL=http://localhost:5174

# Toggle R2 product image uploads
VITE_R2_PRODUCT_IMAGES=false

3.3 Marketing Site (`debelu-marketing/.env.local`)

bash

cp debelu-marketing/.env.example debelu-marketing/.env.local

dotenv

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_API_URL=http://localhost:8000/api
NEXT_PUBLIC_STOREFRONT_URL=http://localhost:5173

4. Local Database Stack Orchestration (Supabase CLI)

Debelu utilizes the official Supabase Docker container stack for local database execution, auth emulation, and storage simulation.

mermaid

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant CLI as Supabase CLI
    participant Docker as Docker Engine (Postgres + Kong + Inbucket)

    Dev->>CLI: supabase start
    CLI->>Docker: Launches Postgres (Port 54322), Kong API (54321), Studio (54323)
    Docker-->>CLI: Stack healthy; emits local service_role & anon keys
    Dev->>CLI: supabase db reset
    CLI->>Docker: Drops local DB, executes all 97 migrations, and seeds test data
    Docker-->>CLI: Database clean and migrations up to date
    Dev->>Dev: Copy generated keys into .env and .env.local files

4.1 Launching the Local Stack

bash

# Start Docker containers (Postgres, GoTrue Auth, Realtime, Storage, Kong Gateway)
supabase start

# Apply all migrations from scratch and run seed scripts
supabase db reset

Upon completion, Supabase outputs local access credentials:

API URL: http://127.0.0.1:54321
GraphQL URL: http://127.0.0.1:54321/graphql/v1
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
Studio Web UI: http://127.0.0.1:54323
Inbucket Local Email UI: http://127.0.0.1:54324

4.2 Seeding Local Campus Data

bash

# Seed initial categories, campus hubs, and test product listings
node scripts/seed_via_service_role.js

5. Starting Development Servers

Run the required development servers in separate terminal panes or via concurrent commands:

mermaid

graph LR
    API["npm run dev --workspace=debelu-backend<br/>Port 8000: Express REST API"]
    SF["npm run dev --workspace=@debelu/storefront<br/>Port 5173: Vite Buyer/Vendor SPA"]
    MKT["npm run dev --workspace=debelu-marketing<br/>Port 3000: Next.js Marketing & Auth"]
    Admin["npm run dev --workspace=debelu-admin<br/>Port 5174: Vite Admin Console"]

5.1 Individual Workspaces

bash

# 1. Start Backend Express API
npm run dev --workspace=debelu-backend

# 2. Start Storefront (Buyer & Vendor SPA)
npm run dev --workspace=@debelu/storefront

# 3. Start Marketing & Public Auth Portal
npm run dev --workspace=debelu-marketing

# 4. Start Admin & Operations Console
npm run dev --workspace=debelu-admin

6. Verifying Setup & Health Probes

Verify that all subsystems are communicating properly before writing code:

Backend Liveness & Deep Readiness:

bash

curl -i http://localhost:8000/health/live
# Expect HTTP 200 OK: {"status":"live"}

curl -i http://localhost:8000/health/ready
# Expect HTTP 200 OK: {"status":"ready"}

SRE Diagnostic Dashboard:

bash

curl -s http://localhost:8000/health | jq .
# Verify checks: { "supabase": "ok", "gemini": "operational", "paystack": "operational" }

Public Status Screen:

bash

curl -s http://localhost:8000/api/status | jq .
# Verify maintenance flag is false

Browser Verification:
- Open http://localhost:5173/buy to verify the buyer storefront and campus selector.
- Open http://localhost:3000 to verify the marketing homepage and SEO rendering.
- Open http://127.0.0.1:54323 to inspect local database tables via Supabase Studio.

7. IDE Configuration & Code Quality Standards

7.1 Recommended VS Code Extensions

TypeScript & JavaScript Language Features (vscode.typescript-language-features)
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
ESLint (dbaeumer.vscode-eslint)
Prettier - Code formatter (esbenp.prettier-vscode)
Even Better TOML / Docker / Mermaid Preview

7.2 Code Style & Lint Enforcement

The monorepo uses ESLint 9 Flat Config (eslint.config.base.js) and unified Prettier settings (.prettierrc):

bash

# Run static type checking across all workspaces
npm run type-check

# Run linter across all workspaces
npm run lint

# Run global automated unit and integration tests
npm test

8. Troubleshooting Common Local Issues

Issue / Symptom	Root Cause	Solution
`EADDRINUSE: address already in use :::8000`	Stale Node.js or Docker process occupying port 8000.	Run `npx kill-port 8000` or inspect `netstat -ano \| findstr :8000` on Windows.
`Postgres connection error: 127.0.0.1:54322 connection refused`	Supabase Docker container stack is stopped or paused.	Run `supabase status` followed by `supabase start`. Ensure Docker Desktop is active.
`Vite CSP Nonce or React Hydration Mismatch`	Stale cache in Vite or Next.js build directories.	Run `rm -rf apps/storefront/node_modules/.vite debelu-marketing/.next` and restart dev servers.
`CORS Error: No 'Access-Control-Allow-Origin' header`	Origin mismatch between client and backend.	Verify `ALLOWED_ORIGINS` in `debelu-backend/.env` contains your client URL (`http://localhost:5173`).
`Supabase RLS Violation (Postgres 42501)`	Client attempting direct query without required auth role.	Ensure test queries authenticate with a valid JWT or run privileged operations via `SUPABASE_SERVICE_ROLE_KEY`.

9. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
`1.0.0`	2026-10-05	Principal Staff Engineer	Initial enterprise local development onboarding specification covering prerequisites, toolchain, environment provisioning, Supabase CLI, and verification probes.	Active Living Standard

Local Development Environment Setup Guide ​

1. Prerequisites & Toolchain Verification ​

2. Monorepo Clone & Clean Installation ​

3. Environment Variable Provisioning ​

3.1 Backend API (debelu-backend/.env) ​

3.2 Storefront Application (apps/storefront/.env.local) ​

3.3 Marketing Site (debelu-marketing/.env.local) ​

4. Local Database Stack Orchestration (Supabase CLI) ​

4.1 Launching the Local Stack ​

4.2 Seeding Local Campus Data ​

5. Starting Development Servers ​

5.1 Individual Workspaces ​

6. Verifying Setup & Health Probes ​

7. IDE Configuration & Code Quality Standards ​

7.1 Recommended VS Code Extensions ​

7.2 Code Style & Lint Enforcement ​

8. Troubleshooting Common Local Issues ​

9. Document Revision History ​

Local Development Environment Setup Guide

1. Prerequisites & Toolchain Verification

2. Monorepo Clone & Clean Installation

3. Environment Variable Provisioning

3.1 Backend API (`debelu-backend/.env`)

3.2 Storefront Application (`apps/storefront/.env.local`)

3.3 Marketing Site (`debelu-marketing/.env.local`)

4. Local Database Stack Orchestration (Supabase CLI)

4.1 Launching the Local Stack

4.2 Seeding Local Campus Data

5. Starting Development Servers

5.1 Individual Workspaces

6. Verifying Setup & Health Probes

7. IDE Configuration & Code Quality Standards

7.1 Recommended VS Code Extensions

7.2 Code Style & Lint Enforcement

8. Troubleshooting Common Local Issues

9. Document Revision History