Configuration

Overview

SkillRise uses environment variables to configure database connections, authentication, payments, AI services, and media uploads. This guide walks you through setting up all required configuration.

Never commit .env files to version control. They contain sensitive credentials. Both server/.env and client/.env are already in .gitignore.

Backend Configuration

Create Server Environment File

Navigate to server directory

cd server

Create .env file

touch .env

Add environment variables

Open server/.env and add the following:

server/.env

# Database
MONGODB_URI=mongodb://localhost:27017

# Currency for payments (INR, USD, EUR, etc.)
CURRENCY=INR

# Clerk Authentication
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_WEBHOOK_SECRET=whsec_...

# Cloudinary Media Uploads
CLOUDINARY_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_SECRET_KEY=your_api_secret

# Razorpay Payments (for India)
RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_KEY_SECRET=your_key_secret
RAZORPAY_WEBHOOK_SECRET=whsec_...

# Groq AI (for chatbot and roadmap)
GROQ_CHATBOT_API_KEY=gsk_...

# Optional: Frontend URL (for CORS in production)
FRONTEND_URL=http://localhost:5173

# Optional: Server port
PORT=3000

Backend Environment Variables

Database Configuration

string

required

MongoDB connection string.

Local MongoDB
MongoDB Atlas

MONGODB_URI=mongodb://localhost:27017

MONGODB_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net

Replace username, password, and cluster URL with your Atlas credentials.

The database name SkillRise is automatically appended in configs/mongodb.js:7

string

default:"INR"

Three-letter ISO currency code for payments (e.g., INR, USD, EUR).Used in:

server/controllers/userController.js:123
server/services/payments/razorpay.service.js:14

Clerk Authentication

Create a Clerk application

Go to dashboard.clerk.com
Click Create Application
Choose Email and OAuth providers (Google, GitHub recommended)
Click Create Application

Get API keys

From the Clerk dashboard:

Go to API Keys in the sidebar
Copy Publishable key → CLERK_PUBLISHABLE_KEY
Copy Secret key → CLERK_SECRET_KEY

CLERK_PUBLISHABLE_KEY=pk_test_Y2xlcmsuZXhhbXBsZS5jb20k
CLERK_SECRET_KEY=sk_test_abcdefghijklmnopqrstuvwxyz123456

Configure webhook (for user sync)

SkillRise syncs Clerk users to MongoDB via webhooks.

In Clerk dashboard, go to Webhooks → Add Endpoint
Enter endpoint URL:
- Local dev (with ngrok): https://your-ngrok-url.ngrok.app/clerk
- Production: https://api.yourapp.com/clerk
Select events: user.created, user.updated, user.deleted
Click Create
Copy Signing Secret → CLERK_WEBHOOK_SECRET

CLERK_WEBHOOK_SECRET=whsec_abcdefghijklmnopqrstuvwxyz123456

Local development with ngrok

To test webhooks locally:

# Install ngrok
npm install -g ngrok

# Start your server
npm run server

# In another terminal, create tunnel to port 3000
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.app)
# Use this URL + /clerk in Clerk webhook settings

string

required

Public API key for Clerk. Starts with pk_test_ (test) or pk_live_ (production).

string

required

Secret API key for Clerk. Starts with sk_test_ or sk_live_.

Keep this secret. Never expose in client-side code.

string

required

Signing secret for verifying webhook requests from Clerk. Starts with whsec_.Used in server/controllers/webhooks.js to verify request authenticity.

Cloudinary (Media Uploads)

Create Cloudinary account

Go to cloudinary.com/users/register_free
Sign up for a free account (25 GB storage, 25 GB bandwidth/month)

Get credentials

From the Cloudinary dashboard:

Go to Dashboard (home page)
Find Account Details section
Copy:
- Cloud Name → CLOUDINARY_NAME
- API Key → CLOUDINARY_API_KEY
- API Secret → CLOUDINARY_SECRET_KEY

CLOUDINARY_NAME=dxyz123abc
CLOUDINARY_API_KEY=123456789012345
CLOUDINARY_SECRET_KEY=abcdefghijklmnopqrstuvwxyz12

string

required

Your Cloudinary cloud name (found on dashboard).

string

required

API key for Cloudinary uploads.

string

required

API secret for signing Cloudinary requests.Used in server/configs/cloudinary.js:6 to configure the Cloudinary SDK.

Razorpay (Payment Processing)

For international users: Replace Razorpay with Stripe. See Payment Integration Guide for Stripe setup.

Create Razorpay account

Go to dashboard.razorpay.com/signup
Sign up (requires Indian phone number and business details)
Complete KYC verification

Get API keys

From Razorpay dashboard:

Go to Settings → API Keys
Click Generate Test Key (for development)
Copy:
- Key ID → RAZORPAY_KEY_ID
- Key Secret → RAZORPAY_KEY_SECRET

RAZORPAY_KEY_ID=rzp_test_ABC123XYZ456
RAZORPAY_KEY_SECRET=your_key_secret_here

Use Test Mode keys for development. Switch to Live Mode for production only after completing KYC.

Configure webhook

Go to Settings → Webhooks
Click Add New Webhook
Enter webhook URL:
- Local: https://your-ngrok-url.ngrok.app/razorpay
- Production: https://api.yourapp.com/razorpay
Select events: payment.captured, payment.failed
Copy Secret → RAZORPAY_WEBHOOK_SECRET

RAZORPAY_WEBHOOK_SECRET=whsec_razorpay_secret_key

string

required

Razorpay API Key ID (starts with rzp_test_ or rzp_live_).Used in:

server/services/payments/razorpay.service.js:11
server/services/payments/razorpay.service.js:33

string

required

Razorpay API Key Secret for server-side requests.

string

required

Signing secret to verify webhook requests from Razorpay.Used in server/controllers/webhooks.js:45 to validate payment notifications.

Groq AI (Chatbot & Roadmap)

Get Groq API key

Go to console.groq.com
Sign in with Google or GitHub
Click API Keys in sidebar
Click Create API Key
Copy the key (starts with gsk_)

GROQ_CHATBOT_API_KEY=gsk_abcdefghijklmnopqrstuvwxyz1234567890

string

required

Groq API key for AI chat and roadmap generation.Used in:

server/services/chatbot/aiChatbotService.js:3 - AI chatbot
Quiz generation
Learning roadmap generation

SkillRise uses the openai/gpt-oss-120b model by default. Groq offers generous free tier limits.

Optional Variables

string

default:"http://localhost:5173"

Frontend URL for CORS configuration.

# Development
FRONTEND_URL=http://localhost:5173

# Production
FRONTEND_URL=https://skillrise.com

Used in server/server.js:29 to configure CORS policy.

Required in production. Without this, API requests from the frontend will be blocked.

number

default:"3000"

Port for the Express server.

PORT=3000

Used in server/server.js:123 to start the HTTP server.

string

default:"development"

Node environment mode.

NODE_ENV=production

development - Enables verbose logging
production - Enforces FRONTEND_URL requirement

Frontend Configuration

Create Client Environment File

Navigate to client directory

cd client

Create .env file

touch .env

Add environment variables

Open client/.env and add:

client/.env

# Clerk Authentication (public key)
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

# Backend API URL
VITE_BACKEND_URL=http://localhost:3000

# Razorpay public key (optional - only if using Razorpay checkout)
VITE_RAZORPAY_KEY_ID=rzp_test_...

Frontend Environment Variables

string

required

Clerk publishable key (same as backend CLERK_PUBLISHABLE_KEY).

VITE_CLERK_PUBLISHABLE_KEY=pk_test_Y2xlcmsuZXhhbXBsZS5jb20k

Used in:

client/src/main.jsx:6 - Initialize ClerkProvider
client/src/context/AppContext.jsx - Auth state

The VITE_ prefix is required for Vite to expose the variable to client code.

string

required

Base URL for API requests.

# Development
VITE_BACKEND_URL=http://localhost:3000

# Production
VITE_BACKEND_URL=https://api.skillrise.com

Used in:

client/src/context/AppContext.jsx:23 - Axios instance base URL
client/src/hooks/useTimeTracker.js:12 - Analytics tracking

string

Razorpay public key ID for client-side checkout (if using Razorpay).

VITE_RAZORPAY_KEY_ID=rzp_test_ABC123XYZ456

Only required if you’re implementing Razorpay embedded checkout in the frontend.

Verify Configuration

Before running the application, verify your configuration:

cd server

# Check .env file exists
ls -la .env

# Verify environment variables are loaded
node -e "require('dotenv').config(); console.log('MONGODB_URI:', process.env.MONGODB_URI ? '✓ Set' : '✗ Missing')"

cd client

# Check .env file exists
ls -la .env

# Print Vite env variables (safe - only shows VITE_ prefixed vars)
npm run dev -- --help 2>&1 | head -5

Configuration Checklist

Configuration complete! Proceed to run the application or set up Docker.

Environment Variable Reference

Complete .env template (server)

server/.env

# ─── Database ─────────────────────────────────────────────────────────────────
MONGODB_URI=mongodb://localhost:27017
CURRENCY=INR

# ─── Authentication ───────────────────────────────────────────────────────────
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_WEBHOOK_SECRET=whsec_...

# ─── Media Uploads ────────────────────────────────────────────────────────────
CLOUDINARY_NAME=your_cloud_name
CLOUDINARY_API_KEY=123456789012345
CLOUDINARY_SECRET_KEY=your_api_secret

# ─── Payments ─────────────────────────────────────────────────────────────────
RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_KEY_SECRET=your_key_secret
RAZORPAY_WEBHOOK_SECRET=whsec_...

# ─── AI Services ──────────────────────────────────────────────────────────────
GROQ_CHATBOT_API_KEY=gsk_...

# ─── Optional ─────────────────────────────────────────────────────────────────
FRONTEND_URL=http://localhost:5173
PORT=3000
NODE_ENV=development

Complete .env template (client)

client/.env

# ─── Authentication ───────────────────────────────────────────────────────────
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...

# ─── API ──────────────────────────────────────────────────────────────────────
VITE_BACKEND_URL=http://localhost:3000

# ─── Payments (optional) ──────────────────────────────────────────────────────
VITE_RAZORPAY_KEY_ID=rzp_test_...

Troubleshooting

Environment variables not loading

Symptom: undefined when accessing process.env.VARIABLE_NAMESolutions:

Verify .env file exists in the correct directory (server/ or client/)
Restart the dev server after changing .env
For Vite (client), ensure variables start with VITE_
Check for typos in variable names (they’re case-sensitive)

CORS errors when calling API

Error:

Access to XMLHttpRequest at 'http://localhost:3000/api/...' from origin 'http://localhost:5173' has been blocked by CORS policy

Solutions:

Set FRONTEND_URL=http://localhost:5173 in server/.env
Verify VITE_BACKEND_URL=http://localhost:3000 in client/.env
Restart both servers

Clerk authentication not working

Symptom: Login redirects to 404 or fails silentlySolutions:

Verify CLERK_PUBLISHABLE_KEY matches in both server/.env and client/.env (as VITE_CLERK_PUBLISHABLE_KEY)
Check Clerk dashboard → API Keys → ensure you’re using keys from the correct application
Clear browser cookies and localStorage, then try again

MongoDB connection failed

Error: MongoServerError: Authentication failedSolutions:

Verify MONGODB_URI is correct
For Atlas: ensure your IP is whitelisted in Network Access
For Atlas: verify database user credentials are correct
For local: ensure MongoDB is running (brew services list or sudo systemctl status mongod)

Cloudinary uploads failing

Error: Invalid API keySolutions:

Go to Cloudinary dashboard → verify cloud name, API key, and secret
Ensure no extra spaces in .env values
Restart the server after updating .env

Next Steps

Run Locally

Start development servers

Docker Setup

Run with Docker Compose

Seed Data

Populate with demo data

Overview

Getting Started

Core Features

For Students

For Educators

For Admins

Integrations

Deployment

Development

Overview

Backend Configuration

Create Server Environment File

Backend Environment Variables

Database Configuration

Clerk Authentication

Cloudinary (Media Uploads)

Razorpay (Payment Processing)

Groq AI (Chatbot & Roadmap)

Optional Variables

Frontend Configuration

Create Client Environment File

Frontend Environment Variables

Verify Configuration

Configuration Checklist

Environment Variable Reference

Troubleshooting

Next Steps

Run Locally

Docker Setup

Seed Data

​Overview

​Backend Configuration

​Create Server Environment File

​Backend Environment Variables

​Database Configuration

​Clerk Authentication

​Cloudinary (Media Uploads)

​Razorpay (Payment Processing)

​Groq AI (Chatbot & Roadmap)

​Optional Variables

​Frontend Configuration

​Create Client Environment File

​Frontend Environment Variables

​Verify Configuration

​Configuration Checklist

​Environment Variable Reference

​Troubleshooting

​Next Steps

Run Locally

Docker Setup

Seed Data

Overview

Backend Configuration

Create Server Environment File

Backend Environment Variables

Database Configuration

Clerk Authentication

Cloudinary (Media Uploads)

Razorpay (Payment Processing)

Groq AI (Chatbot & Roadmap)

Optional Variables

Frontend Configuration

Create Client Environment File

Frontend Environment Variables

Verify Configuration

Configuration Checklist

Environment Variable Reference

Troubleshooting

Next Steps