This document describes all environment variables used by the Yemaya platform.
Table of Contents#
- Core Configuration
- Server Configuration
- Database Configuration
- Redis Configuration
- Storage Configuration
- Authentication Configuration
- AI Services Configuration
- Email Configuration
- Logging Configuration
- Worker Configuration
- Feature Flags
- Environment-Specific Settings
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 loggingstaging- Pre-production testing environmentproduction- Production environment with optimizationstest- 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_SECRETmust be at least 32 characters- Use
openssl rand -base64 64to 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)#
fatal- Application crasheserror- Error conditionswarn- Warning conditionsinfo- Informational messagesdebug- Debug messagestrace- 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 typesagent- AI agent task processingmedia- Media transcoding and processingasset- Asset optimizationnotification- 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#
- Never commit secrets - Use
.env.localfiles (git-ignored) for secrets - Use strong secrets - Generate with
openssl rand -base64 64 - Rotate secrets regularly - At least every 90 days for production
- Validate on startup - Use
pnpm validate:envbefore deployment - Redact in logs - Ensure
LOG_REDACTincludes all sensitive keys - Use secret managers - Consider Vault or AWS Secrets Manager for production