Eve library

Yemaya Environment Variables

Guide

Revision 1

On this page

This document describes all environment variables used by the Yemaya platform.

Table of Contents#


Core Configuration#

Variable Description Default Required
NODE_ENV Application environment development No
PORT Server port 3000 No
HOST Server host 0.0.0.0 No

NODE_ENV#

Determines the application environment. Valid values:

  • development - Local development with hot reload, debug logging
  • staging - Pre-production testing environment
  • production - Production environment with optimizations
  • test - Automated testing environment

Server Configuration#

Variable Description Default Required
PORT HTTP server port 3000 No
HOST HTTP server host binding 0.0.0.0 No
CORS_ORIGINS Comma-separated list of allowed CORS origins http://localhost:5173 No
TRUST_PROXY Trust proxy headers (for load balancers) false No

Example#

bash
PORT=3000
HOST=0.0.0.0
CORS_ORIGINS=https://app.yemaya.io,https://admin.yemaya.io
TRUST_PROXY=true

Database Configuration#

Variable Description Default Required
DATABASE_URL PostgreSQL connection string - Yes
DATABASE_URL_DIRECT Direct connection (bypassing PgBouncer) - No
DATABASE_POOL_MIN Minimum connection pool size 2 No
DATABASE_POOL_MAX Maximum connection pool size 10 No
DATABASE_CONNECTION_TIMEOUT_MS Connection timeout in ms 5000 No
DATABASE_IDLE_TIMEOUT_MS Idle connection timeout in ms 10000 No
DATABASE_SSL Enable SSL for database connection false No

Connection String Format#

text
postgresql://[user]:[password]@[host]:[port]/[database]?[options]

Example#

bash
# With PgBouncer
DATABASE_URL=postgresql://yemaya:password@pgbouncer:6432/yemaya?pgbouncer=true

# Direct connection (for migrations)
DATABASE_URL_DIRECT=postgresql://yemaya:password@postgres:5432/yemaya

Redis Configuration#

Variable Description Default Required
REDIS_URL Redis connection URL - No*
REDIS_HOST Redis host localhost No*
REDIS_PORT Redis port 6379 No
REDIS_PASSWORD Redis password - No
REDIS_DB Redis database number 0 No
REDIS_KEY_PREFIX Prefix for all Redis keys yemaya: No
REDIS_TLS Enable TLS for Redis connection false No

*Either REDIS_URL or REDIS_HOST should be provided.

Example#

bash
# Using URL
REDIS_URL=redis://:password@redis:6379/0

# Using individual settings
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_PASSWORD=secret
REDIS_DB=0

Storage Configuration#

MinIO/S3-compatible object storage configuration.

Variable Description Default Required
MINIO_ENDPOINT MinIO/S3 endpoint host localhost No
MINIO_PORT MinIO/S3 endpoint port 9000 No
MINIO_ACCESS_KEY Access key ID - Yes*
MINIO_SECRET_KEY Secret access key - Yes*
MINIO_USE_SSL Use HTTPS for connections false No
MINIO_PUBLIC_URL Public base URL for storage objects - No
MINIO_BUCKET Default bucket name yemaya No
MINIO_BUCKET_ASSETS Asset bucket name (overrides MINIO_BUCKET) - No
MINIO_REGION AWS region (for S3) us-east-1 No

*Required for production environments.

Example#

bash
# Local MinIO
MINIO_ENDPOINT=minio
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_USE_SSL=false
MINIO_PUBLIC_URL=http://localhost:9000/assets
MINIO_BUCKET_ASSETS=assets

# AWS S3
MINIO_ENDPOINT=s3.amazonaws.com
MINIO_PORT=443
MINIO_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
MINIO_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
MINIO_USE_SSL=true
MINIO_REGION=us-west-2

Authentication Configuration#

Variable Description Default Required
JWT_SECRET Secret for signing JWTs - Yes
JWT_EXPIRES_IN JWT expiration time 7d No
JWT_REFRESH_EXPIRES_IN Refresh token expiration 30d No
BCRYPT_ROUNDS Password hashing rounds 12 No
SESSION_SECRET Session encryption secret - No
OAUTH_REDIRECT_BASE_URL Base URL used to build OAuth redirect URIs - No
OAUTH_REDIRECT_ALLOWLIST Comma-separated allowlist of redirect origins - No

OAuth Providers#

Google OAuth#

Variable Description Required
OAUTH_GOOGLE_CLIENT_ID Google OAuth client ID No
OAUTH_GOOGLE_CLIENT_SECRET Google OAuth client secret No
OAUTH_GOOGLE_REDIRECT_URI Google OAuth redirect URI (optional) No

GitHub OAuth#

Variable Description Required
OAUTH_GITHUB_CLIENT_ID GitHub OAuth client ID No
OAUTH_GITHUB_CLIENT_SECRET GitHub OAuth client secret No
OAUTH_GITHUB_REDIRECT_URI GitHub OAuth redirect URI (optional) No

Discord OAuth#

Variable Description Required
OAUTH_DISCORD_CLIENT_ID Discord OAuth client ID No
OAUTH_DISCORD_CLIENT_SECRET Discord OAuth client secret No
OAUTH_DISCORD_REDIRECT_URI Discord OAuth redirect URI (optional) No

Apple OAuth#

Variable Description Required
OAUTH_APPLE_CLIENT_ID Apple OAuth client ID No
OAUTH_APPLE_TEAM_ID Apple team ID No
OAUTH_APPLE_KEY_ID Apple key ID No
OAUTH_APPLE_PRIVATE_KEY Apple private key (PEM, use \n for newlines) No
OAUTH_APPLE_PRIVATE_KEY_PATH Path to Apple private key file No
OAUTH_APPLE_REDIRECT_URI Apple OAuth redirect URI (optional) No

Security Notes#

  • JWT_SECRET must be at least 32 characters
  • Use openssl rand -base64 64 to generate a secure secret
  • Never use development secrets in production

AI Services Configuration#

Anthropic (Claude)#

Variable Description Default Required
ANTHROPIC_API_KEY Anthropic API key - No
ANTHROPIC_MODEL Default Claude model claude-3-5-sonnet-20241022 No
ANTHROPIC_MAX_TOKENS Max tokens per request 4096 No

OpenAI#

Variable Description Default Required
OPENAI_API_KEY OpenAI API key - No
OPENAI_MODEL Default OpenAI model gpt-4-turbo-preview No
OPENAI_MAX_TOKENS Max tokens per request 4096 No

Google AI (Gemini)#

Variable Description Default Required
GOOGLE_API_KEY Google AI API key - No
GOOGLE_MODEL Default Gemini model gemini-pro No

Ollama (Local)#

Variable Description Default Required
OLLAMA_URL Ollama server URL (enables local models) - No
OLLAMA_MODEL Default Ollama model llama3 No

Agent Runtime#

Variable Description Default Required
AGENT_TASK_CONCURRENCY Max concurrent agent tasks 2 No
AGENT_TASK_TIMEOUT_MS Default task timeout in ms 60000 No
AGENT_MESSAGE_HISTORY_LIMIT Max in-memory agent messages 1000 No

Email Configuration#

Variable Description Default Required
SMTP_HOST SMTP server host - No*
SMTP_PORT SMTP server port 587 No
SMTP_SECURE Use TLS false No
SMTP_USER SMTP username - No
SMTP_PASS SMTP password - No
SMTP_FROM Default sender email noreply@yemaya.io No

*Required if email functionality is needed.

Example#

bash
# Development (Mailpit)
SMTP_HOST=mailpit
SMTP_PORT=1025

# Production (SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_SECURE=true
SMTP_USER=apikey
SMTP_PASS=SG.xxxxx
SMTP_FROM=noreply@yemaya.io

Logging Configuration#

Variable Description Default Required
LOG_LEVEL Minimum log level info No
LOG_PRETTY Pretty print logs (dev) false* No
LOG_REDACT Comma-separated keys to redact password,token,secret,apiKey No

*Automatically true in development.

Log Levels (in order of severity)#

  1. fatal - Application crashes
  2. error - Error conditions
  3. warn - Warning conditions
  4. info - Informational messages
  5. debug - Debug messages
  6. trace - Trace-level debugging

Worker Configuration#

Background worker specific settings.

Variable Description Default Required
WORKER_TYPE Type of worker to run all No
WORKER_CONCURRENCY Jobs processed concurrently 5 No
WORKER_JOB_TIMEOUT_MS Job timeout in ms 300000 No
WORKER_STALLED_INTERVAL Stalled job check interval 30000 No
WORKER_MAX_STALLED_COUNT Max stalled count before fail 3 No

Worker Types#

  • all - Run all worker types
  • agent - AI agent task processing
  • media - Media transcoding and processing
  • asset - Asset optimization
  • notification - Email and notifications

Feature Flags#

Variable Description Default Required
ENABLE_DEBUG Enable debug mode false No
ENABLE_METRICS Enable Prometheus metrics false No
ENABLE_TRACING Enable OpenTelemetry tracing false No
DISABLE_EXTERNAL_AI Disable external AI calls false No
DISABLE_EXTERNAL_WEBHOOKS Disable webhook delivery false No

Environment-Specific Settings#

Development#

bash
NODE_ENV=development
LOG_LEVEL=debug
LOG_PRETTY=true
DATABASE_URL=postgresql://yemaya:yemaya_dev_password@localhost:5432/yemaya
REDIS_HOST=localhost
JWT_SECRET=development-secret-change-in-production-32chars

Staging#

bash
NODE_ENV=staging
LOG_LEVEL=debug
DATABASE_URL=postgresql://yemaya:${POSTGRES_PASSWORD}@postgres:5432/yemaya
REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379
JWT_SECRET=${JWT_SECRET}
SENTRY_DSN=${SENTRY_DSN}

Production#

bash
NODE_ENV=production
LOG_LEVEL=info
LOG_PRETTY=false
DATABASE_URL=postgresql://yemaya:${POSTGRES_PASSWORD}@postgres:5432/yemaya
REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379
JWT_SECRET=${JWT_SECRET}
SENTRY_DSN=${SENTRY_DSN}
ENABLE_METRICS=true
TRUST_PROXY=true

Validation#

Run the environment validation script to check your configuration:

bash
# Validate current environment
pnpm validate:env

# Validate specific environment
NODE_ENV=production pnpm validate:env

Security Best Practices#

  1. Never commit secrets - Use .env.local files (git-ignored) for secrets
  2. Use strong secrets - Generate with openssl rand -base64 64
  3. Rotate secrets regularly - At least every 90 days for production
  4. Validate on startup - Use pnpm validate:env before deployment
  5. Redact in logs - Ensure LOG_REDACT includes all sensitive keys
  6. Use secret managers - Consider Vault or AWS Secrets Manager for production