Environment Variables

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

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

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

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

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

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

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:

string

GitHub OAuth application client IDWhere to get: https://github.com/settings/developersExample:

GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8

string

GitHub OAuth application client secretExample:

GITHUB_CLIENT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

string

Google OAuth 2.0 client IDWhere to get: https://console.cloud.google.com/apis/credentialsExample:

GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com

string

Google OAuth 2.0 client secretExample:

GOOGLE_CLIENT_SECRET=GOCSPX-abcdefghijklmnopqrstuvwxyz

Payment Processing (Stripe)

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

string

Stripe webhook signing secret for verifying webhook eventsWhere to get: https://dashboard.stripe.com/webhooksExample:

STRIPE_WEBHOOK_SECRET=whsec_abcdefghijklmnopqrstuvwxyz123456

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

string

Stripe Price ID for the Starter planWhere to get: https://dashboard.stripe.com/productsExample:

STRIPE_STARTER_PRICE_ID=price_1AbCdEfGhIjKlMnO

string

Stripe Price ID for the Growth planExample:

STRIPE_GROWTH_PRICE_ID=price_1PqRsTuVwXyZaBcD

Email Service (Resend)

string

Resend API key for sending transactional emailsWhere to get: https://resend.com/api-keysExample:

RESEND_API_KEY=re_AbCdEfGh_1234567890abcdefghijklmnopqr

string

Email address used as the sender for outgoing emailsRequirements: Must be a verified domain in ResendExample:

EMAIL_FROM=notifications@opensight.dev

Redis Cache

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

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:

string

OpenAI API key for GPT modelsWhere to get: https://platform.openai.com/api-keysExample:

OPENAI_API_KEY=sk-proj-abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOP

string

Perplexity AI API key for real-time search and analysisWhere to get: https://www.perplexity.ai/settings/apiExample:

PERPLEXITY_API_KEY=pplx-abcdefghijklmnopqrstuvwxyz1234567890

string

Serper API key for Google Search integrationWhere to get: https://serper.dev/api-keyExample:

SERPER_API_KEY=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcd

File Uploads (Uploadthing)

string

Uploadthing secret key for server-side file operationsWhere to get: https://uploadthing.com/dashboardExample:

UPLOADTHING_SECRET=sk_live_abcdefghijklmnopqrstuvwxyz1234567890

string

Uploadthing application IDExample:

UPLOADTHING_APP_ID=abcdefghij

Error Tracking (Sentry)

string

Sentry DSN for server-side error trackingWhere to get: https://sentry.io/settings/projects/Example:

SENTRY_DSN=https://1234567890abcdef@o123456.ingest.sentry.io/1234567

string

Sentry DSN for client-side error trackingExample:

NEXT_PUBLIC_SENTRY_DSN=https://1234567890abcdef@o123456.ingest.sentry.io/1234567

Feature Flags

boolean

default:"true"

Enable or disable content scoring featuresExample:

ENABLE_CONTENT_SCORING=true

boolean

default:"true"

Enable or disable webhook functionalityExample:

ENABLE_WEBHOOKS=true

Server Configuration

number

default:"4000"

Port number for the API serverExample:

API_PORT=4000

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=notifications@yourdomain.com

# 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://...@sentry.io/...
NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

# Feature Flags
ENABLE_CONTENT_SCORING=true
ENABLE_WEBHOOKS=true

Production Environment (Managed Services)

.env

# Database (managed PostgreSQL)
DATABASE_URL=postgresql://user:password@your-db-host.region.provider.com: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

Database connection failed

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

JWT authentication not working

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

Redis connection errors

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

API not accessible from frontend

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

Get Started

Core Features

Deployment

Platform

Environment Variables

Overview

Required Variables

Database

Authentication

Application URLs

Optional Variables

OAuth Authentication

Payment Processing (Stripe)

Email Service (Resend)

Redis Cache

AI Engine APIs

File Uploads (Uploadthing)

Error Tracking (Sentry)

Feature Flags

Server Configuration

Configuration Examples

Development Environment

Production Environment (Docker)

Production Environment (Managed Services)

Security Best Practices

Generate Secure Secrets

Separate Environments

Rotate Secrets

Use Secrets Management

Validating Configuration

Troubleshooting

Next Steps

Docker Deployment

Self-Hosting Guide

​Overview

​Required Variables

​Database

​Authentication

​Application URLs

​Optional Variables

​OAuth Authentication

​Payment Processing (Stripe)

​Email Service (Resend)

​Redis Cache

​AI Engine APIs

​File Uploads (Uploadthing)

​Error Tracking (Sentry)

​Feature Flags

​Server Configuration

​Configuration Examples

​Development Environment

​Production Environment (Docker)

​Production Environment (Managed Services)

​Security Best Practices

Generate Secure Secrets

Separate Environments

Rotate Secrets

Use Secrets Management

​Validating Configuration

​Troubleshooting

​Next Steps

Docker Deployment

Self-Hosting Guide

Overview

Required Variables

Database

Authentication

Application URLs

Optional Variables

OAuth Authentication

Payment Processing (Stripe)

Email Service (Resend)

Redis Cache

AI Engine APIs

File Uploads (Uploadthing)

Error Tracking (Sentry)

Feature Flags

Server Configuration

Configuration Examples

Development Environment

Production Environment (Docker)

Production Environment (Managed Services)

Security Best Practices

Validating Configuration

Troubleshooting

Next Steps