Skip to main content

Configuration

Cluster is configured through environment variables. This page documents all available options.

Environment Variables​

Required Variables​

Database​

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@localhost:5432/cluster

Azure AD​

VariableDescriptionExample
AZURE_TENANT_IDAzure AD directory ID12345678-1234-1234-1234-123456789012
AZURE_CLIENT_IDApplication (client) ID87654321-4321-4321-4321-210987654321
AZURE_CLIENT_SECRETClient secret valueabc123~secret

Application​

VariableDescriptionExample
SESSION_SECRETSecret for session cookiesrandom-32-char-string

Optional Variables​

Server​

VariableDefaultDescription
PORT4000API server port
NODE_ENVdevelopmentEnvironment mode
LOG_LEVELinfoLogging verbosity

CORS​

VariableDefaultDescription
WEB_URLhttp://localhost:3000Frontend origin for CORS
CORS_CREDENTIALStrueAllow credentials in CORS

Search (Optional)​

VariableDefaultDescription
MEILISEARCH_URL—Meilisearch server URL
MEILISEARCH_API_KEY—Meilisearch API key

Session (Optional)​

VariableDefaultDescription
REDIS_URL—Redis URL for session storage
SESSION_MAX_AGE86400000Session TTL in milliseconds (24h)

Frontend Variables​

These go in packages/web/.env:

VariableDescriptionExample
VITE_API_URLAPI server URLhttp://localhost:4000/api
VITE_AZURE_CLIENT_IDAzure AD client IDSame as AZURE_CLIENT_ID
VITE_AZURE_TENANT_IDAzure AD tenant IDSame as AZURE_TENANT_ID

Configuration Files​

.env.example​

The repository includes an example configuration:

# Database
DATABASE_URL=postgresql://cluster:devpassword@localhost:5432/cluster

# Azure AD - Get these from Azure Portal
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

# Application
PORT=4000
NODE_ENV=development
WEB_URL=http://localhost:3000
SESSION_SECRET=change-this-to-a-random-string

# Optional: Meilisearch
# MEILISEARCH_URL=http://localhost:7700
# MEILISEARCH_API_KEY=your-master-key

# Optional: Redis (for multi-instance deployments)
# REDIS_URL=redis://localhost:6379

Docker Compose Override​

For local development, create docker-compose.override.yml:

version: '3.8'
services:
  api:
    volumes:
      - ./packages/server/src:/app/packages/server/src
    environment:
      - LOG_LEVEL=debug
  web:
    volumes:
      - ./packages/web/src:/app/packages/web/src

Production Configuration​

Security Recommendations​

# Use strong secrets
SESSION_SECRET=$(openssl rand -base64 32)

# Enable production mode
NODE_ENV=production

# Use HTTPS URLs
WEB_URL=https://cluster.yourcompany.com
API_URL=https://api.cluster.yourcompany.com

Database Connection​

For production, use connection pooling:

# With PgBouncer
DATABASE_URL=postgresql://user:pass@pgbouncer:6432/cluster?pgbouncer=true

# AWS RDS with SSL
DATABASE_URL=postgresql://user:pass@rds-endpoint:5432/cluster?sslmode=require

Multi-Instance Deployment​

When running multiple API instances, configure shared session storage:

# Redis for sessions
REDIS_URL=redis://redis.cluster.internal:6379

# Or Redis Cluster
REDIS_URL=redis://node1:6379,node2:6379,node3:6379

Logging​

Log Levels​

LevelDescription
errorOnly errors
warnErrors and warnings
infoStandard operations (default)
debugDetailed debugging

Structured Logging​

In production, logs are JSON-formatted:

{
  "level": "info",
  "timestamp": "2025-01-04T10:30:00.000Z",
  "message": "Request completed",
  "method": "GET",
  "path": "/api/annotations",
  "status": 200,
  "duration": 45
}

Feature Flags​

Some features can be toggled via environment:

VariableDefaultDescription
ENABLE_SEARCHfalseEnable Meilisearch integration
ENABLE_METRICSfalseExpose Prometheus metrics

Validation​

Cluster validates configuration on startup. Missing required variables will cause the server to exit with an error:

❌ Missing required environment variable: AZURE_CLIENT_ID
Please check your .env file or environment configuration.

Next Steps​