Installation

This guide covers the complete installation process for PIPELINE, including system requirements, database setup, environment configuration, and verification steps.

Looking for a faster setup? Check out the Quickstart guide for a streamlined 5-10 minute installation.

System Requirements

Required

Node.js ≥ 18.0.0 (or Bun ≥ 1.0.0)
Git for version control
PostgreSQL database (via Supabase)
Modern browser (Chrome, Firefox, Safari, Edge)

Project Setup

1. Clone the Repository

# Clone via HTTPS
git clone https://github.com/yourusername/pipeline.git

# Or via SSH
git clone [email protected]:yourusername/pipeline.git

# Navigate to project directory
cd pipeline

2. Install Dependencies

bun install

PIPELINE uses Bun for optimal performance. While npm/yarn/pnpm should work, Bun is the officially supported runtime.

3. Verify Installation

# Check installed packages
bun pm ls

# Verify TypeScript compilation
bun run typecheck

Database Setup

PIPELINE uses Supabase (managed PostgreSQL) for data storage with Row-Level Security (RLS) policies.

1. Create Supabase Project

Go to supabase.com
Click Start your project
Sign in with GitHub, GitLab, or email

Create a new project

Click New Project
Choose your organization (or create one)
Fill in project details:
- Name: pipeline-jobs (or your preferred name)
- Database Password: Generate a strong password
- Region: Choose closest to your location
- Pricing Plan: Free tier works for development
Click Create new project

Save your database password! You’ll need it for direct database access and cannot retrieve it later.

Wait for provisioning

Project creation takes 1-2 minutes. You’ll see a progress indicator.

2. Get API Credentials

Navigate to API settings

In your Supabase project dashboard:

Click Settings (gear icon) in the sidebar
Click API under Project Settings

Copy credentials

You’ll need three values:Project URL:

https://YOUR_PROJECT_REF.supabase.co

anon public key:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

service_role key:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Keep your service_role key secret! It bypasses Row-Level Security and should never be exposed in client-side code.

3. Apply Database Migrations

PIPELINE includes 14 migrations that create:

6 tables (jobs, events, insights, scraper_runs, audit_log, audit_alerts)
5 enums (job_status, job_source, event_type, insight_type, scraper_status)
20+ indexes for query performance
RLS policies for data security
Triggers for automation
Audit logging for change tracking
Full-text search with weighting

Supabase CLI (Recommended)
Supabase Dashboard

# Login to Supabase
supabase login

# Link to your project
# Your project ref is in your Supabase URL: https://YOUR_PROJECT_REF.supabase.co
supabase link --project-ref YOUR_PROJECT_REF

# Apply all migrations
supabase db push

# Verify migrations
supabase db diff

The first time you run supabase login, it will open your browser for authentication.

If you prefer not to use the CLI:

Go to your Supabase project dashboard
Click SQL Editor in the sidebar
Click New Query
Apply each migration in order:

Migration 001: Core Tables

-- Copy contents of supabase/migrations/001_tables.sql
-- Paste into SQL Editor
-- Click "Run"

Migration 002: Indexes

-- Copy contents of supabase/migrations/002_indexes.sql
-- Paste into SQL Editor
-- Click "Run"

Migration 003: Triggers

-- Copy contents of supabase/migrations/003_triggers.sql
-- Paste into SQL Editor
-- Click "Run"

Continue with remaining migrations:

004_rls.sql - Row-Level Security policies
005_audit.sql - Audit logging system
006_soft_deletes.sql - Soft delete support
007_rls_soft_delete_fix.sql - RLS for deleted jobs
008_fix_status_transitions.sql - Status transition rules
009_fix_service_role_bypass.sql - Service role limits
010_trigger_error_handling.sql - Error handling
011_remove_redundant_indexes.sql - Index optimization
012_add_check_constraints.sql - Data integrity
013_fulltext_search_weighting.sql - Search weighting
014_fix_security_definer_views.sql - Security fixes

Critical: Run migrations in numerical order! Later migrations depend on earlier ones.

4. Verify Database Setup

Check tables exist

In Supabase Dashboard → Table Editor, verify these tables:

✅ jobs - Job applications
✅ events - Activity timeline
✅ insights - AI-generated insights
✅ scraper_runs - Scraper telemetry
✅ audit_log - Change history
✅ audit_alerts - Security alerts

Verify RLS policies

Click on any table → Policies tab. You should see policies like:

Users can view own jobs
Users can insert own jobs
Users can update own jobs
Users can delete own jobs

Test database connection (optional)

# Run validation script (if you have devDependencies installed)
bun run contracts:validate

# Or test with SQL
supabase db diff

Environment Configuration

1. Create Environment File

cp .env.example .env.local

Never commit .env.local to version control! It’s already in .gitignore but double-check before pushing.

2. Configure Required Variables

Open .env.local and fill in your Supabase credentials:

.env.local

# =============================================================================
# PIPELINE — Environment Variables
# =============================================================================

# ─── Supabase (REQUIRED) ─────────────────────────────────────────────────────
# Get these from: https://supabase.com/dashboard/project/YOUR_PROJECT/settings/api

NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

# ─── Application (REQUIRED for production) ───────────────────────────────────

NEXT_PUBLIC_APP_URL=http://localhost:3000

# Debug mode — set to 'true' for verbose logging
# DEBUG=false

Only Supabase variables are required to get started. AI services, Discord, and other integrations are optional.

3. Optional: Configure AI Services

For AI match scoring and insights (coming in Phase 2):

.env.local

# ─── AI Services (OPTIONAL — Module 4) ───────────────────────────────────────
# Required for: Job scoring, insights generation, daily digests

# Anthropic (Claude)
# Get from: https://console.anthropic.com/account/keys
ANTHROPIC_API_KEY=sk-ant-...

# Google AI (Gemini)
# Get from: https://makersuite.google.com/app/apikey
GOOGLE_AI_API_KEY=...

4. Optional: Configure Integrations

.env.local

# ─── Discord Integration (OPTIONAL — Module 5) ───────────────────────────────
DISCORD_BOT_TOKEN=...
DISCORD_WEBHOOK_ALERTS=https://discord.com/api/webhooks/...
DISCORD_WEBHOOK_DIGEST=https://discord.com/api/webhooks/...

# ─── Google / Gmail Integration (OPTIONAL — Module 5) ────────────────────────
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...

# ─── Scraper Service (OPTIONAL — Module 2) ───────────────────────────────────
SCRAPER_URL=https://your-scraper.fly.dev
SCRAPER_API_KEY=your-secret-key

Development Server

Start the Server

bun run dev

The application will be available at:

Local: http://localhost:3000
Network: http://YOUR_LOCAL_IP:3000

The dev server includes:

⚡ Fast Refresh for instant updates
🔍 TypeScript type checking
🎨 Tailwind CSS hot reload
🐛 Detailed error overlay

Verify Installation

Check server started

You should see:

✓ Ready in 2.3s
○ Local:    http://localhost:3000
○ Network:  http://192.168.1.100:3000

Open in browser

Navigate to http://localhost:3000You should see the PIPELINE landing page with:

Hero section with “Treat job hunting like DevOps”
Sign Up / Log In buttons
Terminal aesthetic

Test authentication

Click Sign Up
Enter email and password
Submit form
Check for success message or email confirmation prompt

Post-Installation Setup

1. Configure Email Confirmations (Development)

By default, Supabase requires email confirmation for new users:

Disable for Development
Configure SMTP

For local development, you can disable email confirmation:

Go to Supabase Dashboard → Authentication → Settings
Scroll to User Signups
Toggle Enable email confirmations to OFF
Click Save

Re-enable email confirmations for production!

2. Generate TypeScript Types (Optional)

Generate TypeScript types from your database schema:

# Generate types
supabase gen types typescript --linked > src/lib/types/database.types.ts

# Verify types
bun run typecheck

Types are already included in the repository and match migration 014. You only need to regenerate if you modify the schema.

3. Run Tests (Optional)

Verify everything is working:

# Run all tests
bun test

# Run with coverage
bun run test:coverage

# Watch mode
bun test --watch

4. Enable RLS Testing (Optional)

Test Row-Level Security policies:

# Install test dependencies (if not already installed)
bun add -d @types/pg pg dotenv

# Run RLS tests
bun run test:rls

Building for Production

Create Production Build

# Create optimized production build
bun run build

# Test production build locally
bun run start

The build process:

Type-checks all TypeScript files
Compiles Next.js pages and API routes
Optimizes images and assets
Generates static pages where possible
Creates production-ready bundles

For deployment instructions, see the Deployment Guide.

Project Structure

Understanding the codebase:

pipeline/
├── app/                      # Next.js App Router
│   ├── (app)/                # Authenticated pages
│   │   ├── tracker/          # Kanban board + list view
│   │   ├── dashboard/        # Analytics dashboard
│   │   ├── intel/            # Market insights
│   │   ├── settings/         # User settings
│   │   └── help/             # Documentation
│   ├── (auth)/               # Auth pages (login, signup)
│   ├── api/                  # API routes
│   │   ├── auth/             # Authentication endpoints
│   │   ├── jobs/             # Jobs CRUD
│   │   ├── analytics/        # Dashboard data
│   │   └── ai/               # AI services
│   └── page.tsx              # Landing page
├── src/
│   ├── components/           # React components
│   │   ├── ui/               # shadcn/ui primitives
│   │   ├── layout/           # Sidebar, topbar, etc.
│   │   ├── jobs/             # Job-related components
│   │   └── tracker/          # Board and list views
│   ├── hooks/                # Custom React hooks
│   ├── lib/                  # Utilities and config
│   │   ├── supabase/         # Supabase clients
│   │   ├── stores/           # Zustand state stores
│   │   ├── types/            # TypeScript types
│   │   └── validations/      # Zod schemas
│   └── views/                # Page-level components
├── supabase/
│   ├── migrations/           # Database migrations
│   └── config.toml           # Supabase configuration
├── docs/                     # Documentation
├── scripts/                  # Automation scripts
├── tests/                    # Test suites
└── .env.local                # Environment variables (create this)

Troubleshooting

Common Installation Issues

Bun installation fails

macOS/Linux:

# Try with sudo
curl -fsSL https://bun.sh/install | bash

# Add to PATH manually
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Windows:

Ensure PowerShell execution policy allows scripts
Run PowerShell as Administrator
Try WSL2 if issues persist

npm/bun install hangs

# Clear package manager cache
bun pm cache rm

# Or for npm
npm cache clean --force

# Delete lockfile and node_modules
rm -rf node_modules bun.lock

# Reinstall
bun install

TypeScript errors after installation

# Ensure all dependencies are installed
bun install

# Clear Next.js cache
rm -rf .next

# Regenerate types
bun run typecheck

Supabase CLI not found

macOS/Linux:

# Install via Homebrew
brew install supabase/tap/supabase

# Or download binary
# https://github.com/supabase/cli/releases

Windows:

# Install via Scoop
scoop install supabase

Database migrations fail

Check connection:

supabase db remote status

Re-link project:

supabase unlink
supabase link --project-ref YOUR_PROJECT_REF

Apply migrations with debug:

supabase db push --debug

Reset and retry (destructive):

supabase db reset

Environment variables not loading

Check file name:

Must be .env.local (not .env or .env.development)

Restart dev server:

# Stop server (Ctrl+C)
# Start again
bun run dev

Verify values:

# In dev tools console
console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)

Port 3000 already in use

Find and kill process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Or use different port:

bun run dev -- --port 3001

Getting Help

If you’re still having issues:

Check existing issues: GitHub Issues
Review documentation: See docs/
Join Discord: Get help from the community
Open an issue: Provide details about your environment and error messages

Next Steps

Configuration

Configure AI services, integrations, and feature flags.

Architecture

Learn about PIPELINE’s architecture and design decisions.

API Reference

Explore API endpoints and data models.

Deployment

Deploy PIPELINE to production (Vercel, Netlify, self-hosted).

Development Workflow

Recommended Setup

VS Code Extensions:
- ESLint
- Prettier
- Tailwind CSS IntelliSense
- TypeScript and JavaScript Language Features

Git Hooks:

# Enable pre-commit type checking
chmod +x scripts/hooks/pre-commit-types.sh
cp scripts/hooks/pre-commit-types.sh .git/hooks/pre-commit

Database Backups:

# Backup database before major changes
supabase db dump -f backup.sql

You’re all set! Head to the Quickstart to track your first job.

Get Started

Core Features

Guides

Architecture

​Installation

​System Requirements

​Required

​Recommended

​Project Setup

​1. Clone the Repository

​2. Install Dependencies

​3. Verify Installation

​Database Setup

​1. Create Supabase Project

​2. Get API Credentials

​3. Apply Database Migrations

​4. Verify Database Setup

​Environment Configuration

​1. Create Environment File

​2. Configure Required Variables

​3. Optional: Configure AI Services

​4. Optional: Configure Integrations

​Development Server

​Start the Server

​Verify Installation

​Post-Installation Setup

​1. Configure Email Confirmations (Development)

​2. Generate TypeScript Types (Optional)

​3. Run Tests (Optional)

​4. Enable RLS Testing (Optional)

​Building for Production

​Create Production Build

​Project Structure

​Troubleshooting

​Common Installation Issues

​Getting Help

​Next Steps

Configuration

Architecture

API Reference

Deployment

​Development Workflow

​Recommended Setup

Build docs developers (and LLMs) love

Installation

System Requirements

Required

Recommended

Project Setup

1. Clone the Repository

2. Install Dependencies

3. Verify Installation

Database Setup

1. Create Supabase Project

2. Get API Credentials

3. Apply Database Migrations

4. Verify Database Setup

Environment Configuration

1. Create Environment File

2. Configure Required Variables

3. Optional: Configure AI Services

4. Optional: Configure Integrations

Development Server

Start the Server

Verify Installation

Post-Installation Setup

1. Configure Email Confirmations (Development)

2. Generate TypeScript Types (Optional)

3. Run Tests (Optional)

4. Enable RLS Testing (Optional)

Building for Production

Create Production Build

Project Structure

Troubleshooting

Common Installation Issues

Getting Help

Next Steps

Development Workflow

Recommended Setup