Installation Guide

Comprehensive installation guide for HiveForge with all configuration options.

System Requirements

Hardware

CPU: 2+ cores recommended
RAM: 8GB minimum, 16GB recommended
Storage: 10GB free space

Software

Tool	Version	Required	Notes
Node.js	18+	Yes	LTS version recommended
pnpm	8+	Yes	Package manager
Python	3.11+	Yes	Backend runtime
Docker	24+	Yes	For Supabase local development
Git	2+	Yes	Version control
Supabase CLI	Latest	Yes	Database management

Installation Steps

1. Install System Dependencies

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
# Install dependencies
brew install node python@3.11 git docker
brew install supabase/tap/supabase
 
# Install pnpm
npm install -g pnpm

Linux (Ubuntu/Debian)

# Update package list
sudo apt update
 
# Install Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Install Python 3.11
sudo apt install python3.11 python3.11-venv python3-pip
 
# Install Docker
sudo apt install docker.io docker-compose
 
# Install pnpm
npm install -g pnpm
 
# Install Supabase CLI
brew install supabase/tap/supabase
# Or use npm
npm install -g supabase

Windows

# Install using Chocolatey
choco install nodejs python311 git docker-desktop
 
# Install pnpm
npm install -g pnpm
 
# Install Supabase CLI
npm install -g supabase

2. Clone Repository

# Clone via HTTPS
git clone https://github.com/YOUR-ORG/hiveforge.git
 
# Or clone via SSH
git clone git@github.com:YOUR-ORG/hiveforge.git
 
cd hiveforge

3. Install Project Dependencies

# Install all workspace dependencies
pnpm install
 
# This installs:
# - Next.js and React dependencies
# - FastAPI and Python packages
# - Shared UI components
# - Development tools

The monorepo structure means this single command installs everything for:

Frontend (apps/web)
Backend (apps/api)
Documentation (docs)
Shared packages (packages/*)

4. Python Virtual Environment (Recommended)

# Create virtual environment for API
cd apps/api
python3.11 -m venv venv
 
# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# Or on Windows:
# .\venv\Scripts\activate
 
# Install Python dependencies
pip install -r requirements.txt

5. Configure Environment Variables

# Copy example environment file
cp .env.example .env

Edit .env with your configuration:

# ============================================
# REQUIRED: Application URLs
# ============================================
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8000
 
# ============================================
# REQUIRED: Supabase Configuration
# ============================================
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret
 
# ============================================
# OPTIONAL: Stripe (for billing features)
# ============================================
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
 
# ============================================
# OPTIONAL: Email (Resend)
# ============================================
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=noreply@yourdomain.com
 
# ============================================
# OPTIONAL: AI Features
# ============================================
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
 
# ============================================
# REQUIRED: Platform Configuration
# ============================================
PLATFORM_ADMIN_EMAILS=admin@example.com,admin2@example.com
HARD_ISOLATION_ENABLED=false
 
# ============================================
# OPTIONAL: Monitoring
# ============================================
SENTRY_DSN=https://...
SENTRY_AUTH_TOKEN=...

See Environment Variables Reference for details.

6. Start Supabase

# Initialize Supabase
supabase init
 
# Start all Supabase services
supabase start

This command will output important credentials:

Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
        anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Copy the anon key and service_role key to your .env file.

7. Database Setup

# Run migrations to set up database schema
pnpm db:migrate
 
# Seed database with sample data (optional)
pnpm db:seed
 
# Create platform admin user (optional)
pnpm db:create-admin

8. Verify Installation

# Start all development servers
pnpm dev

Check that all services are running:

Frontend: http://localhost:3000 (opens in a new tab)
Backend API: http://localhost:8000 (opens in a new tab)
API Docs: http://localhost:8000/docs (opens in a new tab)
Supabase Studio: http://localhost:54323 (opens in a new tab)
Inbucket (Email): http://localhost:54324 (opens in a new tab)

Configuration Options

Multi-Tenant vs Hard Isolation

Set in .env:

# Multi-tenant (shared database)
HARD_ISOLATION_ENABLED=false
 
# Hard isolation (separate database per tenant)
HARD_ISOLATION_ENABLED=true

See Multi-Tenancy Architecture for details.

Authentication Providers

Configure in Supabase Studio (http://localhost:54323 (opens in a new tab)):

Go to Authentication > Providers
Enable providers:
- Email/Password (enabled by default)
- Google OAuth
- GitHub OAuth
- More...

See Authentication Setup for configuration.

Stripe Configuration

For billing features:

Create Stripe account at https://stripe.com (opens in a new tab)
Get API keys from Dashboard > Developers > API keys
Set up products and prices
Configure webhook endpoint

See Billing Setup for details.

Development Tools

Recommended VS Code Extensions

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-python.python",
    "ms-python.vscode-pylance",
    "supabase.supabase-vscode"
  ]
}

Git Hooks

HiveForge uses Husky for git hooks:

# Install git hooks
pnpm prepare
 
# Hooks configured:
# - pre-commit: Lint and format
# - pre-push: Run tests
# - commit-msg: Validate commit messages

Next Steps

Troubleshooting

Docker Issues

If Docker fails to start Supabase:

# Check Docker is running
docker ps
 
# Restart Docker Desktop
# Then retry: supabase start

Port Conflicts

If ports are already in use:

# Check what's using the port
lsof -i :3000
 
# Kill the process
kill -9 <PID>
 
# Or change ports in package.json

Permission Denied Errors

# Fix permissions on Unix systems
sudo chown -R $USER:$USER .
chmod -R u+w .

For more help, see Troubleshooting.

Quick Start First Steps