VIBN Frontend for Coolify deployment
This commit is contained in:
318
SETUP.md
Normal file
318
SETUP.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 🚀 VIBN Local Development Setup
|
||||
|
||||
Complete guide to running VIBN locally on your machine.
|
||||
|
||||
## ✅ Prerequisites
|
||||
|
||||
- **Node.js** 18+ (check with `node --version`)
|
||||
- **npm** or **pnpm** package manager
|
||||
- **Firebase Project** (for authentication and database)
|
||||
- **GitHub OAuth App** (optional, for GitHub integration)
|
||||
|
||||
---
|
||||
|
||||
## 📦 Step 1: Install Dependencies
|
||||
|
||||
```bash
|
||||
cd vibn-frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Step 2: Environment Variables
|
||||
|
||||
Create a `.env.local` file in the `vibn-frontend` directory:
|
||||
|
||||
```bash
|
||||
touch .env.local
|
||||
```
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
Copy and paste the following into `.env.local` and replace with your actual values:
|
||||
|
||||
```env
|
||||
# ===================================
|
||||
# Firebase Client Config (Public)
|
||||
# Get these from Firebase Console > Project Settings > General
|
||||
# ===================================
|
||||
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
|
||||
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
|
||||
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
|
||||
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
|
||||
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
|
||||
NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id
|
||||
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX
|
||||
|
||||
# ===================================
|
||||
# Firebase Admin Config (Server-side ONLY)
|
||||
# Get these from Firebase Console > Project Settings > Service Accounts
|
||||
# Click "Generate New Private Key" to download JSON file
|
||||
# ===================================
|
||||
FIREBASE_PROJECT_ID=your_project_id
|
||||
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your_project_id.iam.gserviceaccount.com
|
||||
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour_Private_Key_Here\n-----END PRIVATE KEY-----\n"
|
||||
|
||||
# ===================================
|
||||
# GitHub OAuth (Optional)
|
||||
# Create an OAuth App at: https://github.com/settings/developers
|
||||
# Authorization callback URL: http://localhost:3000/api/github/oauth/callback
|
||||
# ===================================
|
||||
NEXT_PUBLIC_GITHUB_CLIENT_ID=your_github_oauth_client_id
|
||||
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Step 3: Firebase Setup
|
||||
|
||||
### 3.1 Get Firebase Credentials
|
||||
|
||||
1. Go to [Firebase Console](https://console.firebase.google.com/)
|
||||
2. Select your project (or create a new one)
|
||||
3. Navigate to **Project Settings** (⚙️ icon)
|
||||
|
||||
#### Client Config (Public):
|
||||
- Under **General** tab, scroll to "Your apps"
|
||||
- Copy the `firebaseConfig` values
|
||||
- These go in `NEXT_PUBLIC_FIREBASE_*` variables
|
||||
|
||||
#### Admin Config (Private):
|
||||
- Go to **Service Accounts** tab
|
||||
- Click **Generate New Private Key**
|
||||
- Download the JSON file
|
||||
- Extract values:
|
||||
- `FIREBASE_PROJECT_ID` = `project_id` from JSON
|
||||
- `FIREBASE_CLIENT_EMAIL` = `client_email` from JSON
|
||||
- `FIREBASE_PRIVATE_KEY` = `private_key` from JSON (keep the `\n` characters!)
|
||||
|
||||
### 3.2 Enable Authentication
|
||||
|
||||
1. In Firebase Console, go to **Authentication** → **Sign-in method**
|
||||
2. Enable **Email/Password**
|
||||
3. Enable **Google** (optional)
|
||||
|
||||
### 3.3 Setup Firestore
|
||||
|
||||
1. In Firebase Console, go to **Firestore Database**
|
||||
2. Click **Create database**
|
||||
3. Choose **Start in production mode** (we have custom rules)
|
||||
4. Select a location (closest to your users)
|
||||
|
||||
### 3.4 Deploy Firestore Rules & Indexes
|
||||
|
||||
```bash
|
||||
# Deploy security rules
|
||||
npm run firebase:deploy:rules
|
||||
|
||||
# Deploy indexes
|
||||
npm run firebase:deploy:indexes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐙 Step 4: GitHub OAuth Setup (Optional)
|
||||
|
||||
Only needed if you want to test GitHub repository integration.
|
||||
|
||||
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
|
||||
2. Click **New OAuth App**
|
||||
3. Fill in:
|
||||
- **Application name**: VIBN Local
|
||||
- **Homepage URL**: `http://localhost:3000`
|
||||
- **Authorization callback URL**: `http://localhost:3000/api/github/oauth/callback`
|
||||
4. Copy **Client ID** → `NEXT_PUBLIC_GITHUB_CLIENT_ID`
|
||||
5. Generate **Client Secret** → `GITHUB_CLIENT_SECRET`
|
||||
|
||||
---
|
||||
|
||||
## 🏃 Step 5: Run the Development Server
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The app will be available at **http://localhost:3000**
|
||||
|
||||
### First Time Setup
|
||||
|
||||
1. **Create an account**: Click "Get Started" or go to `/auth`
|
||||
2. **Sign up** with email/password or Google
|
||||
3. **Create your first project**: Click "New Project"
|
||||
4. **Start coding**: Open your project in Cursor and install the monitor extension
|
||||
|
||||
---
|
||||
|
||||
## 📂 Development Scripts
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Start production server
|
||||
npm start
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
|
||||
# Deploy Firebase rules
|
||||
npm run firebase:deploy:rules
|
||||
|
||||
# Deploy Firebase indexes
|
||||
npm run firebase:deploy:indexes
|
||||
|
||||
# Run Firebase emulators (test without production database)
|
||||
npm run firebase:emulators
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Troubleshooting
|
||||
|
||||
### Firebase Admin "Credentials not configured"
|
||||
|
||||
**Problem**: API routes throw errors about Firebase Admin not being initialized.
|
||||
|
||||
**Solution**: Make sure your `.env.local` has all three `FIREBASE_*` variables (not `NEXT_PUBLIC_`):
|
||||
- `FIREBASE_PROJECT_ID`
|
||||
- `FIREBASE_CLIENT_EMAIL`
|
||||
- `FIREBASE_PRIVATE_KEY`
|
||||
|
||||
Make sure the private key includes `\n` for newlines and is wrapped in quotes.
|
||||
|
||||
### "Failed to fetch" or CORS errors
|
||||
|
||||
**Problem**: Client can't connect to Firebase.
|
||||
|
||||
**Solution**:
|
||||
1. Check that all `NEXT_PUBLIC_FIREBASE_*` variables are set correctly
|
||||
2. Make sure Firebase Authentication is enabled in the console
|
||||
3. Check browser console for specific error messages
|
||||
|
||||
### Dev server won't start
|
||||
|
||||
**Problem**: Port 3000 is already in use.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Find what's using port 3000
|
||||
lsof -i :3000
|
||||
|
||||
# Kill the process
|
||||
kill -9 <PID>
|
||||
|
||||
# Or use a different port
|
||||
PORT=3001 npm run dev
|
||||
```
|
||||
|
||||
### Changes not showing up
|
||||
|
||||
**Problem**: You made code changes but they're not reflected in the browser.
|
||||
|
||||
**Solution**:
|
||||
1. Hard refresh: `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows)
|
||||
2. Clear Next.js cache: `rm -rf .next`
|
||||
3. Restart the dev server
|
||||
|
||||
---
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
vibn-frontend/
|
||||
├── app/ # Next.js App Router
|
||||
│ ├── (marketing)/ # Marketing site (public)
|
||||
│ │ └── page.tsx # Homepage
|
||||
│ ├── [workspace]/ # Workspace pages (authenticated)
|
||||
│ │ ├── projects/ # Projects list
|
||||
│ │ ├── connections/ # API connections & keys
|
||||
│ │ └── project/[id]/ # Individual project pages
|
||||
│ ├── auth/ # Authentication pages
|
||||
│ ├── api/ # API routes
|
||||
│ │ ├── sessions/ # Session tracking
|
||||
│ │ ├── projects/ # Project management
|
||||
│ │ ├── github/ # GitHub OAuth
|
||||
│ │ └── stats/ # Analytics
|
||||
│ └── layout.tsx # Root layout
|
||||
├── components/ # React components
|
||||
│ ├── layout/ # Layout components (left rail, sidebar, etc)
|
||||
│ ├── ui/ # shadcn/ui components
|
||||
│ └── *.tsx # Feature components
|
||||
├── lib/ # Utility libraries
|
||||
│ ├── firebase/ # Firebase config & admin
|
||||
│ ├── github/ # GitHub OAuth
|
||||
│ └── utils.ts # Helper functions
|
||||
├── marketing/ # Marketing content & components
|
||||
│ ├── components/ # Marketing-specific components
|
||||
│ └── content/ # Marketing copy
|
||||
├── public/ # Static assets
|
||||
├── firestore.rules # Firestore security rules
|
||||
├── firestore.indexes.json # Firestore indexes
|
||||
└── .env.local # Environment variables (YOU CREATE THIS)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Production Deployment
|
||||
|
||||
This project is configured for **Vercel** deployment:
|
||||
|
||||
1. Push to GitHub
|
||||
2. Connect your repo to [Vercel](https://vercel.com)
|
||||
3. Add all environment variables in Vercel dashboard
|
||||
4. Deploy automatically on push to `main`
|
||||
|
||||
Firebase Hosting is also configured but Vercel is recommended for Next.js.
|
||||
|
||||
---
|
||||
|
||||
## ✨ VS Code Tips
|
||||
|
||||
### Recommended Extensions
|
||||
|
||||
- **ESLint** - Code linting
|
||||
- **Tailwind CSS IntelliSense** - Tailwind autocomplete
|
||||
- **Prettier** - Code formatting
|
||||
- **Firebase** - Firebase syntax highlighting
|
||||
|
||||
### Settings
|
||||
|
||||
Add to `.vscode/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"tailwindCSS.experimental.classRegex": [
|
||||
["cn\\(([^)]*)\\)", "'([^']*)'"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Additional Resources
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs)
|
||||
- [Firebase Documentation](https://firebase.google.com/docs)
|
||||
- [Tailwind CSS](https://tailwindcss.com/docs)
|
||||
- [shadcn/ui](https://ui.shadcn.com/)
|
||||
- [Lucide Icons](https://lucide.dev/)
|
||||
|
||||
---
|
||||
|
||||
## 💬 Need Help?
|
||||
|
||||
- Check the [Project Instructions](../PROJECT_INSTRUCTIONS.md)
|
||||
- Review the [Firebase Admin Setup](lib/firebase/admin.ts)
|
||||
- Look at existing [API routes](app/api/) for examples
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ Ready for local development
|
||||
**Last Updated**: November 2025
|
||||
|
||||
Reference in New Issue
Block a user