Setup

Environment Variables

Complete guide to environment variables configuration

Overview

OpenInvoice uses environment variables for configuration. Copy env.example.txt to .env.local and configure the following variables.

Required Variables

Clerk Authentication

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# Redirect URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/auth/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/auth/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/dashboard/overview"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/dashboard/overview"

Database

DATABASE_URL=postgresql://user:password@localhost:5432/openinvoice

Webhook Secret (Optional)

WEBHOOK_SECRET=whsec_...

Optional Variables

Stripe (Payment Processing)

STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_APP_URL=http://localhost:3000
STRIPE_DEFAULT_COUNTRY=US
STRIPE_PLATFORM_FEE_PERCENTAGE=

Resend (Email)

RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=noreply@yourdomain.com
RESEND_FROM_NAME=OpenInvoice
RESEND_WEBHOOK_KEY=whsec_...

TaxJar (Tax Calculation)

TAXJAR_API_KEY=...
TAXJAR_USE_SANDBOX=true

Sentry (Error Tracking)

NEXT_PUBLIC_SENTRY_DSN=https://...@...ingest.sentry.io/...
NEXT_PUBLIC_SENTRY_ORG=your-org
NEXT_PUBLIC_SENTRY_PROJECT=openinvoice
SENTRY_AUTH_TOKEN=sntrys_...
NEXT_PUBLIC_SENTRY_DISABLED=false

Crypto Payments

COINGECKO_API_KEY=...
COINGECKO_API_URL=https://api.coingecko.com/api/v3
CRYPTO_TEST_MODE=false
CRYPTO_USE_TESTNET=false

Cron Jobs

CRON_SECRET=...

File Storage (DigitalOcean Spaces)

DO_SPACES_ENDPOINT=...
DO_SPACES_BUCKET=...
DO_SPACES_KEY=...
DO_SPACES_SECRET=...

Environment-Specific Configuration

Development

Use test/development keys:

  • Clerk development keys
  • Stripe test keys
  • TaxJar sandbox mode
  • Test database

Production

Use production keys:

  • Clerk production keys
  • Stripe live keys
  • TaxJar production mode
  • Production database
  • Verified domains
  • SSL certificates

Security Best Practices

  1. Never Commit Secrets - Keep .env.local in .gitignore
  2. Use Different Keys - Separate dev and prod keys
  3. Rotate Regularly - Rotate API keys periodically
  4. Limit Access - Restrict who can access env vars
  5. Use Secrets Manager - For production, use secrets manager

Next Steps