# Environment Variables Reference

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](#core-settings)
- [Authentication & Security](#authentication--security)
- [AI/LLM Provider API Keys](#aillm-provider-api-keys)
- [AWS Configuration](#aws-configuration)
- [Email Configuration](#email-configuration)
- [Database Configuration](#database-configuration)
- [AI/ML Service Configuration](#aiml-service-configuration)
- [Observability](#observability)
- [Feature Flags](#feature-flags)

---

## 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

- **OpenAI**:
  [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
- **Anthropic**: [console.anthropic.com](https://console.anthropic.com/)
- **OpenRouter**: [openrouter.ai](https://openrouter.ai/)
- **ElevenLabs**: [elevenlabs.io](https://elevenlabs.io/)

---

## 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

### 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

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
