🚀 InsightOS - Deployment Guide

Frontend → Vercel | Backend → Render | Database → MongoDB Atlas

📋 Prerequisites

Service	Account Required	Link
GitHub	Yes	github.com
Vercel	Yes (free)	vercel.com
Render	Yes (free)	render.com
MongoDB Atlas	Yes (free tier)	mongodb.com/atlas
Google AI Studio	For AI features	aistudio.google.com

📦 Step 1: Push Code to GitHub

# Initialize git (if not already done)
git init

# Add all files
git add .

# Commit
git commit -m "Initial commit"

# Create a repo on GitHub first, then:
git remote add origin https://github.com/yourusername/InsightOS.git
git branch -M main
git push -u origin main

🗄️ Step 2: MongoDB Atlas Setup

2.1 Create Cluster

Sign in to MongoDB Atlas
Click Create → Choose Free Shared Cluster (M0)
Select a cloud provider & region (e.g., AWS / Singapore)
Click Create Cluster (takes 1-3 minutes)

2.2 Create Database User

Go to Database Access (left sidebar)
Click Add New Database User
Set username & password (save these!)
Set privileges: Atlas Admin
Click Add User

2.3 Configure Network Access

Go to Network Access (left sidebar)
Click Add IP Address
For Render: Click Allow Access from Anywhere (0.0.0.0/0)

⚠️ Render uses dynamic IPs, so you must allow all IPs
Click Confirm

2.4 Get Connection String

Go to Databases → Click Connect on your cluster
Select Drivers

Copy the connection string:

mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/insightos?retryWrites=true&w=majority

Replace <username> and <password> with your database user credentials
You can change insightos to any database name you want

⚙️ Step 3: Backend - Deploy to Render

3.1 Create Web Service

Sign in to Render Dashboard
Click New + → Web Service
Click Connect GitHub repository
Select your InsightOS repository
Configure:

Setting	Value
Name	`insightos-api` (or your choice)
Region	Choose closest to your users (e.g., Singapore)
Branch	`main`
Root Directory	`backend`
Runtime	`Node`
Build Command	`pnpm install`
Start Command	`node src/server.js`
Plan	Free

3.2 Add Environment Variables

In the same page, scroll to Environment Variables and add:

Variable	Value	Notes
`NODE_ENV`	`production`
`PORT`	`5000`
`MONGODB_URI`	`mongodb+srv://...`	From MongoDB Atlas (Step 2.4)
`JWT_ACCESS_SECRET`	`your-random-secret-here`	Use a long random string
`JWT_REFRESH_SECRET`	`your-different-random-secret`	Different from access secret
`GROQ_API_KEY`	`gsk_your-groq-key`	Optional (for AI features)
`AI_MODEL`	`llama-4-scout`
`AI_WEB_SEARCH`	`disabled`	Enable only if paid Gemini tier
`CORS_ORIGIN`	`https://insightos.vercel.app`	Your Vercel domain (set after Step 4)

🔐 Generate secrets:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3.3 Create render.yaml (Optional but Recommended)

Create a render.yaml in your backend/ directory:

services:
  - type: web
    name: insightos-api
    env: node
    buildCommand: pnpm install
    startCommand: node src/server.js
    envVars:
      - key: NODE_ENV
        value: production
      - key: PORT
        value: 5000
      - key: MONGODB_URI
        sync: false
      - key: JWT_ACCESS_SECRET
        sync: false
      - key: JWT_REFRESH_SECRET
        sync: false
      - key: GROQ_API_KEY
        sync: false
      - key: CORS_ORIGIN
        sync: false

3.4 Deploy

Click Create Web Service
Wait 2-5 minutes for build & deploy
After success, you'll get: https://insightos-api.onrender.com
Visit https://insightos-api.onrender.com/health — you should see:
```
{ "status": "success", "message": "API is working" }
```

💡 Free Tier Notes (Render)

Service spins down after 15 minutes of inactivity (takes ~30s to wake up)
750 hours/month free (enough for 24/7 operation)
Use UptimeRobot to ping every 10 minutes to prevent sleep

🎨 Step 4: Frontend - Deploy to Vercel

4.1 Update API URL

Edit frontend/src/api/axios.config.js — it already uses:

baseURL: import.meta.env.VITE_API_URL || 'http://localhost:5000/api',

So you just need to set VITE_API_URL in Vercel.

4.2 Deploy to Vercel

Option A: Via Vercel Dashboard (Easier)

Go to Vercel Dashboard
Click Add New... → Project
Click Import Git Repository → Select your InsightOS repo
Configure:

Setting	Value
Framework Preset	`Vite`
Root Directory	`frontend`
Build Command	`vite build` (auto-detected)
Output Directory	`dist` (auto-detected)

Add Environment Variable:

Variable	Value
`VITE_API_URL`	`https://insightos-api.onrender.com/api`

Click Deploy

Option B: Via Vercel CLI

# Install Vercel CLI
npm install -g vercel

# Login
vercel login

# Deploy from frontend directory
cd frontend
vercel --prod \
  -e VITE_API_URL=https://insightos-api.onrender.com/api

4.3 Configure Custom Domain (Optional)

In Vercel dashboard → your project → Settings → Domains
Add your custom domain
Follow Vercel's DNS configuration instructions

4.4 Update CORS on Backend

After deploying frontend, update the CORS_ORIGIN environment variable on Render:

CORS_ORIGIN=https://your-frontend.vercel.app

Restart the Render service for changes to take effect.

✅ Step 5: Verify Deployment

5.1 Check Backend Health

curl https://insightos-api.onrender.com/health
# Expected: { "status": "success", "message": "API is working" }

5.2 Check Frontend

Visit your Vercel URL (e.g., https://insightos.vercel.app)
You should see the login/register page
Try creating an account

5.3 Test Authentication Flow

Register a new account
Login
Verify the dashboard loads with data

🔧 Step 6: Post-Deployment Checklist

Frontend loads without errors (check browser console)
Login/Register works
Products, Sales, Expenses CRUD works
Dashboard loads data
AI chat responds (if API key configured)
File uploads work (avatar)
Environment variables are all set
CORS is configured correctly
Database connection is stable

🛠️ Troubleshooting

❌ CORS Error (Frontend can't reach Backend)

Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy

Fix: Update CORS_ORIGIN in Render to match your exact Vercel URL.

❌ MongoDB Connection Error

MongoDB connection failed: ...

Fix:

Check MongoDB Atlas — Network Access → Ensure 0.0.0.0/0 is allowed
Verify username/password in connection string
Check if cluster is running (pause/resume if needed)

❌ 404 on API Routes

Cannot GET /api/...

Fix: Ensure the Root Directory is set to backend in Render settings.

❌ Blank Page on Vercel

Fix:

Check Root Directory is set to frontend
Verify VITE_API_URL environment variable is set
Check browser console for errors
Ensure the build output directory is dist

❌ Render App Keeps Sleeping

Free tier spins down after 15 min of inactivity.

Solution: Use UptimeRobot (free) to ping every 10 min:

Create a Monitor → HTTP(s)
URL: https://insightos-api.onrender.com/health
Interval: 10 minutes

📁 Project Structure Reference

InsightOS/
├── backend/           → Deploy on Render
│   ├── src/
│   │   ├── config/
│   │   ├── middleware/
│   │   ├── modules/
│   │   ├── routes/
│   │   └── utils/
│   ├── uploads/
│   ├── package.json
│   └── ...
│
├── frontend/          → Deploy on Vercel
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── pages/
│   │   └── ...
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   └── ...
│
└── setup.md           ← This file

💰 Cost Summary

Service	Plan	Cost
MongoDB Atlas	M0 Free	$0/month (512 MB storage)
Render	Free	$0/month (750 hrs/month)
Vercel	Free	$0/month (100 GB bandwidth)
Google Gemini	Free tier	$0/month (60 requests/min)
UptimeRobot	Free	$0/month (5 monitors)
Total		$0/month 🎉

🔗 Quick Links

Render Dashboard: https://dashboard.render.com
Vercel Dashboard: https://vercel.com/dashboard
MongoDB Atlas: https://cloud.mongodb.com
Google AI Studio: https://aistudio.google.com
UptimeRobot: https://uptimerobot.com

Need Help? Check Render Docs | Vercel Docs | MongoDB Atlas Docs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🚀 InsightOS - Deployment Guide

📋 Prerequisites

📦 Step 1: Push Code to GitHub

🗄️ Step 2: MongoDB Atlas Setup

2.1 Create Cluster

2.2 Create Database User

2.3 Configure Network Access

2.4 Get Connection String

⚙️ Step 3: Backend - Deploy to Render

3.1 Create Web Service

3.2 Add Environment Variables

3.3 Create render.yaml (Optional but Recommended)

3.4 Deploy

💡 Free Tier Notes (Render)

🎨 Step 4: Frontend - Deploy to Vercel

4.1 Update API URL

4.2 Deploy to Vercel

Option A: Via Vercel Dashboard (Easier)

Option B: Via Vercel CLI

4.3 Configure Custom Domain (Optional)

4.4 Update CORS on Backend

✅ Step 5: Verify Deployment

5.1 Check Backend Health

5.2 Check Frontend

5.3 Test Authentication Flow

🔧 Step 6: Post-Deployment Checklist

🛠️ Troubleshooting

❌ CORS Error (Frontend can't reach Backend)

❌ MongoDB Connection Error

❌ 404 on API Routes

❌ Blank Page on Vercel

❌ Render App Keeps Sleeping

📁 Project Structure Reference

💰 Cost Summary

🔗 Quick Links

FilesExpand file tree

setup.md

Latest commit

History

setup.md

File metadata and controls

🚀 InsightOS - Deployment Guide

📋 Prerequisites

📦 Step 1: Push Code to GitHub

🗄️ Step 2: MongoDB Atlas Setup

2.1 Create Cluster

2.2 Create Database User

2.3 Configure Network Access

2.4 Get Connection String

⚙️ Step 3: Backend - Deploy to Render

3.1 Create Web Service

3.2 Add Environment Variables

3.3 Create render.yaml (Optional but Recommended)

3.4 Deploy

💡 Free Tier Notes (Render)

🎨 Step 4: Frontend - Deploy to Vercel

4.1 Update API URL

4.2 Deploy to Vercel

Option A: Via Vercel Dashboard (Easier)

Option B: Via Vercel CLI

4.3 Configure Custom Domain (Optional)

4.4 Update CORS on Backend

✅ Step 5: Verify Deployment

5.1 Check Backend Health

5.2 Check Frontend

5.3 Test Authentication Flow

🔧 Step 6: Post-Deployment Checklist

🛠️ Troubleshooting

❌ CORS Error (Frontend can't reach Backend)

❌ MongoDB Connection Error

❌ 404 on API Routes

❌ Blank Page on Vercel

❌ Render App Keeps Sleeping

📁 Project Structure Reference

💰 Cost Summary

🔗 Quick Links