# Yemaya Environment Variables

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

## Table of Contents

- [Core Configuration](#core-configuration)
- [Server Configuration](#server-configuration)
- [Database Configuration](#database-configuration)
- [Redis Configuration](#redis-configuration)
- [Storage Configuration](#storage-configuration)
- [Authentication Configuration](#authentication-configuration)
- [AI Services Configuration](#ai-services-configuration)
- [Email Configuration](#email-configuration)
- [Logging Configuration](#logging-configuration)
- [Worker Configuration](#worker-configuration)
- [Feature Flags](#feature-flags)
- [Environment-Specific Settings](#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 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

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