← operations

Quick Start Guide

Get HiveJournal up and running locally in minutes.

Prerequisites

  • Node.js 18+ installed
  • npm or yarn
  • Supabase account (free tier works)
  • Stripe account (test mode is fine for development)
  • Resend account (free tier works)

Step 1: Clone and Install

# Clone with submodules (pulls the pinned energy-patent-research data needed
# by scripts/import-energy-patents.ts). If you cloned without --recurse,
# run `git submodule update --init --recursive` from the repo root instead.
git clone --recurse-submodules https://github.com/jurowski/hivejournal-2026.git

# Install root dependencies
npm install

# Install frontend dependencies
cd apps/frontend
npm install

# Install backend dependencies
cd ../backend
npm install

Step 2: Set Up Supabase

  1. Create a new project at supabase.com
  2. Go to SQL Editor and run the migration:
    • Copy contents of supabase/migrations/001_initial_schema.sql
    • Paste and execute in Supabase SQL Editor
  3. Get your project URL and anon key from Settings > API
  4. For Local Development - Disable Email Confirmation:
    • Go to Authentication > Settings in Supabase Dashboard
    • Under "Email Auth", toggle OFF "Enable email confirmations"
    • This allows instant signup without email verification (development only!)

Step 3: Configure Environment Variables

Frontend (apps/frontend/.env.local)

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key
NEXT_PUBLIC_API_URL=http://localhost:3001

Backend (apps/backend/.env)

PORT=3001
NODE_ENV=development
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
RESEND_API_KEY=your_resend_api_key
RESEND_FROM_EMAIL=noreply@hivejournal.com
ALLOWED_ORIGINS=http://localhost:3000
JWT_SECRET=your_random_secret_key

Step 4: Run Development Servers

Terminal 1 - Backend

cd apps/backend
npm run dev

Backend will run on http://localhost:3001

Terminal 2 - Frontend

cd apps/frontend
npm run dev

Frontend will run on http://localhost:3000

Step 5: Test the Application

  1. Open http://localhost:3000 in your browser
  2. Click "Get Started" to create an account
  3. Sign in and explore the dashboard

Testing API Endpoints

You can test the backend API directly:

# Health check
curl http://localhost:3001/health

# Get journal entries (requires auth token)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3001/api/journal

Next Steps

  • Set up Stripe products and prices
  • Configure Resend for email sending
  • Set up webhooks for Stripe and Resend
  • Deploy to Vercel (frontend) and Railway (backend)

See DEPLOYMENT.md for production deployment instructions.

Troubleshooting

Port already in use

  • Change PORT in backend .env file
  • Update NEXT_PUBLIC_API_URL in frontend .env.local

Supabase connection errors

  • Verify your Supabase URL and keys
  • Check that migrations have been run
  • Ensure RLS policies are set up correctly

CORS errors

  • Make sure ALLOWED_ORIGINS includes http://localhost:3000
  • Check backend is running on correct port
QUICKSTART — Docs | HiveJournal