Environment Variables

Overview

Bounty uses environment variables for configuration. Create a .env file in your project root with the required variables.

Never commit your .env file to version control. The .env.example file in the repository shows the required format without sensitive values.

Quick Setup

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

# Edit with your values
nano .env

Required Variables

These variables are essential for Bounty to function:

Database

DATABASE_URL

string

required

PostgreSQL connection string with SSL support.Format: postgresql://username:password@host/database?sslmode=requireProviders:

Neon - Serverless PostgreSQL (recommended)
Supabase - Open source PostgreSQL
Railway - Simple PostgreSQL hosting
Self-hosted PostgreSQL instance

Get a free temporary database (72 hours) at neon.new

URL-encode special characters in username or password. For example, p@ssw0rd! becomes p%40ssw0rd%21

DATABASE_URL="postgresql://username:[email protected]/neondb?sslmode=require"

Authentication

BETTER_AUTH_SECRET

string

required

Secret key for Better Auth session encryption. Must be at least 32 characters.Generate with:

openssl rand -base64 32

Use a different secret for each environment (dev, staging, production)

BETTER_AUTH_URL

string

required

The full URL where your application is hosted.

Development: http://localhost:3000
Production: https://yourdomain.com

This URL is used for OAuth callbacks and must match your OAuth app configuration

GitHub OAuth

GITHUB_CLIENT_ID

string

required

GitHub OAuth application client ID.Setup:

Go to GitHub Developer Settings
Click “OAuth Apps” → “New OAuth App”
Set Authorization callback URL: {BETTER_AUTH_URL}/api/auth/callback/github
Copy the Client ID

GITHUB_CLIENT_SECRET

string

required

GitHub OAuth application client secret.

Keep this secret secure. Never expose it in client-side code.

GitHub App

GITHUB_APP_NAME

string

required

Your GitHub App slug (e.g., bountydotnew from github.com/apps/bountydotnew).Setup:

Go to GitHub Apps Settings
Click “New GitHub App”
Configure webhook URL: {BETTER_AUTH_URL}/api/webhooks/github
Enable permissions: Issues (read/write), Pull requests (read/write)
Copy the app slug from the URL

GITHUB_APP_ID

string

required

Numeric ID of your GitHub App (found in app settings).

GITHUB_APP_CLIENT_ID

string

required

GitHub App client ID (different from OAuth client ID).

GITHUB_APP_PRIVATE_KEY

string

required

GitHub App private key, base64 encoded.Setup:

Generate private key in GitHub App settings
Encode to base64:

cat private-key.pem | base64 -w 0

Set in environment: GITHUB_APP_PRIVATE_KEY="LS0tLS1CRUdJTi..."

The key must be base64 encoded and include the full PEM format including headers

GITHUB_WEBHOOK_SECRET

string

required

Secret for verifying GitHub webhook payloads.Generate with:

openssl rand -hex 32

Set this same value in your GitHub App webhook settings.

Redis Cache

UPSTASH_REDIS_REST_URL

string

required

Upstash Redis REST API URL.Setup:

Create account at Upstash
Create a new Redis database
Copy the REST URL from database details

UPSTASH_REDIS_REST_URL="https://example-12345.upstash.io"

UPSTASH_REDIS_REST_TOKEN

string

required

Upstash Redis REST API token (found in database details).

Application URLs

NEXT_PUBLIC_BASE_URL

string

required

Public-facing base URL of your application.

Development: http://localhost:3000
Production: https://yourdomain.com

The NEXT_PUBLIC_ prefix makes this variable available in client-side code

Optional Variables

These variables enable additional features:

Discord Integration

DISCORD_CLIENT_ID

string

Discord OAuth application client ID.Setup: Discord Developer Portal

DISCORD_CLIENT_SECRET

string

Discord OAuth application client secret.

DISCORD_INVITE_URL

string

Discord server invite link (e.g., https://discord.gg/your_server).

DISCORD_WEBHOOK_URL

string

Discord webhook URL for general notifications.Setup: Server Settings → Integrations → Webhooks → New Webhook

BOUNTY_FEED_WEBHOOK_URL

string

Discord webhook URL specifically for bounty feed updates.

FEEDBACK_WEBHOOK_URL

string

Discord webhook URL for user feedback submissions.

Payment Processing

Stripe

STRIPE_SECRET_KEY

string

Stripe secret API key (starts with sk_test_ or sk_live_).Setup: Stripe Dashboard

STRIPE_PUBLISHABLE_KEY

string

Stripe publishable API key (starts with pk_test_ or pk_live_).

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

string

Same as STRIPE_PUBLISHABLE_KEY but accessible in client-side code.

STRIPE_CONNECT_WEBHOOK_SECRET

string

Stripe webhook signing secret for Connect webhooks.Setup: Stripe Dashboard → Developers → Webhooks → Add endpointEndpoint URL: {NEXT_PUBLIC_BASE_URL}/api/webhooks/stripe

BOUNTY_PRO_MONTHLY_ID

string

Stripe Price ID for monthly Bounty Pro subscription.

BOUNTY_PRO_ANNUAL_ID

string

Stripe Price ID for annual Bounty Pro subscription.

Autumn (Alternative Payment Processor)

AUTUMN_API_URL

string

Autumn API base URL.Default: https://api.useautumn.com/v1

AUTUMN_SECRET_KEY

string

Autumn secret API key (starts with am_sk_test_ or am_sk_live_).Setup: Autumn Dashboard

AUTUMN_SUCCESS_URL

string

URL to redirect users after successful payment.Example: http://localhost:3000/success

AUTUMN_CANCEL_URL

string

URL to redirect users after cancelled payment.Example: http://localhost:3000/billing

Email

RESEND_API_KEY

string

Resend API key for transactional emails.Setup: Resend DashboardStarts with re_

Analytics & Monitoring

NEXT_PUBLIC_POSTHOG_KEY

string

PostHog project API key.Setup: PostHog Dashboard → Project Settings → API KeysStarts with phc_

NEXT_PUBLIC_POSTHOG_HOST

string

PostHog API host URL.US: https://us.i.posthog.com
EU: https://eu.i.posthog.com

NEXT_PUBLIC_SENTRY_DSN

string

Sentry Data Source Name for error tracking.Setup: Sentry Dashboard → Settings → Client Keys (DSN)

SENTRY_AUTH_TOKEN

string

Sentry authentication token for source map uploads.Setup: Sentry Dashboard → Settings → Auth TokensStarts with sntrys_

SENTRY_PROJECT

string

Sentry project slug (e.g., javascript-nextjs).

SENTRY_ORG

string

Sentry organization slug.

CMS & Content

NEXT_PUBLIC_MARBLE_API_URL

string

Marble CMS API endpoint.Default: https://api.marblecms.comSetup: Marble CMS

MARBLE_WEBHOOK_SECRET

string

Marble CMS webhook verification secret.Setup: Marble Dashboard → Workspace → API Keys

MARLE_WEBHOOK_SECRET

string

Alternative Marble webhook secret (legacy, same as MARBLE_WEBHOOK_SECRET).

Security & Rate Limiting

UNKEY_ROOT_KEY

string

Unkey root API key for API key management.Setup: Unkey DashboardStarts with unkey_

CRON_SECRET

string

Secret for authenticating cron job requests.Generate with:

openssl rand -base64 32

Used in Vercel cron jobs (see vercel.json).

Feature Flags

NEXT_PUBLIC_EARLY_ACCESS_ENABLED

boolean

Enable early access mode (restricts app to invited users only).Values:

"true" - Early access enabled (default)
"false" - Fully public, no access restrictions

Set to "false" on launch day to make the app publicly accessible.

Additional GitHub

GITHUB_TOKEN

string

Personal GitHub access token (optional, for enhanced API limits).Setup: GitHub Settings → Developer settings → Personal access tokens → Generate new token

Environment-Specific Configuration

Development

# .env.development
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_EARLY_ACCESS_ENABLED="false"

# Use test mode keys for services
STRIPE_SECRET_KEY="sk_test_..."
AUTUMN_SECRET_KEY="am_sk_test_..."

Production

# .env.production
BETTER_AUTH_URL="https://yourdomain.com"
NEXT_PUBLIC_BASE_URL="https://yourdomain.com"
NEXT_PUBLIC_EARLY_ACCESS_ENABLED="true"

# Use live mode keys for services
STRIPE_SECRET_KEY="sk_live_..."
AUTUMN_SECRET_KEY="am_sk_live_..."

Validation

Bounty uses @t3-oss/env-nextjs for environment variable validation. If required variables are missing, the application will fail to start with a detailed error message.

Set SKIP_ENV_VALIDATION="true" during build if you’re using environment variables from your deployment platform (configured in vercel.json).

Security Best Practices

Secret Generation

Always use cryptographically secure random values:

openssl rand -base64 32
openssl rand -hex 32

Separate Environments

Use different credentials for dev, staging, and production environments.

Secret Rotation

Regularly rotate API keys and secrets, especially after team member changes.

Access Control

Limit access to environment variables using your deployment platform’s IAM features.

Troubleshooting

Application won't start

Check that all required variables are set
Verify DATABASE_URL format is correct
Ensure secrets are properly encoded (no extra whitespace)
Check for syntax errors in .env file

Database connection fails

Verify DATABASE_URL includes ?sslmode=require
URL-encode special characters in username/password
Check database is accessible from your network
Ensure PostgreSQL version is 14 or higher

OAuth redirect errors

Verify BETTER_AUTH_URL matches OAuth app callback URL
Check callback URL format: {BETTER_AUTH_URL}/api/auth/callback/github
Ensure URL has no trailing slash
Confirm OAuth app is not in suspended state

GitHub webhooks not working

Verify GITHUB_WEBHOOK_SECRET matches GitHub App settings
Check webhook URL is publicly accessible
Ensure webhook permissions are correctly set
Review webhook delivery logs in GitHub App settings

Next Steps

Database Setup

Configure PostgreSQL and run database migrations

Get Started

Core Features

Integrations

Self-Hosting

Environment Variables

Overview

Quick Setup

Required Variables

Database

Authentication

GitHub OAuth

GitHub App

Redis Cache

Application URLs

Optional Variables

Discord Integration

Payment Processing

Stripe

Autumn (Alternative Payment Processor)

Email

Analytics & Monitoring

CMS & Content

Security & Rate Limiting

Feature Flags

Additional GitHub

Environment-Specific Configuration

Development

Production

Validation

Security Best Practices

Secret Generation

Separate Environments

Secret Rotation

Access Control

Troubleshooting

Next Steps

Database Setup

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Self-Hosting

​Overview

​Quick Setup

​Required Variables

​Database

​Authentication

​GitHub OAuth

​GitHub App

​Redis Cache

​Application URLs

​Optional Variables

​Discord Integration

​Payment Processing

​Stripe

​Autumn (Alternative Payment Processor)

​Email

​Analytics & Monitoring

​CMS & Content

​Security & Rate Limiting

​Feature Flags

​Additional GitHub

​Environment-Specific Configuration

​Development

​Production

​Validation

​Security Best Practices

Secret Generation

Separate Environments

Secret Rotation

Access Control

​Troubleshooting

​Next Steps

Database Setup

Build docs developers (and LLMs) love

Overview

Quick Setup

Required Variables

Database

Authentication

GitHub OAuth

GitHub App

Redis Cache

Application URLs

Optional Variables

Discord Integration

Payment Processing

Stripe

Autumn (Alternative Payment Processor)

Email

Analytics & Monitoring

CMS & Content

Security & Rate Limiting

Feature Flags

Additional GitHub

Environment-Specific Configuration

Development

Production

Validation

Security Best Practices

Troubleshooting

Next Steps