Skip to main content

​
Overview

OpenSight uses environment variables for configuration. Copy .env.example to .env and configure the variables for your deployment. 
cp .env.example .env

​
Required Variables

These variables must be configured for OpenSight to function:

​
Database

​
DATABASE_URL
string
required
PostgreSQL connection stringFormat: postgresql://user:password@host:port/databaseExample:
# For Docker deployment (use service name)
DATABASE_URL=postgresql://opensight:opensight@postgres:5432/opensight

# For local development
DATABASE_URL=postgresql://user:password@localhost:5432/opensight

​
Authentication

​
JWT_SECRET
string
required
Secret key for signing JWT access tokensRequirements: Minimum 64 characters, cryptographically randomExample:
JWT_SECRET=generate-a-64-char-random-string-here-use-openssl-rand-hex-32
Generate secure secret:
openssl rand -hex 32
​
JWT_REFRESH_SECRET
string
required
Secret key for signing JWT refresh tokensRequirements: Minimum 64 characters, cryptographically random (different from JWT_SECRET)Example:
JWT_REFRESH_SECRET=generate-another-different-64-char-random-string-here
Generate secure secret:
openssl rand -hex 32

​
Application URLs

​
NEXT_PUBLIC_APP_URL
string
required
Public URL where the web application is hostedExample:
# Development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Production
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
​
NEXT_PUBLIC_API_URL
string
required
Public URL where the API server is accessibleExample:
# Development
NEXT_PUBLIC_API_URL=http://localhost:4000

# Production
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
​
FRONTEND_URL
string
required
Frontend application URL (used by API for CORS and redirects)Example:
FRONTEND_URL=http://localhost:3000

​
Optional Variables

​
OAuth Authentication

Configure OAuth providers for user authentication:
​
GITHUB_CLIENT_ID
string
GitHub OAuth application client IDWhere to get: https://github.com/settings/developersExample:
GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
​
GITHUB_CLIENT_SECRET
string
GitHub OAuth application client secretExample:
GITHUB_CLIENT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
​
GOOGLE_CLIENT_ID
string
Google OAuth 2.0 client IDWhere to get: https://console.cloud.google.com/apis/credentialsExample:
GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com
​
GOOGLE_CLIENT_SECRET
string
Google OAuth 2.0 client secretExample:
GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

​
Payment Processing (Stripe)

​
STRIPE_SECRET_KEY
string
Stripe secret API key for server-side operationsWhere to get: https://dashboard.stripe.com/apikeysExample:
# Test key
STRIPE_SECRET_KEY=sk_test_51AbCdEfGhIjKlMnOpQrStUvWxYz

# Live key
STRIPE_SECRET_KEY=sk_live_51AbCdEfGhIjKlMnOpQrStUvWxYz
​
STRIPE_WEBHOOK_SECRET
string
Stripe webhook signing secret for verifying webhook eventsWhere to get: https://dashboard.stripe.com/webhooksExample:
STRIPE_WEBHOOK_SECRET=whsec_abcdefghijklmnopqrstuvwxyz123456
​
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
string
Stripe publishable key for client-side operationsExample:
# Test key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51AbCdEfGhIjKlMnOpQrStUvWxYz

# Live key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_51AbCdEfGhIjKlMnOpQrStUvWxYz
​
STRIPE_STARTER_PRICE_ID
string
Stripe Price ID for the Starter planWhere to get: https://dashboard.stripe.com/productsExample:
STRIPE_STARTER_PRICE_ID=price_1AbCdEfGhIjKlMnO
​
STRIPE_GROWTH_PRICE_ID
string
Stripe Price ID for the Growth planExample:
STRIPE_GROWTH_PRICE_ID=price_1PqRsTuVwXyZaBcD

​
Email Service (Resend)

​
RESEND_API_KEY
string
Resend API key for sending transactional emailsWhere to get: https://resend.com/api-keysExample:
RESEND_API_KEY=re_AbCdEfGh_1234567890abcdefghijklmnopqr
​
EMAIL_FROM
string
Email address used as the sender for outgoing emailsRequirements: Must be a verified domain in ResendExample:
EMAIL_FROM=[email protected]

​
Redis Cache

​
UPSTASH_REDIS_REST_URL
string
Upstash Redis REST API URLWhere to get: https://console.upstash.com/redisExample:
# Upstash hosted
UPSTASH_REDIS_REST_URL=https://your-db-name.upstash.io

# Self-hosted Redis (Docker)
UPSTASH_REDIS_REST_URL=redis://redis:6379
​
UPSTASH_REDIS_REST_TOKEN
string
Upstash Redis REST API authentication tokenNote: Not required for self-hosted RedisExample:
UPSTASH_REDIS_REST_TOKEN=AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

​
AI Engine APIs

Configure AI service providers for content analysis:
​
OPENAI_API_KEY
string
OpenAI API key for GPT modelsWhere to get: https://platform.openai.com/api-keysExample:
OPENAI_API_KEY=sk-proj-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOP
​
PERPLEXITY_API_KEY
string
Perplexity AI API key for real-time search and analysisWhere to get: https://www.perplexity.ai/settings/apiExample:
PERPLEXITY_API_KEY=pplx-abcdefghijklmnopqrstuvwxyz1234567890
​
SERPER_API_KEY
string
Serper API key for Google Search integrationWhere to get: https://serper.dev/api-keyExample:
SERPER_API_KEY=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcd

​
File Uploads (Uploadthing)

​
UPLOADTHING_SECRET
string
Uploadthing secret key for server-side file operationsWhere to get: https://uploadthing.com/dashboardExample:
UPLOADTHING_SECRET=sk_live_abcdefghijklmnopqrstuvwxyz1234567890
​
UPLOADTHING_APP_ID
string
Uploadthing application IDExample:
UPLOADTHING_APP_ID=abcdefghij

​
Error Tracking (Sentry)

​
SENTRY_DSN
string
Sentry DSN for server-side error trackingWhere to get: https://sentry.io/settings/projects/Example:
SENTRY_DSN=https://[email protected]/1234567
​
NEXT_PUBLIC_SENTRY_DSN
string
Sentry DSN for client-side error trackingExample:
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/1234567

​
Feature Flags

​
ENABLE_CONTENT_SCORING
boolean
default:"true"
Enable or disable content scoring featuresExample:
ENABLE_CONTENT_SCORING=true
​
ENABLE_WEBHOOKS
boolean
default:"true"
Enable or disable webhook functionalityExample:
ENABLE_WEBHOOKS=true

​
Server Configuration

​
API_PORT
number
default:"4000"
Port number for the API serverExample:
API_PORT=4000
​
NODE_ENV
string
default:"development"
Node.js environment modePossible values: development, production, testExample:
NODE_ENV=production

​
Configuration Examples

​
Development Environment

.env
# Database
DATABASE_URL=postgresql://opensight:opensight@localhost:5432/opensight

# Authentication
JWT_SECRET=dev-secret-key-minimum-64-characters-replace-in-production-environment
JWT_REFRESH_SECRET=dev-refresh-secret-minimum-64-characters-replace-in-production

# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:4000
FRONTEND_URL=http://localhost:3000
API_PORT=4000

# Environment
NODE_ENV=development

# Redis (using Docker)
UPSTASH_REDIS_REST_URL=redis://localhost:6379

# Feature Flags
ENABLE_CONTENT_SCORING=true
ENABLE_WEBHOOKS=true

​
Production Environment (Docker)

.env
# Database (use Docker service name)
DATABASE_URL=postgresql://opensight:opensight@postgres:5432/opensight

# Authentication (use secure random values)
JWT_SECRET=<output-of-openssl-rand-hex-32>
JWT_REFRESH_SECRET=<output-of-openssl-rand-hex-32>

# Application URLs (replace with your domain)
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
FRONTEND_URL=https://app.yourdomain.com
API_PORT=4000

# Environment
NODE_ENV=production

# Redis (use Docker service name)
UPSTASH_REDIS_REST_URL=redis://redis:6379

# OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Stripe (production keys)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_STARTER_PRICE_ID=price_...
STRIPE_GROWTH_PRICE_ID=price_...

# Email
RESEND_API_KEY=re_...
EMAIL_FROM=[email protected]

# AI APIs
OPENAI_API_KEY=sk-proj-...
PERPLEXITY_API_KEY=pplx-...
SERPER_API_KEY=...

# File Uploads
UPLOADTHING_SECRET=sk_live_...
UPLOADTHING_APP_ID=...

# Error Tracking
SENTRY_DSN=https://[email protected]/...
NEXT_PUBLIC_SENTRY_DSN=https://[email protected]/...

# Feature Flags
ENABLE_CONTENT_SCORING=true
ENABLE_WEBHOOKS=true

​
Production Environment (Managed Services)

.env
# Database (managed PostgreSQL)
DATABASE_URL=postgresql://user:[email protected]:5432/opensight?sslmode=require

# Authentication
JWT_SECRET=<secure-random-string>
JWT_REFRESH_SECRET=<secure-random-string>

# Application URLs
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
FRONTEND_URL=https://app.yourdomain.com
API_PORT=4000

# Environment
NODE_ENV=production

# Redis (Upstash)
UPSTASH_REDIS_REST_URL=https://your-db-name.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

# (Include all other production variables from above)

​
Security Best Practices

Never commit your .env file to version control. The .env file is included in .gitignore by default.

Generate Secure Secrets

Use cryptographically secure random strings:
openssl rand -hex 32

Separate Environments

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

Rotate Secrets

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

Use Secrets Management

In production, use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.).

​
Validating Configuration

Verify your environment configuration: 
# Check required variables are set
node -e "require('dotenv').config(); const required = ['DATABASE_URL', 'JWT_SECRET', 'JWT_REFRESH_SECRET', 'NEXT_PUBLIC_APP_URL', 'NEXT_PUBLIC_API_URL']; required.forEach(v => { if (!process.env[v]) console.error('Missing:', v); });"

# Test database connection
npm run db:generate

# Test Redis connection (if using Upstash)
curl -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" $UPSTASH_REDIS_REST_URL/ping

​
Troubleshooting

Symptoms: API fails to start with database connection errorsSolutions:
  • Verify DATABASE_URL is correctly formatted
  • For Docker: Use service name (postgres) instead of localhost
  • Check PostgreSQL is running: docker compose ps postgres
  • Verify credentials match PostgreSQL configuration
Symptoms: Login fails or tokens are invalidSolutions:
  • Ensure JWT_SECRET and JWT_REFRESH_SECRET are set
  • Verify secrets are at least 64 characters
  • Check secrets are different from each other
  • Clear browser cookies and try again
Symptoms: OAuth redirect fails or shows errorSolutions:
  • Verify OAuth client IDs and secrets are correct
  • Check redirect URIs in OAuth provider settings
  • Ensure NEXT_PUBLIC_APP_URL matches OAuth configuration
  • For GitHub: Callback URL should be {NEXT_PUBLIC_APP_URL}/api/auth/callback/github
Symptoms: Caching fails or application is slowSolutions:
  • For Docker: Use redis://redis:6379 format
  • For Upstash: Verify both URL and token are set
  • Test connection: docker compose exec redis redis-cli ping
  • Check Redis is running: docker compose ps redis
Symptoms: Frontend shows network errorsSolutions:
  • Verify NEXT_PUBLIC_API_URL is publicly accessible
  • Check CORS settings in API server
  • Ensure FRONTEND_URL matches web application URL
  • For Docker: Verify port mappings are correct

​
Next Steps

Docker Deployment

Deploy OpenSight using Docker Compose

Self-Hosting Guide

Learn about self-hosting architecture and options

Build docs developers (and LLMs) love

Get started for freeTalk to us