Eve library
Environment Variables Reference
Guide
Revision 1
On this page
Complete reference for all environment variables used in the Lilith platform.
Quick Start#
- Copy
.env.example to .env in the project root
- Update values for your environment
- 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 |
| 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#
- Never store secrets in code or version control
- Use a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.)
- Rotate secrets regularly
- Use different secrets per environment
Recommended Secret Generation#
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#
-
Database connection refused
- Check
POSTGRES_HOST is reachable
- Verify
POSTGRES_PASSWORD is correct
- Ensure PostgreSQL container is healthy
-
AI features not working
- Verify
OPENAI_API_KEY or ANTHROPIC_API_KEY is valid
- Check API key has sufficient credits
-
Media upload failing
- Check
S3_BUCKET exists
- Verify AWS credentials have proper permissions
- For local dev, ensure MinIO is running
-
Kafka connection issues
- Ensure Zookeeper is running and healthy
- Check
KAFKA_BOOTSTRAP_SERVERS is correct
- Verify Kafka container started successfully