Dashboard Setup

The VIJ Admin dashboard is a Next.js application that provides error monitoring, visualization, and AI-powered analysis. This guide walks you through setting up your own self-hosted instance.

Prerequisites

Before setting up VIJ Admin, ensure you have:

Required Software

Node.js 18+ - Required for running Next.js
npm, yarn, pnpm, or bun - Package manager
MongoDB 5.0+ - Database for storing error logs
Git - For cloning the repository

MongoDB Setup

You need a MongoDB instance. Choose one of:Option 1: MongoDB Atlas (Cloud)

Create free account at mongodb.com/atlas
Create a cluster
Get connection string

Option 2: Local MongoDB

# macOS
brew install mongodb-community
brew services start mongodb-community

# Linux
sudo apt-get install mongodb
sudo systemctl start mongodb

# Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

Optional: Google Gemini API Key

For AI-powered error analysis:

Visit ai.google.dev
Create an API key
Keep it for environment configuration

AI features are optional. VIJ works perfectly without them.

Installation

Clone the repository

Clone the VIJ Admin repository:

git clone https://github.com/asengupta07/vij-admin.git
cd vij-admin

Alternatively, fork the repository first if you plan to make customizations.

Install dependencies

Install all required npm packages:

npm install

This will install:

Next.js 14+ framework
MongoDB driver
Google Generative AI SDK
UI components and utilities

Configure environment variables

Create a .env.local file in the project root:

touch .env.local

Add the following configuration:

.env.local

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

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

# Optional: Google Gemini API key for AI features
GEMINI_API_KEY=your_api_key_here

MONGODB_URI is required. The application will not start without it.

See the Environment Variables reference for all available options.

Start the development server

Run the Next.js development server:

npm run dev

The dashboard will be available at http://localhost:3000

You should see the VIJ Admin dashboard! The home page will be empty until you start sending logs from your applications.

Verify database connection

Check the terminal output for MongoDB connection status:

✓ Ready in 2.3s
✓ MongoDB connected successfully

If you see connection errors, verify:

MongoDB is running
Connection string is correct
Network/firewall allows connection

Configuration

Environment Variables

Configure VIJ Admin through environment variables:

MONGODB_URI

string

required

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

# Local MongoDB
MONGODB_URI=mongodb://localhost:27017/vij

# MongoDB Atlas
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/vij

# With authentication
MONGODB_URI=mongodb://admin:password@localhost:27017/vij?authSource=admin

# Replica set
MONGODB_URI=mongodb://host1:27017,host2:27017,host3:27017/vij?replicaSet=rs0

NEXT_PUBLIC_BASE_URL

string

required

Base URL where your VIJ Admin dashboard is accessible.Usage: Used for API endpoints and client-side routing.Examples:

# Development
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Production
NEXT_PUBLIC_BASE_URL=https://vij.yourdomain.com

# Custom port
NEXT_PUBLIC_BASE_URL=http://localhost:8080

GEMINI_API_KEY

string

Google Gemini API key for AI-powered error analysis.Get a key: ai.google.devExample:

GEMINI_API_KEY=AIzaSyC1234567890abcdefghijklmnopqrstuv

Without this key, AI features will be disabled but all other functionality works normally.

MongoDB Configuration

VIJ Admin automatically creates the following indexes for optimal performance:

// Composite index for efficient filtering
{ appId: 1, environment: 1, timestamp: -1 }

// Text index for full-text search
{ message: "text", stack: "text" }

// Grouping index
{ group: 1, timestamp: -1 }

Indexes are created automatically on first connection. No manual setup required.

Database Schema

Error logs are stored in the logs collection with this structure:

{
  _id: ObjectId,
  message: string,
  name: string,
  stack: string,
  severity: "error" | "warning" | "info",
  timestamp: Date,
  appId: string,
  environment: string,
  metadata: object,
  context: object,
  group: string, // Auto-generated fingerprint
  aiAnalysis?: {
    summary: string,
    possibleCause: string,
    suggestedFix: string
  }
}

Next.js Configuration

The VIJ Admin uses these Next.js settings:

App Router Structure

app/
├── page.tsx              # Dashboard home
├── logs/
│   ├── page.tsx         # Logs listing
│   └── [id]/
│       └── page.tsx     # Error details
├── groups/
│   └── page.tsx         # Error groups
├── api/
│   ├── logs/
│   │   └── route.ts     # POST /api/logs, GET /api/logs
│   ├── stats/
│   │   └── route.ts     # GET /api/stats
│   └── groups/
│       └── route.ts     # GET /api/groups
└── layout.tsx           # Root layout

API Routes

All API routes are automatically available:

POST /api/logs - Receive error logs from SDK
GET /api/logs - Fetch logs with filtering
GET /api/stats - Get dashboard statistics
GET /api/groups - Get grouped errors

These routes are documented in detail in the API Reference.

Initial Setup Checklist

After installation, verify your setup:

Check dashboard access

Open http://localhost:3000 in your browser.You should see:

Dashboard home page
Navigation menu (Dashboard, Logs, Groups)
Empty state (no errors yet)

Verify API endpoints

Test the API is responding:

# Check health
curl http://localhost:3000/api/logs

# Should return: {"error":"Method not allowed"}

Getting a method error is good! It means the API is running.

Test log ingestion

Send a test log:

curl -X POST http://localhost:3000/api/logs \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Test error",
    "name": "Error",
    "stack": "Error: Test error\n    at test.js:1:1",
    "severity": "error",
    "timestamp": "2024-01-01T00:00:00.000Z",
    "appId": "test-app",
    "environment": "development",
    "metadata": {},
    "context": {}
  }'

Then check the dashboard - you should see your test error!

Verify database

Check MongoDB has the data:

# MongoDB shell
mongosh vij

# List collections
show collections

# Count logs
db.logs.countDocuments()

# View a log
db.logs.findOne()

Test AI features (if configured)

If you set GEMINI_API_KEY, click on a log entry and verify you see:

AI Summary
Possible Cause
Suggested Fix

AI analysis may take a few seconds on first load.

Project Structure

Understanding the VIJ Admin codebase:

vij-admin/
├── app/                  # Next.js App Router
│   ├── api/             # API routes
│   ├── logs/            # Logs pages
│   ├── groups/          # Groups pages
│   └── page.tsx         # Dashboard home
├── components/          # React components
│   ├── ui/             # shadcn/ui components
│   ├── Dashboard.tsx   # Dashboard component
│   ├── LogsView.tsx    # Logs table
│   └── ErrorDetails.tsx # Error detail view
├── lib/                # Utilities
│   ├── mongodb.ts      # Database connection
│   ├── gemini.ts       # AI integration
│   └── utils.ts        # Helper functions
├── public/             # Static assets
├── .env.local          # Environment config
└── package.json        # Dependencies

Customization

Theming

VIJ Admin uses Tailwind CSS. Customize colors in tailwind.config.js:

tailwind.config.js

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "#3b82f6", // Your brand color
          dark: "#2563eb"
        }
      }
    }
  }
}

Adding Custom Filters

Extend filtering in app/logs/page.tsx:

// Add custom filter option
const customFilters = [
  { label: "My App Only", value: "appId:my-app" },
  { label: "Critical Errors", value: "severity:error" }
];

Custom Metadata Fields

Display custom metadata in components/ErrorDetails.tsx:

// Add custom metadata rendering
{metadata.userId && (
  <div>
    <strong>User ID:</strong> {metadata.userId}
  </div>
)}

Troubleshooting

MongoDB connection failed

Error: MongoServerError: connect ECONNREFUSEDSolutions:

Verify MongoDB is running:

# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongodb

# Docker
docker ps | grep mongo

Check connection string in .env.local
Verify firewall/network settings
For Atlas: Check IP whitelist

Module not found errors

Error: Module not found: Can't resolve 'X'Solutions:

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Next.js cache
rm -rf .next
npm run dev

Environment variables not loading

Issue: Environment variables undefinedSolutions:

Ensure file is named .env.local (not .env)
Restart dev server after changes
Use NEXT_PUBLIC_ prefix for client-side variables
Check for typos in variable names

AI features not working

Issue: No AI analysis appearingSolutions:

Verify GEMINI_API_KEY is set
Check API key is valid on ai.google.dev
Check browser console for errors
Verify you have API quota available
Check server logs for AI-related errors

Port already in use

Error: Port 3000 is already in useSolutions:

# Use different port
PORT=3001 npm run dev

# Or kill process using port 3000
lsof -ti:3000 | xargs kill

Next Steps

Dashboard Features

Explore all dashboard capabilities and features

Environment Variables

Complete environment variable reference

Deploy to Production

Deploy VIJ Admin to Vercel or your infrastructure

Integrate SDK

Add error tracking to your applications

Getting started

SDK

Dashboard

Advanced

Dashboard Setup

Prerequisites

Installation

Configuration

Environment Variables

MongoDB Configuration

Database Schema

Next.js Configuration

App Router Structure

API Routes

Initial Setup Checklist

Project Structure

Customization

Theming

Adding Custom Filters

Custom Metadata Fields

Troubleshooting

Next Steps

Dashboard Features

Environment Variables

Deploy to Production

Integrate SDK

Getting started

SDK

Dashboard

Advanced

​Prerequisites

​Installation

​Configuration

​Environment Variables

​MongoDB Configuration

​Database Schema

​Next.js Configuration

​App Router Structure

​API Routes

​Initial Setup Checklist

​Project Structure

​Customization

​Theming

​Adding Custom Filters

​Custom Metadata Fields

​Troubleshooting

​Next Steps

Dashboard Features

Environment Variables

Deploy to Production

Integrate SDK

Prerequisites

Installation

Configuration

Environment Variables

MongoDB Configuration

Database Schema

Next.js Configuration

App Router Structure

API Routes

Initial Setup Checklist

Project Structure

Customization

Theming

Adding Custom Filters

Custom Metadata Fields

Troubleshooting

Next Steps