Docs
→
Getting Started
→
Installation

Installation

Complete installation guide for HeadlessX V2.0

Prerequisites

Before installing HeadlessX, ensure you have:

  • Node.js 18+ (Download)
  • pnpm 9+ (Install)
  • PostgreSQL or Supabase account
  • 4GB+ RAM (8GB+ recommended)

Quick Install

1. Clone the Repository

git clone https://github.com/yourusername/HeadlessX.git
cd HeadlessX

2. Install Dependencies

# Install all dependencies (pnpm required - npm/yarn will fail)
pnpm install

# Download Camoufox browser (runs automatically on install)
pnpm camoufox:fetch

Note: pnpm is required because the project uses workspace features. npm and yarn will not work correctly.

3. Configure Environment

Create .env files in the root and backend directories:

Root .env:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/headlessx"

# Backend API URL (for frontend)
NEXT_PUBLIC_API_URL="http://localhost:3001"

backend/.env:

# Server Configuration
PORT=3001
NODE_ENV=development

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/headlessx"

# Frontend URL (CORS)
FRONTEND_URL="http://localhost:3000"

# Logging
LOG_LEVEL=info
LOG_DIR=./logs

4. Setup Database

# Push schema to database
pnpm db:push

# Or run migrations
pnpm db:migrate

5. Start the System

# Start both frontend and backend
pnpm dev

Platform-Specific Scripts

Windows

# One-click install
scripts\install.bat

# Start development servers
scripts\start.bat

Linux / macOS

# One-click install
./scripts/install.sh

# Start development servers
./scripts/start.sh

Access Points

After installation, access the application at:

ServiceURL
🖥️ Dashboardhttp://localhost:3000
🔗 Backend APIhttp://localhost:3001

Verify Installation

Test the API

curl http://localhost:3001/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-01-28T12:00:00.000Z"
}

Test Scraping

curl -X POST http://localhost:3001/api/website/html \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"url": "https://example.com"}'

Troubleshooting

Port Already in Use

If ports 3000 or 3001 are unavailable:

  1. Change PORT in backend/.env
  2. Update NEXT_PUBLIC_API_URL to match
  3. Restart the servers

Camoufox Download Failed

# Manually download Camoufox
pnpm camoufox:fetch --force

# Or download from specific version
pnpm camoufox:fetch --version 0.1.0

Database Connection Error

  1. Verify PostgreSQL is running
  2. Check DATABASE_URL format: 
    postgresql://username:password@host:port/database
  3. Ensure database exists: 
    createdb headlessx

Dependencies Installation Issues

# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Production Deployment

Environment Variables

Set these in your production environment:

NODE_ENV=production
DATABASE_URL="your-production-db-url"
NEXT_PUBLIC_API_URL="https://api.yourdomain.com"

Build Commands

# Build frontend
cd frontend
pnpm build

# Build backend
cd backend
pnpm build

Start Production

# Frontend (runs on port 3000)
cd frontend
pnpm start

# Backend (runs on port 3001)
cd backend
pnpm start

Docker Installation (Coming Soon)

Docker support is planned for a future release. Track progress in Issue #XX.

Next Steps