From 58056f39f11abdb99ea81c42c01d0c30135c1859 Mon Sep 17 00:00:00 2001 From: vshnosngh Date: Fri, 6 Nov 2026 18:47:51 +0530 Subject: [PATCH] docs: add SETUP_README home PC setup guide --- README.md | 1 + SETUP_README.md | 140 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 141 insertions(+) create mode 100644 SETUP_README.md diff --git a/README.md b/README.md index 4d7b639..e463eb6 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ > Built strictly to specification from `PROJECT_REQUIREMENT_DOCUMENTATION.md` (PRD v1.1). > Dynamic React (Next.js App Router + TypeScript + Tailwind CSS) marketing and try-it engine driven by JSON content and an external, replaceable API Catalogue connected to `FastAPI_BACKEND`. > +> ๐Ÿ“˜ **Home PC Setup Guide (What to do after clone):** See [SETUP_README.md](./SETUP_README.md). > ๐Ÿ“˜ **Multi-Location Sync & Branching Guide:** See [GIT_README.md](./GIT_README.md). --- diff --git a/SETUP_README.md b/SETUP_README.md new file mode 100644 index 0000000..a4be422 --- /dev/null +++ b/SETUP_README.md @@ -0,0 +1,140 @@ +# ๐Ÿš€ Home PC Setup Guide: CRE Innovations (`WEBB`) + +This step-by-step guide explains exactly how to set up and run this website on your home computer from scratch after cloning. + +--- + +## ๐Ÿ“‹ Step 0: Check Prerequisites + +Before starting, make sure your home PC has **Node.js** and **Git** installed. + +Open your terminal (Command Prompt, PowerShell, or macOS/Linux Terminal) and run: + +```bash +node -v +npm -v +git --version +``` + +* **Node.js**: Recommended version is **Node 18.17+** or **Node 20+** (LTS). + *(If you don't have Node.js installed, download the LTS version from [nodejs.org](https://nodejs.org/)).* + +--- + +## ๐Ÿ“ฅ Step 1: Clone the Repository + +Choose a folder on your home PC where you keep your coding projects (for example, `Desktop` or `Projects`), open your terminal in that folder, and run: + +```bash +git clone https://github.com/vaishnosingh/webb.git +``` + +Then move into the project directory: + +```bash +cd webb +``` + +--- + +## ๐Ÿ“ฆ Step 2: Install Project Dependencies + +Install all required packages (Next.js, React, Tailwind CSS, Lucide, Framer Motion, Lenis, Three.js, etc.): + +```bash +npm install +``` + +> **Note:** This will create your local `node_modules/` folder. It usually takes 30โ€“60 seconds depending on your internet connection. + +--- + +## โš™๏ธ Step 3: Environment Configuration (Optional) + +The website works **100% out of the box** without any `.env` file because it includes safe fallback defaults and an automatic simulated neural mock engine. + +If you want to configure custom ports or backend endpoints, you can optionally create a `.env.local` file in the root folder: + +```env +# Optional configuration: +SITE_URL=http://localhost:3000 +API_BACKEND_URL=http://127.0.0.1:6666 +``` + +> **Note:** If the local Python FastAPI GPU cluster (`http://127.0.0.1:6666`) is not running on your home PC, you can still test every photo tool seamlessly! The website has a built-in neural simulation engine (`mockEngine.ts`) that automatically returns high-fidelity results. + +--- + +## ๐Ÿ’ป Step 4: Run the Development Server + +Start the local Next.js development server: + +```bash +npm run dev +``` + +You will see output like: +```text + โ–ฒ Next.js 14.2.35 + - Local: http://localhost:3000 + - Network: http://0.0.0.0:3000 + + โœ“ Ready in 1.5s +``` + +Now, open your web browser (Chrome, Brave, Edge, Safari, Firefox) and navigate to: +๐Ÿ‘‰ **[http://localhost:3000](http://localhost:3000)** + +--- + +## ๐Ÿงช Step 5: Verify the Build & Tests (Sanity Check) + +To verify that all 19 unit tests pass and the production build compiles cleanly on your home machine: + +### Run unit tests: +```bash +npm test +``` +*(All 19 Vitest unit tests should pass with green checkmarks).* + +### Test production build: +```bash +npm run build +``` +*(Confirms that all 18 static & dynamic pages compile with 0 TypeScript errors).* + +--- + +## ๐Ÿ› ๏ธ Common Issues & How to Fix Them + +### 1. "Port 3000 is already in use" +If another app on your home PC is using port 3000, either stop that process or start this site on port 3001: +```bash +npm run dev -- -p 3001 +``` +Then visit `http://localhost:3001`. + +### 2. "Node version mismatch or unsupported engine" +If you get Node syntax errors, verify your Node version with `node -v`. If it is older than version 18, update Node.js to the latest LTS from [nodejs.org](https://nodejs.org/). + +### 3. "Permission denied when pushing to GitHub" +When pushing changes from your home PC, GitHub requires a **Personal Access Token** (PAT) instead of your regular account password: +* Username: your GitHub username (`vaishnosingh`) +* Password: your GitHub Personal Access Token (starts with `ghp_...`) + +To prevent typing it every time on your home PC: +```bash +git config --global credential.helper store +``` + +--- + +## ๐Ÿ”„ Daily Workflow (Syncing Back to Office) + +Once you make changes at home and want to continue at the office tomorrow: +1. `git add .` +2. `git commit -m "feat: work done at home"` +3. `git push origin main` + +For the full multi-location syncing guide and branching cheatsheet, read: +๐Ÿ‘‰ **[GIT_README.md](./GIT_README.md)**