Self-Deployment Guide

Deploy PDR AI on your own infrastructure with complete control and customization

View on GitHub

Prerequisites

Node.js & Package Manager

  • Node.js v18.0 or higher
  • pnpm (recommended) or npm
  • Git for version control

Database

  • Docker (for local PostgreSQL)
  • Or existing PostgreSQL instance
  • PostgreSQL 14+ recommended

API Keys Required

  • OpenAI API key
  • Clerk authentication
  • UploadThing for file storage

Quick Start

1. Clone the Repository

git clone https://github.com/Deodat-Lawson/pdr_ai_v2.git
cd pdr_ai_v2

2. Install Dependencies

pnpm install

3. Configure Environment Variables

Create a .env file in the root directory with all required variables:

# Database Configuration
# Format: postgresql://[user]:[password]@[host]:[port]/[database]
DATABASE_URL="postgresql://postgres:password@localhost:5432/pdr_ai_v2"

# Clerk Authentication (get from https://clerk.com/)
# Required for user authentication and authorization
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# Clerk Force Redirect URLs (Optional - for custom redirect after authentication)
# These URLs control where users are redirected after sign in/up/sign out
# If not set, Clerk will use default redirect behavior
NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL=https://your-domain.com/employer/home
NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL=https://your-domain.com/signup
NEXT_PUBLIC_CLERK_SIGN_OUT_FORCE_REDIRECT_URL=https://your-domain.com/

# OpenAI API (get from https://platform.openai.com/)
# Required for AI features: document analysis, embeddings, chat
OPENAI_API_KEY=your_openai_api_key

# LangChain (get from https://smith.langchain.com/)
# Optional: Required for LangSmith tracing and monitoring
# LangSmith provides observability and debugging for LangChain operations
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langchain_api_key

# Tavily Search API (get from https://tavily.com/)
# Optional: Required for enhanced web search capabilities
# Used for finding related documents and external resources
TAVILY_API_KEY=your_tavily_api_key

# UploadThing (get from https://uploadthing.com/)
# Required for file uploads (PDF documents)
UPLOADTHING_SECRET=your_uploadthing_secret
UPLOADTHING_APP_ID=your_uploadthing_app_id

# Environment Configuration
# Options: development, test, production
NODE_ENV=development

# Optional: Skip environment validation (useful for Docker builds)
# SKIP_ENV_VALIDATION=false

4. Set Up Database

# Start PostgreSQL with Docker
chmod +x start-database.sh
./start-database.sh

# Run migrations
pnpm db:push

5. Start Development Server

pnpm dev

Your application will be available at http://localhost:3000

Setting Up API Keys

Clerk Authentication

  1. Create an account at Clerk.com
  2. Create a new application
  3. Copy the publishable and secret keys
  4. Add them to your .env file
  5. Configure sign-in/sign-up methods as needed
  6. Optional: Set up force redirect URLs:
    • NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL - Redirect after sign in
    • NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL - Redirect after sign up
    • NEXT_PUBLIC_CLERK_SIGN_OUT_FORCE_REDIRECT_URL - Redirect after sign out

OpenAI API

  1. Create an account at OpenAI Platform
  2. Navigate to API keys section
  3. Generate a new API key
  4. Add the key to your .env file
  5. Set up billing for API usage

LangChain (LangSmith) - Optional

  1. Create an account at LangSmith
  2. Generate an API key from your account settings
  3. Set LANGCHAIN_TRACING_V2=true in your .env file
  4. Add LANGCHAIN_API_KEY to your .env file
  5. This enables tracing and monitoring of LangChain operations for debugging

Tavily Search API - Optional

  1. Create an account at Tavily
  2. Generate an API key from your dashboard
  3. Add TAVILY_API_KEY to your .env file
  4. Used for enhanced web search capabilities in document analysis

UploadThing

  1. Create an account at UploadThing.com
  2. Create a new app
  3. Copy the secret and app ID
  4. Add them to your .env file

Production Deployment

Prerequisites for Production

  • ✅ All environment variables configured
  • ✅ Production database set up (PostgreSQL with pgvector extension)
  • ✅ API keys for all external services
  • ✅ Domain name configured (if using custom domain)

1. Vercel (Recommended for Next.js)

Vercel is the recommended platform for Next.js applications with automatic deployments and scaling.

  1. Push your code to GitHub
    git push origin main
  2. Import repository on Vercel
    • Go to vercel.com and sign in
    • Click "Add New Project"
    • Import your GitHub repository
  3. Set up Database and Environment Variables

    Database Setup:

    Option A: Using Vercel Postgres (Recommended)

    1. In Vercel dashboard, go to Storage → Create Database → Postgres
    2. Choose a region and create the database
    3. Vercel will automatically create the DATABASE_URL environment variable
    4. Enable pgvector extension: Connect to your database and run CREATE EXTENSION IF NOT EXISTS vector;

    Option B: Using Neon Database (Recommended for pgvector support)

    1. Create a Neon account at neon.tech if you don't have one
    2. Create a new project in Neon dashboard
    3. Choose PostgreSQL version 14 or higher
    4. In Vercel dashboard, go to your project → Storage tab
    5. Click "Create Database" or "Browse Marketplace"
    6. Select "Neon" from the integrations
    7. Click "Connect" or "Add Integration"
    8. Authenticate with your Neon account
    9. Select your Neon project and branch
    10. Vercel will automatically create the DATABASE_URL environment variable from Neon
    11. You may also see additional Neon-related variables like POSTGRES_URL, POSTGRES_PRISMA_URL, etc.
    12. Enable pgvector extension in Neon:
      • Go to Neon dashboard → SQL Editor
      • Run: CREATE EXTENSION IF NOT EXISTS vector;

    Option C: Using External Database (Manual Setup)

    1. In Vercel dashboard, go to Settings → Environment Variables
    2. Click "Add New"
    3. Key: DATABASE_URL
    4. Value: Your PostgreSQL connection string
    5. Select environments: Production, Preview, Development (as needed)
    6. Click "Save"

    Add Other Environment Variables:

    • In Vercel dashboard, go to Settings → Environment Variables
    • Add all required environment variables:
      • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
      • CLERK_SECRET_KEY
      • OPENAI_API_KEY
      • UPLOADTHING_SECRET
      • UPLOADTHING_APP_ID
      • NODE_ENV=production
      • LANGCHAIN_TRACING_V2=true (optional, for LangSmith tracing)
      • LANGCHAIN_API_KEY (optional, required if tracing enabled)
      • TAVILY_API_KEY (optional, for enhanced web search)
      • NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL (optional)
      • NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL (optional)
      • NEXT_PUBLIC_CLERK_SIGN_OUT_FORCE_REDIRECT_URL (optional)
  4. Configure build settings
    • Build Command: pnpm build
    • Output Directory: .next (default)
    • Install Command: pnpm install
  5. Deploy
    • Click "Deploy"
    • Vercel will automatically deploy on every push to your main branch

Post-Deployment Steps:

  1. Enable pgvector Extension:
    • For Vercel Postgres: Use Vercel's SQL editor in Storage dashboard
    • For Neon: Go to Neon dashboard → SQL Editor
    • For External Database: Connect using your PostgreSQL client
    • Run: CREATE EXTENSION IF NOT EXISTS vector;
  2. Run database migrations:
    # Option 1: Using Vercel CLI locally
    vercel env pull .env.local
    pnpm db:migrate

    # Option 2: Using direct connection
    DATABASE_URL="your_production_db_url" pnpm db:migrate
  3. Set up Clerk webhooks (if needed): Configure webhook URL in Clerk dashboard
  4. Configure UploadThing: Add your production domain to allowed origins

2. Self-Hosted VPS

Deploy on your own VPS with full control over the infrastructure.

  1. Prerequisites
    • VPS with Node.js 18+ installed
    • PostgreSQL database (with pgvector extension)
    • Nginx (for reverse proxy)
    • PM2 or similar process manager
  2. Clone and install
    git clone <your-repo-url>
    cd pdr_ai_v2-2
    pnpm install
  3. Configure environment variables
    nano .env # Add all production environment variables
  4. Build the application
    pnpm build
  5. Set up PM2
    npm install -g pm2
    pm2 start pnpm --name "pdr-ai" -- start
    pm2 save
    pm2 startup
  6. Configure Nginx
    server {
      listen 80;
      server_name your-domain.com;
      location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
      }
    }
  7. Set up SSL with Let's Encrypt
    sudo apt-get install certbot python3-certbot-nginx
    sudo certbot --nginx -d your-domain.com
  8. Run database migrations
    pnpm db:migrate

Production Database Setup

Important: Your production database must have the pgvector extension enabled:

CREATE EXTENSION IF NOT EXISTS vector;

Recommended Database Providers:

  • Neon: Fully serverless PostgreSQL with pgvector support
  • Supabase: PostgreSQL with pgvector extension
  • AWS RDS: Managed PostgreSQL (requires manual pgvector installation)
  • Railway: Simple PostgreSQL hosting

Post-Deployment Checklist

  • ✅ Verify all environment variables are set correctly
  • ✅ Database migrations have been run
  • ✅ Clerk authentication is working
  • ✅ File uploads are working (UploadThing)
  • ✅ AI features are functioning (OpenAI API)
  • ✅ Database has pgvector extension enabled
  • ✅ SSL certificate is configured (if using custom domain)
  • ✅ Monitoring and logging are set up
  • ✅ Backup strategy is in place
  • ✅ Error tracking is configured (e.g., Sentry)

Database Management

Useful Database Commands

# Open Drizzle Studio (Database GUI)
pnpm db:studio

# Generate new migrations
pnpm db:generate

# Apply migrations
pnpm db:migrate

# Push schema changes directly (dev)
pnpm db:push

Troubleshooting

Database Connection Issues

  • Ensure Docker is running: docker ps
  • Check database container status: docker restart pdr_ai_v2-postgres
  • Verify DATABASE_URL in .env file

Build Errors

  • Clear Next.js cache: rm -rf .next
  • Reinstall dependencies: rm -rf node_modules && pnpm install
  • Check TypeScript errors: pnpm typecheck

API Key Issues

  • Verify all required environment variables are set
  • Check for spaces around = in .env file
  • Ensure API keys are valid and have proper permissions
  • Restart the development server after changing .env

What You Get

Full Source Code

Complete access to all application code with no restrictions

Predictive Document Analysis

AI-powered missing document detection and recommendations

AI Chat Engine

Interactive Q&A system for document analysis

Employee Management

Complete employee and employer authentication system

Document Management

Upload, categorize, and manage documents

Analytics Dashboard

Insights and statistics for document usage

Need Help?

Having trouble with deployment? Our support team is here to help!

GitHub Issues