Environment Variables

Overview

JOIP Web Application requires various environment variables for database connections, API integrations, authentication, and feature configuration. This page provides a comprehensive reference for all supported variables.

On Replit, configure all environment variables in the Secrets tab (Tools → Secrets). Never commit secrets to version control.

Required Variables

These variables are essential for the application to function:

Database Configuration

string

required

PostgreSQL connection string in standard format.Format: postgresql://username:password@host:port/databaseExample:

DATABASE_URL="postgresql://joip_user:secure_password@ep-cool-name.us-east-2.aws.neon.tech/joip_production?sslmode=require"

Neon Example:

DATABASE_URL="postgresql://joip_user:abc123xyz@ep-cool-name-123456.us-east-2.aws.neon.tech/neondb?sslmode=require"

Ensure SSL mode is enabled (?sslmode=require) for production databases.

Session Security

string

required

Secret key for signing session cookies. Must be cryptographically secure.Recommended: 32+ random charactersExample:

SESSION_SECRET="a7f9c2e8b4d1f6e3a9c5b8d2f7e4a1c6b9e2f5a8d3c7b1e4f9a2c5d8e1b4f7a3"

Generate secure secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Supabase Storage

string

required

Your Supabase project URL.Format: https://[project-id].supabase.coExample:

SUPABASE_URL="https://xyzabcdefg123456.supabase.co"

Find this in your Supabase project settings under “API”.

string

required

Supabase anonymous (public) API key for client-side operations.Example:

SUPABASE_ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Find this in Supabase project settings under “API” → “Project API keys”.

string

required

Supabase service role key for server-side storage operations.Example:

SUPABASE_SERVICE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Keep this secret! Service key has full access to your Supabase project. Never expose in client code.

Reddit API Integration

string

required

Reddit application client ID for content fetching.Example:

REDDIT_CLIENT_ID="AbCdEf123456"

Obtain from: https://www.reddit.com/prefs/apps

string

required

Reddit application client secret.Example:

REDDIT_CLIENT_SECRET="xYz789-AbC123_dEf456"

Create a “script” type application on Reddit for server-side API access.

Replit OIDC Authentication

Required for production deployment on Replit:

string

Comma-separated list of domains where your Repl is accessible.Example (single domain):

REPLIT_DOMAINS="joip-production.replit.app"

Example (multiple domains):

REPLIT_DOMAINS="app.joip.io,joip-production.replit.app,joip-backup.replit.app"

Behavior:

Application prioritizes app.joip.io if present
Falls back to first domain in list
Used for OAuth callback URL generation
Enables Replit OIDC authentication when set

string

Your Replit project ID (automatically populated by Replit).Example:

REPL_ID="abc123-xyz789-def456"

Required for Replit OIDC authentication in production.

string

Replit OIDC issuer URL (standard value).Value:

ISSUER_URL="https://identity.util.repl.co"

This value is consistent across all Replit deployments.

AI Providers

Caption Generation

At least one AI provider is required for caption generation:

string

OpenRouter API key for AI caption generation (primary provider).Example:

OPENROUTER_API_KEY="sk-or-v1-abc123xyz789..."

Models used:

Manual Editor: google/gemini-2.5-pro (contextual captions)
Fallback: google/gemini-2.5-flash-lite
Smart Captions: gemini-2.5-flash-lite

Obtain from: https://openrouter.ai/

string

OpenAI API key (alternative to OpenRouter).Example:

OPENAI_API_KEY="sk-abc123xyz789..."

Falls back to this provider if OpenRouter fails.

AI Undress (Image Editing)

string

xAI API key (primary provider for AI Undress feature).Example:

XAI_API_KEY="xai-abc123xyz789..."

Model used: grok-imagine-image-pro (via /v1/images/edits)

string

Freepik API key (fallback provider for AI Undress).Example:

FREEPIK_API_KEY="fpk_abc123xyz789..."

Model used: Seedream 4.5 Edit

enum

default:"xai"

Primary AI Undress provider selection.Options: xai | freepikExample:

UNDRESS_PRIMARY_PROVIDER="xai"

Defaults to xai if not specified.

string

default:"grok-imagine-image-pro"

Optional xAI model override for AI Undress.Example:

XAI_UNDRESS_MODEL="grok-imagine-image-pro"

string

Replicate API token (dormant/legacy backend for AI Undress).Example:

REPLICATE_API_TOKEN="r8_abc123xyz789..."

This credential is currently not used in active AI Undress flows.

Optional Features

Imgchest Import

string

Imgchest API key for importing existing JOIP galleries.Example:

IMGCHEST_API_KEY="imgchest_abc123xyz789"

Required for “Import JOIP from Imgchest” feature.

Payment Providers

PayGate (Credit Cards)

string

PayGate merchant wallet address for credit card payments.Example:

PAYGATE_MERCHANT_WALLET="0xABC123..."

string

PayGate callback URL for payment notifications.Example (local dev with ngrok):

PAYGATE_CALLBACK_URL="https://abc123.ngrok.io/api/payments/callback"

Production: Auto-detected from REPLIT_DOMAINS

Telegram Stars

string

Telegram bot token for Telegram Star payments.Example:

TELEGRAM_BOT_TOKEN="123456:ABC-DEF123456..."

Obtain from: https://t.me/BotFather

string

Secret for verifying Telegram webhook signatures.Example:

TELEGRAM_WEBHOOK_SECRET="your_secure_random_string"

Required in production when TELEGRAM_BOT_TOKEN is set.

string

default:"OfficialJoipBot"

Telegram bot username (without @).Example:

TELEGRAM_BOT_USERNAME="OfficialJoipBot"

string

Telegram channel ID for membership features.Example:

TELEGRAM_CHANNEL_ID="-1001234567890"

Thirdweb (Crypto Checkout)

string

Thirdweb client ID for crypto checkout.Example:

THIRDWEB_CLIENT_ID="abc123xyz789"

string

Secret for verifying Thirdweb webhook signatures.Example:

THIRDWEB_WEBHOOK_SECRET="whsec_abc123xyz789"

string

EVM wallet address for receiving Thirdweb payments.Format: Must be valid EVM address (0x…)Example:

THIRDWEB_SELLER_WALLET="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

Must be a valid 40-character hexadecimal EVM address.

Payblis

string

Payblis merchant key.Example:

PAYBLIS_MERCHANT_KEY="merchant_abc123"

string

Payblis secret key for API authentication.Example:

PAYBLIS_SECRET_KEY="sk_abc123xyz789"

boolean

default:"auto"

Enable Payblis sandbox mode.Values: true | falseExample:

PAYBLIS_SANDBOX="false"

Defaults to true in development, false in production.

Application Settings

enum

default:"development"

Node.js environment mode.Options: development | productionExample:

NODE_ENV="production"

Behavior:

development: Enables detailed error messages, Vite HMR
production: Optimized builds, minimal logging

number

default:"5000"

Server listening port.Example:

PORT=5000

Always use port 5000 on Replit. Changing this may break deployment.

number

Optional override for internal localhost callbacks/proxy calls.Example:

JOIP_INTERNAL_PORT=5000

Defaults to PORT when omitted.

string

default:"./uploads"

Local directory for file uploads (legacy).Example:

UPLOAD_DIR="./uploads"

All uploads now use Supabase Storage. This setting is mostly unused.

string

Explicit host URL override.Example:

HOST_URL="https://app.joip.io"

Auto-detected from REPLIT_DOMAINS in production.

Database Connection Tuning

Optional settings for optimizing PostgreSQL connection pooling:

number

default:"20"

Maximum number of database connections in pool.Example:

DB_POOL_MAX=20

number

default:"2"

Minimum number of database connections in pool.Example:

DB_POOL_MIN=2

number

default:"10000"

Idle timeout in milliseconds before closing connection.Example:

DB_POOL_IDLE=10000

number

default:"10"

Connection timeout in seconds.Example:

DB_CONNECT_TIMEOUT=10

number

default:"3600"

Maximum connection lifetime in seconds.Example:

DB_MAX_LIFETIME=3600

number

default:"30000"

Statement timeout in milliseconds.Example:

DB_STATEMENT_TIMEOUT=30000

number

default:"20000"

Query timeout in milliseconds.Example:

DB_QUERY_TIMEOUT=20000

Logging Configuration

enum

default:"info"

Application logging level.Options: error | warn | info | debugExample:

LOG_LEVEL="info"

Levels:

error: Only critical errors
warn: Errors and warnings
info: Normal operation info (recommended for production)
debug: Detailed debugging information

Environment Validation

The application validates all environment variables on startup (server/environmentConfig.ts:89):

export function validateEnvironmentSetup() {
  const errors: string[] = [];
  const warnings: string[] = [];

  // Required variables
  if (!process.env.DATABASE_URL) {
    errors.push('DATABASE_URL is required');
  }

  if (!process.env.SUPABASE_URL) {
    errors.push('SUPABASE_URL is required');
  }

  // ... additional validation
}

Startup Behavior:

Errors: Application may fail to start or have limited functionality
Warnings: Application starts but some features are disabled

Check console logs on startup for validation results.

Configuration Examples

# Required
DATABASE_URL="postgresql://user:pass@host.neon.tech/db?sslmode=require"
SESSION_SECRET="a7f9c2e8b4d1f6e3a9c5b8d2f7e4a1c6"
SUPABASE_URL="https://xyz123.supabase.co"
SUPABASE_ANON_KEY="eyJhbGciOi..."
SUPABASE_SERVICE_KEY="eyJhbGciOi..."
REDDIT_CLIENT_ID="AbCdEf123"
REDDIT_CLIENT_SECRET="xYz789-AbC123"

# Replit OIDC
REPLIT_DOMAINS="app.joip.io,joip.replit.app"
REPL_ID="abc123-xyz789"
ISSUER_URL="https://identity.util.repl.co"

# AI Providers
OPENROUTER_API_KEY="sk-or-v1-..."
XAI_API_KEY="xai-..."
FREEPIK_API_KEY="fpk-..."

# Application
NODE_ENV="production"
PORT=5000

# Required
DATABASE_URL="postgresql://localhost:5432/joip_dev"
SESSION_SECRET="dev-secret-change-in-production"
SUPABASE_URL="https://xyz123.supabase.co"
SUPABASE_ANON_KEY="eyJhbGciOi..."
SUPABASE_SERVICE_KEY="eyJhbGciOi..."
REDDIT_CLIENT_ID="AbCdEf123"
REDDIT_CLIENT_SECRET="xYz789-AbC123"

# AI Providers (optional for testing)
OPENROUTER_API_KEY="sk-or-v1-..."

# Application
NODE_ENV="development"
PORT=5000

# No REPLIT_DOMAINS - uses local auth

# Bare minimum for testing
DATABASE_URL="postgresql://localhost:5432/joip_test"
SESSION_SECRET="test-secret"
SUPABASE_URL="https://xyz123.supabase.co"
SUPABASE_ANON_KEY="eyJhbGciOi..."
SUPABASE_SERVICE_KEY="eyJhbGciOi..."
REDDIT_CLIENT_ID="test"
REDDIT_CLIENT_SECRET="test"

# Warnings expected for missing optional features

Security Best Practices

Critical Security Rules:

Never commit .env files to Git
Use Replit Secrets for all sensitive values
Rotate secrets periodically (every 90 days)
Use different secrets for dev/staging/prod
Audit access to Replit Secrets regularly

Secret Generation

Generate cryptographically secure secrets:

# Session secret (32 bytes)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Webhook secret (16 bytes)
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

# UUID v4
node -e "console.log(require('crypto').randomUUID())"

Environment Files

Never track environment files in Git:

# .gitignore
.env
.env.local
.env.production
.env.development
*.env

Troubleshooting

Missing Required Variables

Symptom: Application fails to start with validation errors Solution:

Check startup logs for specific missing variables
Add all required variables to Replit Secrets
Restart the application

Invalid Variable Format

Symptom: “Invalid format” warnings on startup Solution:

Verify variable format matches documentation
Check for extra spaces or quotes
Validate URLs include protocol (https://)

Features Not Working

Symptom: Specific features disabled or failing Solution:

Check for related warnings in startup logs
Verify optional variables are set correctly
Test connectivity to external services

Next Steps

Deploy on Replit

Complete Replit deployment guide

Database Setup

Configure PostgreSQL and Neon

Storage Configuration

Setup Supabase Storage

Deployment

Development

Integrations

Overview

Required Variables

Database Configuration

Session Security

Supabase Storage

Reddit API Integration

Replit OIDC Authentication

AI Providers

Caption Generation

AI Undress (Image Editing)

Optional Features

Imgchest Import

Payment Providers

PayGate (Credit Cards)

Telegram Stars

Thirdweb (Crypto Checkout)

Payblis

Application Settings

Database Connection Tuning

Logging Configuration

Environment Validation

Configuration Examples

Security Best Practices

Secret Generation

Environment Files

Troubleshooting

Missing Required Variables

Invalid Variable Format

Features Not Working

Next Steps

Deploy on Replit

Database Setup

Storage Configuration

​Overview

​Required Variables

​Database Configuration

​Session Security

​Supabase Storage

​Reddit API Integration

​Replit OIDC Authentication

​AI Providers

​Caption Generation

​AI Undress (Image Editing)

​Optional Features

​Imgchest Import

​Payment Providers

​PayGate (Credit Cards)

​Telegram Stars

​Thirdweb (Crypto Checkout)

​Payblis

​Application Settings

​Database Connection Tuning

​Logging Configuration

​Environment Validation

​Configuration Examples

​Security Best Practices

​Secret Generation

​Environment Files

​Troubleshooting

​Missing Required Variables

​Invalid Variable Format

​Features Not Working

​Next Steps

Deploy on Replit

Database Setup

Storage Configuration

Overview

Required Variables

Database Configuration

Session Security

Supabase Storage

Reddit API Integration

Replit OIDC Authentication

AI Providers

Caption Generation

AI Undress (Image Editing)

Optional Features

Imgchest Import

Payment Providers

PayGate (Credit Cards)

Telegram Stars

Thirdweb (Crypto Checkout)

Payblis

Application Settings

Database Connection Tuning

Logging Configuration

Environment Validation

Configuration Examples

Security Best Practices

Secret Generation

Environment Files

Troubleshooting

Missing Required Variables

Invalid Variable Format

Features Not Working

Next Steps