Eve library

Environment Variables Reference

Guide

Revision 1

On this page

Complete reference for all environment variables used in the Lilith platform.

Quick Start#

  1. Copy .env.example to .env in the project root
  2. Update values for your environment
  3. Never commit .env to version control
bash
cp .env.example .env

Variable Categories#


Core Settings#

Variable Description Default Required
NODE_ENV Environment mode development Yes

Authentication & Security#

Variable Description Default Required
JWT_SECRET Secret key for signing JWT access tokens dev-secret-key Yes
JWT_REFRESH_SECRET Secret key for signing refresh tokens dev-refresh-secret Yes
PASSWORD_SALT Salt for password hashing dev-salt Yes

Security Notes#

  • Production: Generate cryptographically secure random values (minimum 32 bytes)
  • Use openssl rand -base64 32 to generate secure secrets
  • Rotate secrets periodically and after any suspected compromise

AI/LLM Provider API Keys#

Variable Description Default Required
OPENAI_API_KEY OpenAI API key for GPT models sk-test-key For AI features
ANTHROPIC_API_KEY Anthropic API key for Claude models sk-ant-test-key For AI features
OPENROUTER_API_KEY OpenRouter API key for multi-model routing - Optional
ELEVENLABS_API_KEY ElevenLabs API key for text-to-speech - For TTS features

Getting API Keys#


AWS Configuration#

Variable Description Default Required
AWS_ACCESS_KEY_ID AWS access key ID dev-key For AWS services
AWS_SECRET_ACCESS_KEY AWS secret access key dev-secret For AWS services
AWS_REGION Default AWS region us-east-1 For AWS services
S3_BUCKET S3 bucket for media storage lilith-dev-media For media
S3_REGION S3 bucket region us-east-1 For media
CDN_BASE_URL Base URL for CDN/media delivery http://localhost:3005 For media

Local Development#

For local development, MinIO provides S3-compatible storage:

  • Endpoint: minio:9000 (inside Docker) or localhost:9000 (host)
  • Access Key: minioadmin
  • Secret Key: minioadmin

Email Configuration#

Variable Description Default Required
EMAIL_PROVIDER Email service provider (sendgrid, ses, postmark) sendgrid For email
SENDGRID_API_KEY SendGrid API key sg-test-key If using SendGrid
PUSH_SERVICE_URL Push notification service URL http://localhost:3006 For push

Database Configuration#

PostgreSQL#

Variable Description Default Required
POSTGRES_HOST PostgreSQL host postgres Yes
POSTGRES_PORT PostgreSQL port 5432 Yes
POSTGRES_DB PostgreSQL database name lilith_dev Yes
POSTGRES_USER PostgreSQL username lilith Yes
POSTGRES_PASSWORD PostgreSQL password dev_password Yes

Redis#

Basic Configuration#

Variable Description Default Required
REDIS_HOST Redis host (standalone mode) redis Yes*
REDIS_PORT Redis port 6379 Yes*
REDIS_PASSWORD Redis auth password - No
REDIS_DB Redis database number (0-15) 0 No
REDIS_TLS Enable TLS encryption false No

*Required for standalone mode (when REDIS_CLUSTER_MODE=false)

Cluster Mode (Production - ElastiCache)#

Variable Description Default Required
REDIS_CLUSTER_MODE Enable cluster mode false No
REDIS_CLUSTER_NODES Comma-separated cluster nodes (host:port,host:port) - For cluster

Example: REDIS_CLUSTER_NODES=node1.cache.amazonaws.com:6379,node2.cache.amazonaws.com:6379

Advanced Configuration#

Variable Description Default Required
REDIS_KEY_PREFIX Key prefix for namespacing - No
REDIS_DEFAULT_TTL Default TTL in seconds 300 No
REDIS_CONNECT_TIMEOUT Connection timeout (ms) 10000 No
REDIS_COMMAND_TIMEOUT Command timeout (ms) 5000 No

Circuit Breaker (Resilience)#

Variable Description Default Required
REDIS_CIRCUIT_BREAKER Enable circuit breaker true No
REDIS_CB_FAILURE_THRESHOLD Failures before opening circuit 5 No
REDIS_CB_RESET_TIMEOUT Recovery wait time (ms) 30000 No

Vector Database (Milvus)#

Variable Description Default Required
VECTOR_DB_URL Milvus HTTP URL http://milvus:19530 For RAG
MILVUS_ADDRESS Milvus gRPC address milvus:19530 For RAG

Neo4j Graph Database#

Variable Description Default Required
NEO4J_URI Neo4j Bolt URI bolt://neo4j:7687 For knowledge graph
NEO4J_USER Neo4j username neo4j For knowledge graph
NEO4J_PASSWORD Neo4j password dev_password For knowledge graph
NEO4J_DATABASE Neo4j database name lilith For knowledge graph

Elasticsearch#

Variable Description Default Required
ELASTICSEARCH_URL Elasticsearch URL http://elasticsearch:9200 For search

Kafka#

Variable Description Default Required
KAFKA_BOOTSTRAP_SERVERS Kafka bootstrap servers kafka:9092 For events
KAFKA_ZOOKEEPER_CONNECT Zookeeper connection string zookeeper:2181 For events

MinIO#

Variable Description Default Required
MINIO_ENDPOINT MinIO endpoint minio:9000 For local S3
MINIO_ACCESS_KEY MinIO access key minioadmin For local S3
MINIO_SECRET_KEY MinIO secret key minioadmin For local S3

AI/ML Service Configuration#

Variable Description Default Required
SAFETY_MODE Content moderation level (strict, moderate, permissive) strict Yes
GPU_ENABLED Enable GPU acceleration for ML models false Optional
AUDIO_CACHE_SIZE Audio cache size for TTS 1GB Optional
WHISPER_MODEL_SIZE Whisper STT model size (tiny, base, small, medium, large) medium For STT
ENABLE_DIARIZATION Enable speaker diarization in STT true Optional
PROCESSING_QUEUE_SIZE Ingestion processing queue size 100 Optional

Observability#

Variable Description Default Required
PROMETHEUS_URL Prometheus server URL http://prometheus:9090 For metrics
GRAFANA_URL Grafana server URL http://grafana:3000 For dashboards
JAEGER_URL Jaeger server URL http://jaeger:16686 For tracing

Feature Flags#

Variable Description Default Required
FEATURE_VOICE_CHAT Enable voice chat feature true Optional
FEATURE_METAVERSE Enable metaverse features false Optional
FEATURE_NFT_MARKETPLACE Enable NFT marketplace false Optional
FEATURE_CRYPTO_PAYMENTS Enable cryptocurrency payments false Optional

Rate Limiting#

Variable Description Default Required
RATE_LIMIT_WINDOW_MS Rate limit window in milliseconds 60000 Optional
RATE_LIMIT_MAX_REQUESTS Max requests per window 100 Optional

Logging#

Variable Description Default Required
LOG_LEVEL Logging level (debug, info, warn, error) info Optional
LOG_FORMAT Log output format (json, pretty) json Optional

Port Mappings (Development)#

The following ports are exposed in local development:

Application Services#

Service Port Description
BFF 3000 Backend for Frontend
Conversation 3001 Chat/conversation service
AI 3002 AI orchestration
Auth 3003 Authentication
Content 3004 Content management
Media 3005 Media handling
Notification 3006 Notifications
Moderation 3007 Content moderation
RAG 3008 Retrieval-augmented generation
TTS 3009 Text-to-speech
STT 3010 Speech-to-text
Ingestion 3011 Data ingestion
Knowledge 3012 Knowledge graph

Infrastructure#

Service Port Description
PostgreSQL 5433 Database
Redis 6380 Cache
Elasticsearch 9201 Search
Neo4j Browser 7475 Graph DB UI
Neo4j Bolt 7688 Graph DB
Milvus 19530 Vector DB
MinIO API 9000 S3-compatible storage
MinIO Console 9001 S3 UI
Kafka 9092/9093 Event streaming
Zookeeper 2181 Kafka coordination

Monitoring & Tools#

Service Port Description
Prometheus 9090 Metrics
Grafana 9092 Dashboards
Alertmanager 9093 Alerts
Jaeger 16686 Tracing
Vault 8200 Secrets
Redis Commander 8082 Redis UI
pgAdmin 8083 PostgreSQL UI
Kafka UI 8084 Kafka UI

Production Considerations#

Secrets Management#

  1. Never store secrets in code or version control
  2. Use a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.)
  3. Rotate secrets regularly
  4. Use different secrets per environment
bash
# Generate secure JWT secrets
openssl rand -base64 32

# Generate password salt
openssl rand -hex 16

Environment-Specific Configuration#

Environment NODE_ENV Typical Configuration
Development development Local defaults, debug logging
Staging staging Production-like, test API keys
Production production Real API keys, strict security

Troubleshooting#

Common Issues#

  1. Database connection refused

    • Check POSTGRES_HOST is reachable
    • Verify POSTGRES_PASSWORD is correct
    • Ensure PostgreSQL container is healthy
  2. AI features not working

    • Verify OPENAI_API_KEY or ANTHROPIC_API_KEY is valid
    • Check API key has sufficient credits
  3. Media upload failing

    • Check S3_BUCKET exists
    • Verify AWS credentials have proper permissions
    • For local dev, ensure MinIO is running
  4. Kafka connection issues

    • Ensure Zookeeper is running and healthy
    • Check KAFKA_BOOTSTRAP_SERVERS is correct
    • Verify Kafka container started successfully