Files
webb/SETUP_README.md
T

141 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🚀 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)**