Environment Variables

VIJ Admin is configured entirely through environment variables. This page documents all available variables, their purposes, and recommended values.

Required Variables

These variables must be set for VIJ Admin to function.

MONGODB_URI

string

required

MongoDB connection string for storing error logs.Format: mongodb://[username:password@]host[:port]/database[?options]Examples:

MONGODB_URI=mongodb://localhost:27017/vij

Connection Options:

retryWrites=true - Automatically retry write operations
w=majority - Write concern for data durability
authSource=admin - Database for authentication
ssl=true - Enable SSL/TLS encryption
maxPoolSize=50 - Maximum connection pool size
minPoolSize=10 - Minimum connection pool size

Never commit this value to version control. Use .env.local (git-ignored) or environment-specific configuration.

NEXT_PUBLIC_BASE_URL

string

required

The public URL where your VIJ Admin dashboard is accessible.Usage: Used for API endpoints, redirects, and client-side routing.Format: Complete URL with protocol (http/https) and domain/port.Examples:

NEXT_PUBLIC_BASE_URL=http://localhost:3000

The NEXT_PUBLIC_ prefix makes this variable available in both server and client code.

Update this variable when:

Changing domains
Moving from development to production
Changing ports
Adding/removing SSL

Optional Variables

These variables enable additional features or customize behavior.

GEMINI_API_KEY

string

Google Gemini API key for AI-powered error analysis.Get a key: Visit ai.google.dev to create an API key.Example:

GEMINI_API_KEY=AIzaSyC1234567890abcdefghijklmnopqrstuv

Features Enabled:

AI error summaries
Root cause analysis
Suggested fixes
Pattern detection

Without this key:

VIJ works normally
AI features are disabled
No error messages shown

Google Gemini offers a generous free tier. Most VIJ installations stay within free limits.

NODE_ENV

string

default:"development"

Node.js environment mode.Values:

development - Development mode with debugging enabled
production - Production mode with optimizations
test - Test mode (used for automated testing)

Examples:

Development

NODE_ENV=development

Production

NODE_ENV=production

Effects:

Feature	Development	Production
Error details	Full stack traces	Sanitized errors
Logging	Verbose	Minimal
Optimizations	Disabled	Enabled
Source maps	Enabled	Disabled
Cache	Disabled	Enabled

Always use NODE_ENV=production for production deployments to enable performance optimizations and security features.

PORT

number

default:"3000"

Port number for the Next.js server.Examples:

Default

PORT=3000

Custom Port

PORT=8080

Production (Behind Proxy)

PORT=3000

When using a reverse proxy (Nginx, Apache), you typically keep this at 3000 and configure the proxy to forward requests.

MONGODB_OPTIONS

string

Additional MongoDB connection options as JSON.Example:

MONGODB_OPTIONS='{"maxPoolSize":100,"minPoolSize":10,"serverSelectionTimeoutMS":5000}'

Common Options:

{
  "maxPoolSize": 100,
  "minPoolSize": 10,
  "maxIdleTimeMS": 300000,
  "serverSelectionTimeoutMS": 5000,
  "socketTimeoutMS": 45000,
  "family": 4,
  "retryWrites": true,
  "retryReads": true,
  "compressors": ["snappy", "zlib"]
}

Most applications don’t need custom options. The defaults are optimized for typical usage.

LOG_RETENTION_DAYS

number

default:"90"

Number of days to retain logs before automatic deletion.Examples:

30 Days

LOG_RETENTION_DAYS=30

1 Year

LOG_RETENTION_DAYS=365

Disabled (Keep Forever)

LOG_RETENTION_DAYS=0

Behavior:

Logs older than this value are deleted automatically
Deletion runs daily at midnight UTC
Set to 0 to disable automatic deletion

Longer retention periods increase database size. Monitor storage usage and implement appropriate retention policies.

ENABLE_TELEMETRY

boolean

default:"false"

Enable anonymous usage telemetry for VIJ development.Values: true or falseExamples:

Enabled

ENABLE_TELEMETRY=true

Disabled

ENABLE_TELEMETRY=false

Data Collected (if enabled):

Installation count
Feature usage (anonymized)
Error rates (aggregate only)
No PII or error content

Telemetry helps improve VIJ. All data is anonymous and aggregated. You can disable it anytime.

Environment-Specific Configuration

Development (.env.local)

.env.local

# Database
MONGODB_URI=mongodb://localhost:27017/vij

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

# Features
GEMINI_API_KEY=your_development_key

# Debug
DEBUG=true
LOG_LEVEL=debug

Production (.env.production)

.env.production

# Database (MongoDB Atlas)
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/vij?retryWrites=true&w=majority

# Application
NEXT_PUBLIC_BASE_URL=https://vij.yourdomain.com
NODE_ENV=production
PORT=3000

# Features
GEMINI_API_KEY=your_production_key

# Retention
LOG_RETENTION_DAYS=90

# Telemetry
ENABLE_TELEMETRY=true

Staging (.env.staging)

.env.staging

# Database
MONGODB_URI=mongodb+srv://user:pass@staging-cluster.mongodb.net/vij-staging

# Application
NEXT_PUBLIC_BASE_URL=https://vij-staging.yourdomain.com
NODE_ENV=production

# Features
GEMINI_API_KEY=your_staging_key

# Retention (shorter for staging)
LOG_RETENTION_DAYS=30

Platform-Specific Configuration

Vercel

Set environment variables in the Vercel dashboard:

Go to Project Settings → Environment Variables
Add variables for each environment (Production, Preview, Development)
Deploy

Required for Vercel:

MONGODB_URI=your_atlas_connection_string
NEXT_PUBLIC_BASE_URL=https://your-project.vercel.app

Vercel automatically sets NODE_ENV=production for production deployments.

Docker

Pass environment variables via Docker run command:

docker run -d \
  -p 3000:3000 \
  -e MONGODB_URI="mongodb://mongo:27017/vij" \
  -e NEXT_PUBLIC_BASE_URL="http://localhost:3000" \
  -e GEMINI_API_KEY="your_key" \
  vij-admin:latest

Or use environment file:

docker run -d \
  -p 3000:3000 \
  --env-file .env.production \
  vij-admin:latest

Docker Compose

docker-compose.yml

services:
  vij-admin:
    image: vij-admin:latest
    ports:
      - "3000:3000"
    environment:
      MONGODB_URI: mongodb://mongo:27017/vij
      NEXT_PUBLIC_BASE_URL: http://localhost:3000
      GEMINI_API_KEY: ${GEMINI_API_KEY}
    # Or use env_file
    env_file:
      - .env.production

Kubernetes

Use Kubernetes secrets:

apiVersion: v1
kind: Secret
metadata:
  name: vij-secrets
type: Opaque
stringData:
  mongodb-uri: "mongodb+srv://..."
  gemini-api-key: "your_key"
  next-public-base-url: "https://vij.yourdomain.com"

Reference in deployment:

env:
  - name: MONGODB_URI
    valueFrom:
      secretKeyRef:
        name: vij-secrets
        key: mongodb-uri
  - name: NEXT_PUBLIC_BASE_URL
    valueFrom:
      secretKeyRef:
        name: vij-secrets
        key: next-public-base-url

Loading Environment Variables

Next.js Built-in Support

Next.js automatically loads:

.env.local - All environments (git-ignored)
.env.production - Production builds
.env.development - Development builds
.env - All environments (committed to git)

Priority (highest to lowest):

process.env (system environment)
.env.$(NODE_ENV).local
.env.local (not loaded when NODE_ENV=test)
.env.$(NODE_ENV)
.env

Never commit .env.local files. Use .env.example as a template.

Manual Loading (Node.js)

For scripts or custom tooling:

import dotenv from 'dotenv';

// Load .env.local
dotenv.config({ path: '.env.local' });

// Load environment-specific
dotenv.config({ path: `.env.${process.env.NODE_ENV}` });

console.log(process.env.MONGODB_URI);

Environment File Template

Create .env.example for documentation:

.env.example

# VIJ Admin Environment Configuration Template
# Copy this file to .env.local and fill in your values

# ===================================
# Required Configuration
# ===================================

# MongoDB connection string
MONGODB_URI=mongodb://localhost:27017/vij

# Application base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# ===================================
# Optional Configuration
# ===================================

# Google Gemini API key for AI features (optional)
# Get your key at: https://ai.google.dev
GEMINI_API_KEY=

# Node.js environment (development|production|test)
NODE_ENV=development

# Server port
PORT=3000

# Log retention in days (0 = keep forever)
LOG_RETENTION_DAYS=90

# Enable anonymous telemetry
ENABLE_TELEMETRY=false

Security Best Practices

Never commit secrets

Add to .gitignore:

.gitignore

# Environment files
.env.local
.env.*.local
.env.production.local

# Keep template
!.env.example

Use different keys per environment

# Development
GEMINI_API_KEY=dev_key_with_low_quota

# Production
GEMINI_API_KEY=prod_key_with_high_quota

Prevents accidental quota exhaustion and isolates environments.

Rotate secrets regularly

MongoDB passwords: Every 90 days
API keys: Every 180 days
Update in all environments
Document rotation in runbook

Use secret management services

For production:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

// Example: AWS Secrets Manager
import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManager({ region: 'us-east-1' });
const secret = await client.getSecretValue({ SecretId: 'vij/mongodb' });
const MONGODB_URI = JSON.parse(secret.SecretString).uri;

Validate environment variables on startup

lib/config.ts

const requiredEnvVars = [
  'MONGODB_URI',
  'NEXT_PUBLIC_BASE_URL'
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

export const config = {
  mongodb: {
    uri: process.env.MONGODB_URI!
  },
  baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
  geminiApiKey: process.env.GEMINI_API_KEY
};

Troubleshooting

Environment variables not loading

Issue: Variables are undefined at runtimeSolutions:

Check file name is exactly .env.local (not .env.txt or .env)
Restart dev server after changes
Ensure no typos in variable names
Check .env.local is in project root
For client-side variables, use NEXT_PUBLIC_ prefix

NEXT_PUBLIC_ variables not available in client

Issue: Client code cannot access environment variablesSolution: Use NEXT_PUBLIC_ prefix

// Server-side only
const key = process.env.GEMINI_API_KEY;

// Client and server
const url = process.env.NEXT_PUBLIC_BASE_URL;

MongoDB connection string format errors

Issue: Invalid connection string formatCommon mistakes:

# Wrong - missing mongodb://
MONGODB_URI=localhost:27017/vij

# Wrong - spaces in URL
MONGODB_URI=mongodb://user : pass@host/db

# Wrong - unencoded password
MONGODB_URI=mongodb://user:p@ssw0rd!@host/db

# Correct - URL-encoded password
MONGODB_URI=mongodb://user:p%40ssw0rd%21@host/db

URL-encode special characters in passwords:

@ → %40
: → %3A
/ → %2F
? → %3F
# → %23

Vercel environment variables not updating

Issue: Changes to environment variables not reflectedSolution:

Update variables in Vercel dashboard
Trigger a new deployment (redeploy or push commit)
Environment variables are set at build time, not runtime

Next Steps

Dashboard Setup

Complete setup guide for VIJ Admin

Deployment Guide

Deploy VIJ Admin to production

SDK Configuration

Configure the vij-sdk client

Quickstart

Get started with VIJ in minutes

Getting started

SDK

Dashboard

Advanced

Environment Variables

Required Variables

MONGODB_URI

NEXT_PUBLIC_BASE_URL

Optional Variables

GEMINI_API_KEY

NODE_ENV

PORT

MONGODB_OPTIONS

LOG_RETENTION_DAYS

ENABLE_TELEMETRY

Environment-Specific Configuration

Development (.env.local)

Production (.env.production)

Staging (.env.staging)

Platform-Specific Configuration

Vercel

Docker

Docker Compose

Kubernetes

Loading Environment Variables

Next.js Built-in Support

Manual Loading (Node.js)

Environment File Template

Security Best Practices

Troubleshooting

Next Steps

Dashboard Setup

Deployment Guide

SDK Configuration

Quickstart

Getting started

SDK

Dashboard

Advanced

​Required Variables

​MONGODB_URI

​NEXT_PUBLIC_BASE_URL

​Optional Variables

​GEMINI_API_KEY

​NODE_ENV

​PORT

​MONGODB_OPTIONS

​LOG_RETENTION_DAYS

​ENABLE_TELEMETRY

​Environment-Specific Configuration

​Development (.env.local)

​Production (.env.production)

​Staging (.env.staging)

​Platform-Specific Configuration

​Vercel

​Docker

​Docker Compose

​Kubernetes

​Loading Environment Variables

​Next.js Built-in Support

​Manual Loading (Node.js)

​Environment File Template

​Security Best Practices

​Troubleshooting

​Next Steps

Dashboard Setup

Deployment Guide

SDK Configuration

Quickstart

Required Variables

MONGODB_URI

NEXT_PUBLIC_BASE_URL

Optional Variables

GEMINI_API_KEY

NODE_ENV

PORT

MONGODB_OPTIONS

LOG_RETENTION_DAYS

ENABLE_TELEMETRY

Environment-Specific Configuration

Development (.env.local)

Production (.env.production)

Staging (.env.staging)

Platform-Specific Configuration

Vercel

Docker

Docker Compose

Kubernetes

Loading Environment Variables

Next.js Built-in Support

Manual Loading (Node.js)

Environment File Template

Security Best Practices

Troubleshooting

Next Steps