Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Bun v1.0 or higher (install Bun)
  • PostgreSQL v14 or higher
  • Node.js v18 or higher (for compatibility)
  • Git for version control
This project uses Bun as the JavaScript runtime and package manager. The packageManager is set to bun@1.2.17 in package.json.

​
Clone the Repository

1

Clone and Install Dependencies

 git clone https://github.com/bountydotnew/bounty.new.git
cd bounty.new
bun install
This will install all workspace dependencies using Bun’s fast package manager.
2

Set Up PostgreSQL Database

You have two options for the database:
If running PostgreSQL locally:
# Create a new database
createdb bounty_new

# Your connection string will be:
# postgresql://username:password@localhost:5432/bounty_new
URL-encode the username or password portion of your DATABASE_URL if they contain special characters.
3

Configure Environment Variables

Create a .env file in the root directory by copying .env.example:
cp .env.example .env

​
Required Environment Variables

# NEON DATABASE (https://neon.com)
DATABASE_URL="postgresql://username:password@host/database?sslmode=require"
This is your PostgreSQL connection string from Step 2.
# BETTER AUTH (https://better-auth.com)
BETTER_AUTH_SECRET="bounty"  # Generate with: openssl rand -base64 32
BETTER_AUTH_URL="http://localhost:3000"
In production, generate a secure secret using openssl rand -base64 32. The default “bounty” value is for local development only.
# GITHUB OAUTH (https://github.com/settings/developers)
GITHUB_CLIENT_ID="your_github_oauth_client_id"
GITHUB_CLIENT_SECRET="your_github_oauth_client_secret"
GITHUB_TOKEN="your_github_personal_access_token"  # Optional
Setup Steps:
  1. Go to GitHub Developer Settings
  2. Click “New OAuth App”
  3. Fill in the details:
    • Application name: Bounty Local
    • Homepage URL: http://localhost:3000
    • Authorization callback URL: http://localhost:3000/api/auth/callback/github
  4. Click “Register application”
  5. Copy the Client ID and generate a Client Secret
  6. Add both to your .env file
# GITHUB APP (https://github.com/settings/apps)
GITHUB_APP_NAME="your_github_app_name"
GITHUB_APP_ID="your_github_app_id"
GITHUB_APP_CLIENT_ID="your_github_app_client_id"
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."  # base64 encoded
GITHUB_WEBHOOK_SECRET="your_webhook_secret"
Only needed if you want to test GitHub issue/PR integrations locally.
# STRIPE PAYMENTS (https://stripe.com)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_CONNECT_WEBHOOK_SECRET="whsec_..."
Required for testing payment flows. Get test keys from the Stripe Dashboard.
The following are optional for local development:
# DISCORD (for notifications)
DISCORD_CLIENT_ID="your_discord_client_id"
DISCORD_CLIENT_SECRET="your_discord_client_secret"
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# RESEND (for emails)
RESEND_API_KEY="re_your_resend_api_key"

# UPSTASH REDIS (for rate limiting & real-time)
UPSTASH_REDIS_REST_URL="https://your-redis.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your_upstash_token"

# POSTHOG (for analytics)
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
NEXT_PUBLIC_POSTHOG_KEY="phc_your_posthog_key"

# MARBLE CMS (for blog)
NEXT_PUBLIC_MARBLE_API_URL="https://api.marblecms.com"
MARBLE_WEBHOOK_SECRET="your_marble_webhook_secret"
The app will function without these services, though some features will be disabled.
# BOUNTY APP CONFIGURATION
CRON_SECRET="generate_with_openssl_rand_base64_32"
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_EARLY_ACCESS_ENABLED="false"  # Set to "true" to enable waitlist
4

Initialize the Database

Push the database schema to your PostgreSQL instance:
bun db:push
This uses Drizzle ORM to create all necessary tables. The schema includes:
  • User authentication tables (via Better Auth)
  • Bounty management tables
  • Organizations and invites
  • Submissions and applications
  • Comments, votes, and bookmarks
  • GitHub and Linear integration tables
  • Payment and transaction records
For development, db:push synchronizes your schema without migrations. For production, use bun db:generate and bun db:migrate to create and apply migrations.
5

Start the Development Server

bun dev
This starts the Next.js development server with Turbopack for fast refresh. The application will be available at:http://localhost:3000
The dev script runs all workspace packages in development mode using Turborepo, excluding the Discord bot.

​
Available Scripts

The project includes several useful npm scripts: 
# Start all development servers
bun dev

# Start only the web app
bun dev:web

# Type check the web app
bun check:web

​
Project Structure

The repository is a Turborepo monorepo with the following structure: 
bounty.new/
├── apps/
│   ├── web/              # Next.js 14 web application
│   └── discord-bot/      # Discord bot for notifications
├── packages/
│   ├── api/              # tRPC API routes and procedures
│   ├── auth/             # Better Auth configuration
│   ├── db/               # Drizzle ORM schema and migrations
│   ├── email/            # Email templates (Resend)
│   ├── env/              # Environment variable validation
│   ├── realtime/         # Upstash realtime features
│   ├── stripe/           # Stripe payment integration
│   ├── track/            # Analytics tracking
│   ├── types/            # Shared TypeScript types
│   ├── ui/               # Shared UI components (shadcn/ui)
│   ├── eslint-config/    # Shared ESLint configuration
│   └── typescript-config/ # Shared TypeScript configuration
└── package.json

​
Accessing Drizzle Studio

Drizzle Studio provides a GUI for inspecting and managing your database: 
bun db:studio
This opens a web interface at https://local.drizzle.studio where you can:
  • Browse all tables and relationships
  • Run custom SQL queries
  • Edit records directly
  • Inspect indexes and constraints

​
Troubleshooting

  • Verify your DATABASE_URL is correct
  • Ensure PostgreSQL is running
  • Check that the database exists
  • Confirm URL-encoded special characters in credentials
  • For Neon, ensure sslmode=require is in the connection string
  • Verify callback URL is exactly: http://localhost:3000/api/auth/callback/github
  • Check that Client ID and Secret are correct
  • Ensure the OAuth app is not suspended
  • Clear browser cookies and try again
  • Update Bun: bun upgrade
  • Clear Bun cache: rm -rf ~/.bun/install/cache
  • Try deleting node_modules and reinstalling: rm -rf node_modules && bun install
Change the port in your Next.js config or kill the process:
# Find and kill process on port 3000
lsof -ti:3000 | xargs kill -9
  • Run type checking: bun check-types
  • Ensure all workspace packages are built
  • Try restarting your IDE/editor

​
Next Steps

Now that you have Bounty running locally:

Quickstart Guide

Learn how to create bounties and submit work

API Documentation

Explore the tRPC API endpoints

Self-Hosting Guide

Host Bounty on your own infrastructure

Deployment

Deploy Bounty to production

Build docs developers (and LLMs) love

Get started for freeTalk to us