Installation Guide

Installation Overview

VulnTrack is a Next.js 14 application with a PostgreSQL database. This guide covers local development setup and deployment considerations.

Prerequisites: Node.js 20+, PostgreSQL 14+, and a terminal with git installed.

Quick Install

Clone the Repository

Get the latest version from GitHub:

git clone https://github.com/ogdmerlin/vulntrack.git
cd vulntrack

The repository structure:

vulntrack/
├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   └── lib/              # Utilities and configuration
├── prisma/
│   └── schema.prisma     # Database schema
├── public/               # Static assets
└── package.json          # Dependencies

Install Dependencies

VulnTrack uses npm as the package manager:

npm install

This installs the core dependencies from package.json:Framework:

[email protected] - Next.js framework
[email protected] - React library
typescript@5 - TypeScript support

Database:

@prisma/[email protected] - Prisma ORM
[email protected] - Prisma CLI (dev dependency)

Authentication:

[email protected] - NextAuth.js
@next-auth/[email protected] - Prisma adapter
[email protected] - Password hashing

UI Libraries:

@radix-ui/react-* - Headless UI components
[email protected] - Utility-first CSS
[email protected] - Icon library

Additional Features:

[email protected] - Schema validation
[email protected] - Form handling
[email protected] - PDF generation
[email protected] - Markdown rendering

The postinstall script in package.json automatically runs prisma generate after installation.

Configure Environment Variables

Create a .env file in the project root:

touch .env

Add the following configuration:

.env

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/vulntrack"

# NextAuth Configuration
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key-here"  # Generate with: openssl rand -base64 32

# Optional: VulnCheck API (for enhanced CVE data)
VULNCHECK_API_KEY="your-vulncheck-api-key"

# Optional: Email Configuration (for notifications)
RESEND_API_KEY="your-resend-api-key"
FROM_EMAIL="[email protected]"

# Optional: Application URL (for email links)
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Environment Variable Details

DATABASE_URL (Required)

PostgreSQL connection string format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Local Development:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/vulntrack"

Production (example with SSL):

DATABASE_URL="postgresql://user:[email protected]:5432/vulntrack?sslmode=require"

Never commit .env files to version control. Add .env to your .gitignore.

NEXTAUTH_SECRET (Required)

Used to encrypt session tokens. Generate a secure random string:

openssl rand -base64 32

Example output:

J8fHk2L9mN3pQ5rT7vX0yZ4aB6cE8gI1jK3mO5qS7uW=

Use this value as your NEXTAUTH_SECRET.

VULNCHECK_API_KEY (Optional)

Enables enhanced CVE data fetching from VulnCheck.Benefits:

Faster CVE lookups
Real-time KEV (Known Exploited Vulnerabilities) detection
More comprehensive metadata

Get an API key:

Sign up at vulncheck.com
Navigate to API Keys section
Generate a new key
Add to .env: VULNCHECK_API_KEY="vc_xxxxx"

Fallback: If not configured, VulnTrack uses the free NIST NVD API (from src/app/actions/cve.ts).

// CVE import logic with fallback
const vulnCheckResult = await fetchVulnCheckData(cveId)
if (vulnCheckResult) {
  source = "VulnCheck"
  cveData = vulnCheckResult
} else {
  // Fallback to NIST
  const nistResult = await fetchNistData(cveId)
  cveData = nistResult
}

RESEND_API_KEY (Optional)

Enables email notifications for vulnerability assignments.Setup:

Create account at resend.com
Add and verify your domain
Generate API key

Configure:

RESEND_API_KEY="re_xxxxx"
FROM_EMAIL="[email protected]"

Email Triggers (from src/app/actions/vulnerabilities.ts):

Vulnerability assignment
Status changes (if configured)
Team invitations

Without this configuration, the app works but email notifications are disabled.

Set Up PostgreSQL Database

VulnTrack requires PostgreSQL 14 or higher.

Option 1: Local PostgreSQL Installation

brew install postgresql@14
brew services start postgresql@14
createdb vulntrack

Option 2: Docker Container

Run PostgreSQL in Docker for isolated development:

docker run --name vulntrack-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=vulntrack \
  -p 5432:5432 \
  -d postgres:14

Verify connection:

docker exec -it vulntrack-db psql -U postgres -d vulntrack

Option 3: Cloud Database

Use a managed PostgreSQL service:Providers:

Supabase - Free tier with 500MB
Neon - Serverless Postgres
Railway - $5/month starter
Render - Free tier available

After provisioning, update DATABASE_URL in .env with the connection string.

Initialize the Database Schema

VulnTrack uses Prisma for database management. The schema is defined in prisma/schema.prisma.

Generate Prisma Client

npx prisma generate

This creates the TypeScript types and Prisma Client based on your schema.

Push Schema to Database

npx prisma db push

This command:

Creates all tables defined in schema.prisma
Sets up relationships and constraints
Enables full-text search indexes

Tables created:

- Team              # Multi-tenant workspaces
- User              # Authentication and profiles
- Vulnerability     # Core vulnerability records
- DreadScore        # DREAD risk scores (1:1 with Vulnerability)
- StrideScore       # STRIDE classifications (1:1 with Vulnerability)
- Comment           # Collaboration comments
- Invitation        # User invitation tokens
- Notification      # In-app notifications
- AuditLog          # Compliance and activity tracking

Key Schema Features

From prisma/schema.prisma:

model Vulnerability {
  id          String   @id @default(uuid())
  title       String
  description String
  status      String   # OPEN | IN_PROGRESS | REMEDIATED | ACCEPTED | RESOLVED
  severity    String   # CRITICAL | HIGH | MEDIUM | LOW | INFO
  
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  
  teamId      String?
  team        Team?    @relation(fields: [teamId], references: [id])
  
  assignedToId String?
  assignedTo   User?    @relation("AssignedVulnerabilities", fields: [assignedToId], references: [id])
  
  approvalStatus String @default("APPROVED") # PENDING | APPROVED | REJECTED
  
  dread       DreadScore?
  stride      StrideScore?
  comments    Comment[]
  
  # CVE Import Fields
  cveId             String?
  cvssScore         Float?
  affectedSystems   String?  # JSON serialized array
  mitigations       String?  # JSON serialized array
  references        String?  # JSON serialized array
  
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

prisma db push is for development. For production, use migrations:

npx prisma migrate deploy

Verify Database Schema

Open Prisma Studio to inspect your database:

npx prisma studio

This opens a web interface at http://localhost:5555 where you can:

View all tables
Browse records
Edit data manually (useful for testing)

Seed Initial Data (Optional)

Optionally seed the database with sample data for testing.Check if a seed script exists:

ls prisma/seed.ts  # or seed.js

If available, run:

npx prisma db seed

This typically creates:

Sample admin user
Demo team
Example vulnerabilities
Test DREAD/STRIDE scores

The first registered user is automatically made an Admin, so seeding is optional for getting started.

Start the Development Server

Launch VulnTrack locally:

npm run dev

The application starts on http://localhost:3000.What happens on startup:

Next.js compiles React components
Prisma Client connects to PostgreSQL
NextAuth.js initializes session management
API routes become available at /api/*

Verify Installation

You should see:

▲ Next.js 14.2.33
- Local:        http://localhost:3000
- Environments: .env

✓ Ready in 2.3s

Navigate to http://localhost:3000 to see the landing page.

Common Startup Issues

Database Connection Error

Error: P1001 Can't reach database server

Solutions:

Verify PostgreSQL is running: pg_isready
Check DATABASE_URL format in .env
Test connection: psql $DATABASE_URL
Ensure database exists: createdb vulntrack

Prisma Client Not Generated

Error: @prisma/client did not initialize yet

Solution:

npx prisma generate
npm run dev

Port Already in Use

Error: Port 3000 is already in use

Solution:

# Use a different port
PORT=3001 npm run dev

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

Production Deployment

VulnTrack can be deployed to any platform supporting Next.js 14.

Build for Production

npm run build

From package.json, this runs:

"build": "npx prisma generate && npx prisma db push --accept-data-loss && next build"

--accept-data-loss flag is for CI/CD. For production databases, use migrations:

npx prisma migrate deploy

Start Production Server

npm run start

This serves the optimized build on the configured port.

Deployment Platforms

Vercel

Best for: Quick deployments

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Configure environment variables in Vercel dashboard.

Docker

Best for: Self-hosted environments

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npx prisma generate
RUN npm run build
CMD ["npm", "start"]

Railway

Best for: Full-stack deployments

Connect GitHub repo
Railway auto-provisions PostgreSQL
Configure environment variables
Deploy with one click

DigitalOcean App Platform

Best for: Scalable deployments

Create new app from GitHub
Attach managed PostgreSQL
Set environment variables
Configure build command: npm run build

Production Checklist

Development Tools

Useful Commands

# Open Prisma Studio
npx prisma studio

# Create migration
npx prisma migrate dev --name add_new_field

# Reset database (caution: deletes data)
npx prisma migrate reset

# View database schema
npx prisma db pull

VS Code Extensions

Recommended extensions for VulnTrack development:

Prisma - Syntax highlighting for .prisma files
ES7+ React/Redux - React snippets
Tailwind CSS IntelliSense - Autocomplete for Tailwind classes
TypeScript Error Translator - Readable TypeScript errors

Updating VulnTrack

To update to the latest version:

# Pull latest changes
git pull origin main

# Install new dependencies
npm install

# Update database schema
npx prisma generate
npx prisma db push  # or migrate deploy in production

# Rebuild application
npm run build

# Restart server
npm start

Always backup your database before updating, especially in production:

pg_dump -U postgres vulntrack > backup-$(date +%Y%m%d).sql

Next Steps

Quickstart Guide

Create your first vulnerability and explore features

Architecture

Understand VulnTrack’s technical design

Troubleshooting

Session Not Persisting

Symptom: Logged out immediately after loginCauses:

Missing or invalid NEXTAUTH_SECRET
Incorrect NEXTAUTH_URL
Cookie issues (check browser console)

Solution:

.env

NEXTAUTH_SECRET="$(openssl rand -base64 32)"
NEXTAUTH_URL="http://localhost:3000"  # Must match browser URL exactly

CVE Import Not Working

Symptom: “CVE not found” errorsDiagnosis: Check the server logs for API errors:

# Look for VulnCheck or NIST errors
npm run dev 2>&1 | grep -i "CVE\|API"

Solutions:

Verify VULNCHECK_API_KEY if configured
Check NIST API rate limits (if no VulnCheck)
Test CVE ID format: CVE-YYYY-NNNNN

Permission Errors

Symptom: “Unauthorized” when accessing featuresCheck user role:

-- Open Prisma Studio or psql
SELECT email, role FROM "User";

Update role if needed:

UPDATE "User" SET role = 'ADMIN' WHERE email = '[email protected]';

Need Help?

Join the community or report issues on GitHub

Get Started

Core Features

Scoring Frameworks

User Guides

Configuration

Deployment

Installation Guide

Installation Overview

Quick Install

Environment Variable Details

Option 1: Local PostgreSQL Installation

Option 2: Docker Container

Option 3: Cloud Database

Generate Prisma Client

Push Schema to Database

Key Schema Features

Verify Database Schema

Verify Installation

Common Startup Issues

Production Deployment

Build for Production

Start Production Server

Deployment Platforms

Vercel

Docker

Railway

DigitalOcean App Platform

Production Checklist

Development Tools

Useful Commands

VS Code Extensions

Updating VulnTrack

Next Steps

Quickstart Guide

Architecture

Troubleshooting

Need Help?

Build docs developers (and LLMs) love

Get Started

Core Features

Scoring Frameworks

User Guides

Configuration

Deployment

​Installation Overview

​Quick Install

​Environment Variable Details

​Option 1: Local PostgreSQL Installation

​Option 2: Docker Container

​Option 3: Cloud Database

​Generate Prisma Client

​Push Schema to Database

​Key Schema Features

​Verify Database Schema

​Verify Installation

​Common Startup Issues

​Production Deployment

​Build for Production

​Start Production Server

​Deployment Platforms

Vercel

Docker

Railway

DigitalOcean App Platform

​Production Checklist

​Development Tools

​Useful Commands

​VS Code Extensions

​Updating VulnTrack

​Next Steps

Quickstart Guide

Architecture

​Troubleshooting

Need Help?

Build docs developers (and LLMs) love

Installation Overview

Quick Install

Environment Variable Details

Option 1: Local PostgreSQL Installation

Option 2: Docker Container

Option 3: Cloud Database

Generate Prisma Client

Push Schema to Database

Key Schema Features

Verify Database Schema

Verify Installation

Common Startup Issues

Production Deployment

Build for Production

Start Production Server

Deployment Platforms

Production Checklist

Development Tools

Useful Commands

VS Code Extensions

Updating VulnTrack

Next Steps

Troubleshooting