Installation Guide

Complete step-by-step installation instructions for the NS Internship Portal.

System Requirements

Component	Minimum Version	Notes
Node.js	18.x	Recommended: 18.17.0+
npm	9.x	Recommended: 9.6.7+
PostgreSQL	14.x	Supabase provides this
Git	2.30.x	For version control

Prerequisites

1. Supabase Setup

1. Create a new project at https://supabase.com
2. Note your project URL and API keys from Settings → API
3. Create a new database in the SQL Editor

2. Email Service Setup

Recommended: Resend (Free tier available)

1. Sign up at https://resend.com
2. Get your API key from Settings → API Keys
3. Set up a verified sender email

3. Payment Gateway Setup (Optional for testing)

Recommended: Razorpay

1. Create an account at https://razorpay.com
2. Get your test API keys from Dashboard → Settings → API Keys
3. Note: Use test mode keys during development

4. File Storage Setup (Optional for testing)

Recommended: Cloudinary

1. Create an account at https://cloudinary.com
2. Get your credentials from Dashboard → Overview
3. Configure CORS settings if using browser uploads

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/ns-software-solutions/internship-portal.git
cd internship-portal

Step 2: Install Dependencies

npm install

This will install all dependencies listed in package.json:

• Next.js 14 with App Router
• React 18
• TypeScript 5
• Supabase client
• Razorpay SDK
• Nodemailer for email
• PDFKit for PDF generation
• Jitsi Meet SDK for webinars
• Playwright for E2E testing
• And more...

Step 3: Configure Environment Variables

Create a .env file in the root directory:

# Copy the example
cp .env.example .env

# Or create manually with nano/vim
nano .env

Required variables (Application will not work without these):

# ============================================
# REQUIRED - Application will not work without these
# ============================================

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# JWT Secret (CRITICAL - Must be set for authentication)
# Generate a strong random string: openssl rand -base64 32
JWT_SECRET=your_jwt_secret_here

# ============================================
# OPTIONAL - Application will use defaults if not set
# ============================================

# GST Rate Configuration (defaults to 0.18 = 18%)
# Change this if GST rate changes in the future
GST_RATE=0.18

# Node Environment (development, production, test)
NODE_ENV=development

# Base URL for application
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Contact email for contact form
CONTACT_EMAIL=info.nssoftwaresolutions@gmail.com

# ============================================
# PAYMENT GATEWAY (Optional - for Razorpay integration)
# ============================================

RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_secret

# ============================================
# EMAIL CONFIGURATION (Optional - for transactional emails)
# ============================================

EMAIL_HOST=smtp.resend.com
EMAIL_PORT=587
EMAIL_USER=resend
EMAIL_PASS=re_your-api-key
EMAIL_FROM=onboarding@resend.dev

# ============================================
# STORAGE SERVICES (Optional)
# ============================================

# Cloudinary (for internship resource uploads and avatars)
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# ============================================
# THIRD-PARTY INTEGRATIONS (Optional)
# ============================================

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# SerpAPI (Google Jobs integration)
SERPAPI_KEY=your_serpapi_key_here

# Cron job secret (used to protect /api/cron/* endpoints)
# Generate: openssl rand -base64 32
CRON_SECRET=your_cron_secret_here

# ============================================
# MONITORING (Optional)
# ============================================

# Google Analytics 4
# Format: G-XXXXXXXXXX
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-N3JZ2D11V8

# ============================================
# NOTES
# ============================================

# 1. JWT_SECRET is CRITICAL - app will throw error if missing
# 2. SUPABASE keys are REQUIRED for database operations
# 3. Email settings are optional - invoice/notification emails won't be sent without them
# 4. Razorpay keys are optional - payment integration won't work without them
# 5. Google OAuth is optional - social login won't work without it
# 6. Never commit .env file to version control
# 7. Use strong, unique values for all secrets

Step 4: Database Setup

Option A: Using Supabase SQL Editor

1. Open Supabase SQL Editor
2. Run migrations in order:

-- 1. Core tables
supabase/schema.sql
supabase/schema_extensions.sql

-- 2. Admin activity logs
supabase/migrations/create_admin_activity_logs.sql

-- 3. Rate limiting and soft delete
supabase/migrations/rate_limit_and_soft_delete.sql

-- 4. Invoices table
supabase/migrations/create_invoices_table.sql
supabase/migrations/alter_invoices_table.sql

-- 5. Internship resources
supabase/migrations/internship_resources.sql

-- 6. Jobs cache
supabase/migrations/20240320_jobs_cache.sql

-- 7. Constraints
supabase/migrations/add_cancelled_enrollment_status.sql
supabase/migrations/add_rejected_milestone_status.sql

-- 8. Performance indexes
supabase/migrations/add_performance_indexes.sql
supabase/migrations/add_milestone_rls_policies.sql
supabase/migrations/fix_rls_recent_admin_activity_site_settings.sql

-- 9. JWT refresh tokens
supabase/migrations/create_refresh_tokens.sql

-- 10. Email tracking
supabase/migrations/create_email_logs.sql

-- 11. Enhanced announcements
supabase/migrations/extend_announcements.sql

-- 12. Last login tracking
supabase/migrations/add_last_login.sql

-- 13. Milestone optimization
supabase/migrations/optimize_milestone_queries.sql

-- 14. Email queue
supabase/migrations/create_email_queue.sql

-- 15. Additional indexes
supabase/add_indexes_migration.sql

-- 16. Certificate templates
supabase/certificate_templates.sql

-- 17. GST migration
supabase/invoice_gst_migration.sql

-- 18. Safe migration
supabase/safe_migration.sql

-- 19. Newsletter subscribers
supabase/migrations/newsletter_subscribers.sql

Option B: Using Supabase CLI

# Install CLI globally
npm install -g supabase

# Link to your project
supabase link --project-ref your-project-ref

# Run migrations
supabase db push

Step 5: Enable Row Level Security (RLS)

RLS is enabled by default in the schema. Verify with:

SELECT relname, relrowsecurity
FROM pg_class
JOIN pg_namespace ON pg_class.relnamespace = pg_namespace.oid
WHERE nspname = 'public'
AND relrowsecurity = true;

Step 6: Set Up Vercel Cron (for production)

Create or update vercel.json with cron jobs:

{
  "crons": [
    {
      "path": "/api/cron/process-emails",
      "schedule": "0 6 * * *"
    },
    {
      "path": "/api/cron/inactive-students",
      "schedule": "0 9 * * *"
    },
    {
      "path": "/api/cron/deadline-reminders",
      "schedule": "0 8 * * *"
    },
    {
      "path": "/api/cron/job-alerts",
      "schedule": "0 9 * * 1"
    }
  ]
}

Step 7: Start the Application

Development mode:

npm run dev

The app will start at http://localhost:3000

Production mode:

npm run build
npm start

Environment-Specific Configuration

Development Environment

NODE_ENV=development
NEXT_PUBLIC_BASE_URL=http://localhost:3000

Staging Environment

NODE_ENV=staging
NEXT_PUBLIC_BASE_URL=https://staging.internships.yourdomain.com

Production Environment

NODE_ENV=production
NEXT_PUBLIC_BASE_URL=https://internships.yourdomain.com

Troubleshooting

Common Issues

1. App throws "JWT_SECRET is missing"

Solution: Ensure JWT_SECRET is set in .env

2. Database connection failed

Solution: Verify Supabase URL and keys are correct

3. Email sending fails

Solution: Check Resend API key and email configuration

4. File uploads fail

Solution: Verify Cloudinary credentials are set

5. Google OAuth not working

Solution: Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set

Getting Help

• Check logs: npm run dev shows detailed error messages
• Review Troubleshooting documentation
• Contact support: info.nssoftwaresolutions@gmail.com

Next Steps

After installation:

1. Configuration - Fine-tune your setup
2. Testing - Verify everything works
3. Deployment - Go live