Environment Setup

Complete guide to configuring environment variables and API integrations for JOIP

Environment File Setup

JOIP uses environment variables for configuration. All variables are loaded from a .env file in the project root.

1. Create Environment File

   cp .env.example .env
   
2. Edit Configuration

   Open .env in your editor and configure the required variables below.

3. Restart Server

   npm run dev
   

   Changes to .env require a server restart.

Never commit .env files to version control. The .gitignore file should already exclude them.

Core Configuration

Database Connection

DATABASE_URL · string · required

PostgreSQL connection string in URI format.

DATABASE_URL="postgresql://username:password@host:5432/database"

Examples:

• Local: postgresql://postgres:password@localhost:5432/joip_dev
• Supabase: postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres
• Neon: postgresql://[user]:[password]@[host].neon.tech/[database]

For production, enable SSL by appending ?sslmode=require to the connection string.

Session Management

SESSION_SECRET · string · required

Secret key for signing session cookies. Must be a strong random string.

SESSION_SECRET="your_session_secret_key"

Generate securely:

openssl rand -hex 32

Use a different secret for development and production. Changing this will invalidate all existing sessions.

Application Settings

NODE_ENV · string · default: "development"

Application environment mode.

NODE_ENV="development"  # or "production"

Effects:

• development: Enables Vite HMR, verbose logging, local auth
• production: Serves from dist/, minified assets, Replit OIDC

PORT · number · default: 5000

Server port number.

PORT=5000

Replit automatically proxies this port. The default is always 5000.

JOIP_INTERNAL_PORT · number

Optional override for internal localhost callbacks/proxy calls.

# JOIP_INTERNAL_PORT=5000

Defaults to PORT when omitted. Only needed for special reverse proxy setups.

UPLOAD_DIR · string · default: "./uploads"

Directory for temporary file uploads.

UPLOAD_DIR="./uploads"

Deprecated: JOIP now uses Supabase Storage exclusively. This setting is retained for backward compatibility but not actively used.

Reddit Integration

Required for Reddit-based sessions, Gaslighter, and Scroller features.

REDDIT_CLIENT_ID · string · required

Reddit application client ID.

REDDIT_CLIENT_ID="your_reddit_client_id"

How to get:

1. Go to https://www.reddit.com/prefs/apps
2. Click “Create App” or “Create Another App”
3. Choose “script” type
4. The client ID is shown under the app name

REDDIT_CLIENT_SECRET · string · required

Reddit application client secret.

REDDIT_CLIENT_SECRET="your_reddit_client_secret"

Found in the same location as the client ID.

AI Services

Caption Generation

Choose one or both providers for AI caption generation:

OPENROUTER_API_KEY · string

OpenRouter API key for AI caption generation (recommended).

OPENROUTER_API_KEY="sk-or-v1-your_openrouter_api_key"

Features:

• Access to Gemini 2.5 Pro and Flash models
• Automatic fallback between models
• Used for contextual/narrative captions in Manual Editor
• Used for Smart Captions with themed prompts

Get your key:

1. Sign up at https://openrouter.ai
2. Navigate to Settings → API Keys
3. Create a new key

Models used:

• Manual Editor: google/gemini-2.5-pro (fallback: gemini-2.5-flash-lite)
• Smart Captions: gemini-2.5-flash-lite

OPENAI_API_KEY · string

OpenAI API key as alternative to OpenRouter.

OPENAI_API_KEY="sk-your_openai_api_key"

The system will use OpenRouter if available, falling back to OpenAI.

AI Image Services

XAI_API_KEY · string

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

XAI_API_KEY="xai-your_xai_api_key"

Get your key:

• Visit https://console.x.ai/
• Generate an API key

Model:

• Uses grok-imagine-image-pro by default
• Override with XAI_UNDRESS_MODEL

XAI_UNDRESS_MODEL · string · default: "grok-imagine-image-pro"

Optional xAI model override for AI Undress.

XAI_UNDRESS_MODEL="grok-imagine-image-pro"

FREEPIK_API_KEY · string

Freepik API key for AI Undress feature (fallback provider).

FREEPIK_API_KEY="your_freepik_api_key"

Get your key:

• Visit https://www.freepik.com/developers/dashboard
• Create an API key

Model:

• Uses Seedream 4.5 Edit
• Automatically used when xAI fails or is unavailable

UNDRESS_PRIMARY_PROVIDER · string · default: "xai"

Select primary provider for AI Undress.

UNDRESS_PRIMARY_PROVIDER="xai"  # or "freepik"

Options:

• xai: Use xAI as primary, Freepik as fallback
• freepik: Use Freepik as primary, xAI as fallback

REPLICATE_API_TOKEN · string

Replicate API token (dormant/legacy provider).

REPLICATE_API_TOKEN="r8_your_replicate_api_token"

This provider is dormant and kept for backward compatibility. The system uses xAI and Freepik.

Cloud Storage

Required for manual sessions, Media Vault, and file uploads.

SUPABASE_URL · string · required

Supabase project URL.

SUPABASE_URL="https://your-project.supabase.co"

Get from:

1. Supabase Dashboard
2. Select your project
3. Settings → API → Project URL

SUPABASE_ANON_KEY · string · required

Supabase anonymous (public) key.

SUPABASE_ANON_KEY="your_supabase_anon_key"

Found in the same location as the project URL under “Project API keys” → “anon public”.

This key is safe to use in client-side code. It respects Row Level Security (RLS) policies.

SUPABASE_SERVICE_KEY · string · required

Supabase service role (admin) key.

SUPABASE_SERVICE_KEY="your_supabase_service_key"

Found under “Project API keys” → “service_role”.

Never expose this key client-side. It bypasses all RLS policies and has full admin access.

Storage Buckets

The application automatically creates these buckets:

• user-media: User uploads and manual session media
  • Path structure: users/{userId}/manual-sessions/{sessionId}/
• general: Community content and shared media

Test storage connectivity with:

curl http://localhost:5000/api/storage/status

External Services

Imgchest Integration

IMGCHEST_API_KEY · string

Imgchest API key for importing existing galleries.

IMGCHEST_API_KEY="your_imgchest_api_key"

Required only for the “Import JOIP” feature to import from Imgchest.

Replit Deployment

These variables are automatically set by Replit. Only configure manually for custom deployments.

REPLIT_DOMAINS · string

Replit domain for the deployed app.

REPLIT_DOMAINS="your-repl-domain.replit.dev"

Effects:

• When set: Enables Replit OIDC authentication
• When unset: Uses local development auth strategy

REPL_ID · string

Unique Replit project identifier.

REPL_ID="your_repl_id"

Used for Replit OIDC configuration.

ISSUER_URL · string · default: "https://identity.util.repl.co"

OIDC issuer URL for Replit authentication.

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

REPLIT_DEV_DOMAIN · string

Development domain (auto-populated by Replit).

# REPLIT_DEV_DOMAIN="your-dev-domain.replit.dev"

REPLIT_DB_URL · string

Replit database URL (auto-populated).

# REPLIT_DB_URL="your-replit-db-url"

Payment Integrations

Telegram Payments

TELEGRAM_BOT_TOKEN · string

Telegram bot token for Telegram Stars payments.

TELEGRAM_BOT_TOKEN="your_telegram_bot_token"

Required together with TELEGRAM_WEBHOOK_SECRET to enable Telegram payment flow.

TELEGRAM_WEBHOOK_SECRET · string

Telegram webhook secret for payment verification.

TELEGRAM_WEBHOOK_SECRET="your_telegram_webhook_secret"

TELEGRAM_BOT_USERNAME · string · default: "OfficialJoipBot"

Telegram bot username.

TELEGRAM_BOT_USERNAME="OfficialJoipBot"

Defaults to “OfficialJoipBot” when unset.

TELEGRAM_CHANNEL_ID · string

Telegram channel ID for membership features.

TELEGRAM_CHANNEL_ID="-1001234567890"

Only needed for channel invite/membership features.

Thirdweb Checkout

THIRDWEB_CLIENT_ID · string

Thirdweb client ID for crypto/card payments.

THIRDWEB_CLIENT_ID="your_thirdweb_client_id"

Required together with webhook secret to enable Thirdweb checkout flow.

THIRDWEB_WEBHOOK_SECRET · string

Thirdweb webhook secret for payment verification.

THIRDWEB_WEBHOOK_SECRET="your_thirdweb_webhook_secret"

THIRDWEB_SELLER_WALLET · string

Ethereum wallet address for receiving payments.

THIRDWEB_SELLER_WALLET="0xyour_seller_wallet_address"

Database Tuning

Optional connection pool and performance settings.

Connection Pool

# Maximum pool size
DB_POOL_MAX=20

# Minimum pool size  
DB_POOL_MIN=2

# Idle timeout in milliseconds
DB_POOL_IDLE=10000

# Connection timeout in seconds
DB_CONNECT_TIMEOUT=10

# Max connection lifetime in seconds
DB_MAX_LIFETIME=3600

These are optional. The application uses sensible defaults optimized for most deployments.

Logging Configuration

LOG_LEVEL · string · default: "info"

Application logging verbosity.

LOG_LEVEL="info"

Options:

• error: Only errors
• warn: Warnings and errors
• info: General information (recommended)
• debug: Detailed debugging information

Complete Example

Development (.env)

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/joip_dev"

# Session
SESSION_SECRET="generated-secure-random-string-here"

# Application
NODE_ENV="development"
PORT=5000

# Reddit
REDDIT_CLIENT_ID="your_reddit_client_id"
REDDIT_CLIENT_SECRET="your_reddit_client_secret"

# AI - Caption Generation
OPENROUTER_API_KEY="sk-or-v1-your_openrouter_key"

# AI - Image Services
XAI_API_KEY="xai-your_key"
FREEPIK_API_KEY="your_freepik_key"
UNDRESS_PRIMARY_PROVIDER="xai"

# Cloud Storage
SUPABASE_URL="https://yourproject.supabase.co"
SUPABASE_ANON_KEY="your_anon_key"
SUPABASE_SERVICE_KEY="your_service_key"

# Optional
IMGCHEST_API_KEY="your_imgchest_key"

Validation

The application validates environment configuration on startup via server/environmentConfig.ts.

Startup checks:

• Required variables are present
• Database connection succeeds
• Connection pool initializes
• Supabase connectivity (if configured)

Validation errors:

✗ DATABASE_URL must be set
✗ SESSION_SECRET must be set
✗ Supabase configuration incomplete

Diagnostics

Check Storage Status

curl http://localhost:5000/api/storage/status

Response:

{
  "configured": true,
  "reachable": true,
  "buckets": ["user-media", "general"],
  "testPassed": true
}

Error codes:

• STORAGE_CONFIG_ERROR: Missing environment variables
• STORAGE_UNREACHABLE: Cannot connect to Supabase
• STORAGE_PREFLIGHT_FAILED: Bucket test upload failed

Check Database Connection

Verify the database is accessible:

psql "$DATABASE_URL" -c "SELECT version();"

Test API Keys

Test Reddit API

Create a Reddit session and verify media loads. Check server logs for:

✓ Reddit API request successful
✓ Fetched 100 posts from r/subreddit

Test AI Caption Generation

Try generating a caption in Smart Captions. Look for:

✓ OpenRouter request successful
✓ Generated caption with gemini-2.5-flash-lite

Test Supabase Storage

Upload an image in Media Vault. Verify:

✓ File uploaded to user-media bucket
✓ Public URL generated

Security Best Practices

1. Secret Management

   • Never commit .env files to Git
   • Use different secrets for dev/staging/production
   • Rotate API keys regularly (quarterly recommended)
   • Store production secrets in secure vaults (Replit Secrets, AWS Secrets Manager)
2. API Key Security

   • Never expose service keys client-side
   • Use SUPABASE_ANON_KEY for client operations only
   • Keep SUPABASE_SERVICE_KEY server-side only
   • Monitor API usage for anomalies
3. Database Security

   • Use SSL for production database connections
   • Implement IP whitelisting where possible
   • Use strong passwords (20+ characters)
   • Enable connection pooling with max limits
4. Session Security

   • Use strong SESSION_SECRET (32+ bytes)
   • Enable secure cookies in production (HTTPS only)
   • Set appropriate session timeouts
   • Implement CSRF protection

Troubleshooting

Storage Errors in Manual Sessions

Symptom: Manual session creation returns 503 with error codes

Solutions:

1. Verify all three Supabase variables are set
2. Check if Supabase project is paused (resume it)
3. Test with /api/storage/status
4. Review error code:
   • STORAGE_CONFIG_ERROR: Add missing env vars
   • STORAGE_UNREACHABLE: Check URL and network
   • STORAGE_PREFLIGHT_FAILED: Verify bucket permissions

AI Features Not Working

Symptom: Caption generation fails silently

Solutions:

1. Check API keys are valid (not expired)
2. Verify sufficient credits/quota on provider
3. Check server logs for specific errors
4. Test fallback: if OpenRouter fails, try OpenAI

Reddit API Rate Limiting

Symptom: 429 errors when fetching Reddit content

Solutions:

1. Built-in retry logic should handle this automatically
2. Reduce concurrent requests
3. Check if Reddit credentials are valid
4. Wait for rate limit to reset (typically 1 minute)

Database Connection Issues

Symptom: Cannot connect to database

Solutions:

1. Verify DATABASE_URL format is correct
2. Check database is running and accessible
3. For cloud databases: verify IP whitelist
4. Test connection: psql "$DATABASE_URL"
5. Check connection pool settings if hitting limits

Next Steps

Quick Start Guide

Create your first session with AI captions

API Reference

Explore all available API endpoints