Skip to main content

Environment Variables

Complete reference for all configuration options.

Backend Environment Variables​

Server Configuration​

VariableDefaultDescription
PORT3007Server port
NODE_ENVdevelopmentEnvironment mode

Database Configuration​

VariableDefaultDescription
MONGODB_URImongodb://localhost:27017/enterprise_ragMongoDB connection string
REDIS_URLredis://localhost:6378Redis connection URL (production: redis://:password@redis:6379)
REDIS_PASSWORD-Redis authentication password (production only, used by docker-compose)
QDRANT_URLhttp://localhost:6333Qdrant vector database URL (production: http://qdrant:6333)
QDRANT_API_KEY-Qdrant API key (only needed for Qdrant Cloud; not needed for self-hosted)
QDRANT_COLLECTION_NAMEdocumentsQdrant collection name

Azure OpenAI Configuration​

VariableRequiredDescription
LLM_PROVIDERYesSet to azure_openai
EMBEDDING_PROVIDERYesSet to azure
AZURE_OPENAI_API_KEYYesAzure OpenAI API key
AZURE_OPENAI_ENDPOINTYesAzure OpenAI endpoint URL
AZURE_OPENAI_LLM_DEPLOYMENTYesLLM deployment name (e.g., gpt-4o-mini)
AZURE_OPENAI_EMBEDDING_DEPLOYMENTYesEmbedding deployment name
AZURE_OPENAI_API_VERSION2024-02-15-previewAPI version

LLM Settings​

VariableDefaultDescription
LLM_MODELgpt-4o-miniLLM model name
EMBEDDING_MODELtext-embedding-3-smallEmbedding model
JUDGE_LLM_MODELgpt-4o-miniModel for LLM Judge
LLM_TEMPERATURE0.3Generation temperature
LLM_MAX_TOKENS2000Maximum output tokens
LLM_TOP_P1Top-p sampling
LLM_TOP_K50Top-k sampling
EMBEDDING_MAX_CONCURRENCY10Parallel embedding calls

Timeout Configuration​

VariableDefaultDescription
LLM_INVOKE_TIMEOUT60000LLM invoke timeout (ms)
LLM_STREAM_INITIAL_TIMEOUT30000First streaming chunk timeout (ms)
LLM_STREAM_CHUNK_TIMEOUT10000Between chunks timeout (ms)
REQUEST_TIMEOUT_MS30000Default request timeout
STREAMING_TIMEOUT_MS180000Streaming endpoint timeout
SYNC_TIMEOUT_MS600000Sync operation timeout
EMBEDDING_TIMEOUT_MS120000Embedding batch timeout

JWT Authentication​

VariableRequiredDescription
JWT_ACCESS_SECRETYesAccess token secret (min 32 chars)
JWT_REFRESH_SECRETYesRefresh token secret (min 32 chars)
JWT_ACCESS_EXPIRY15mAccess token expiry
JWT_REFRESH_EXPIRY7dRefresh token expiry

Generate secrets:

openssl rand -base64 48
# or
node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"

Encryption​

VariableRequiredDescription
ENCRYPTION_KEYYes32-byte hex key for token encryption
ENCRYPTION_KEY_VERSION1Current key version
ENCRYPTION_KEY_V1NoPrevious key (for rotation)

Generate encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Object Storage (DigitalOcean Spaces)​

Persistent file storage for uploaded data source files and assessment documents. All variables are optional — when unset the upload step is silently skipped and download buttons are hidden in the UI.

VariableDefaultDescription
DO_SPACES_KEY-Spaces access key ID
DO_SPACES_SECRET-Spaces secret access key
DO_SPACES_ENDPOINT-Spaces endpoint URL (e.g. https://fra1.digitaloceanspaces.com)
DO_SPACES_BUCKET-Bucket name
DO_SPACES_REGIONfra1Bucket region

Files are stored under organizations/{orgId}/workspaces/{wsId}/... enforcing org-level isolation. Files are served via a backend proxy — no pre-signed URLs are exposed to clients.

RAG Configuration​

VariableDefaultDescription
RAG_CACHE_ENABLEDtrueEnable response caching
RAG_CACHE_TTL3600Cache TTL (seconds)

Chunking Configuration​

VariableDefaultDescription
MAX_GROUP_TOKENS400Maximum tokens per semantic group
MIN_GROUP_TOKENS200Minimum tokens for standalone chunk
MIN_STANDALONE_TOKENS50Legacy threshold
MAX_LIST_ITEMS15Maximum list items per chunk
EMBEDDING_CONTEXT_TOKENS8192Embedding model context window
PENDING_REINDEXfalseFlag for chunking changes

Chunk Filtering​

VariableDefaultDescription
ENABLE_CHUNK_FILTERtrueFilter low-quality chunks
ENABLE_CODE_FILTERtrueFilter code for non-code queries
USE_TIKTOKENfalseUse accurate token counting

Re-ranking​

VariableDefaultDescription
ENABLE_CROSS_ENCODER_RERANKtrueEnable neural re-ranking
RERANK_PROVIDERllmProvider: cohere, llm, none
COHERE_API_KEY-Cohere API key (if using Cohere)
COHERE_RERANK_MODELrerank-english-v3.0Cohere model
RERANK_TOP_N5Documents after re-ranking
RERANK_MIN_SCORE0.1Minimum score threshold
RERANK_TIMEOUT10000Re-ranking timeout (ms)
RERANK_CACHE_TTL300Re-ranking cache TTL

Context Expansion​

VariableDefaultDescription
ENABLE_CONTEXT_EXPANSIONtrueFetch surrounding chunks
SIBLING_WINDOW_SIZE1Sibling chunks to fetch
MAX_CHUNKS_PER_SOURCE5Max chunks per source document
MIN_SCORE_FOR_EXPANSION0.5Minimum score for expansion

Multi-Tenant Security​

VariableDefaultDescription
ENFORCE_TENANT_ISOLATIONtrueEnforce workspaceId in all queries

Sync Job Recovery​

VariableDefaultDescription
STALE_JOB_TIMEOUT_HOURS2Hours before job is stale
MAX_SYNC_RECOVERY_ATTEMPTS2Max recovery attempts
SYNC_PROGRESS_TIMEOUT_MINUTES30Minutes without progress

Guardrails​

VariableDefaultDescription
GUARDRAIL_STRICT_HALLUCINATION_BLOCKINGtrueBlock hallucinated answers
GUARDRAIL_HALLUCINATION_REQUIRE_BOTHfalseLegacy compound condition
GUARDRAIL_LLM_SEED-Seed for reproducibility
GUARDRAIL_USE_SEED_CRITICALfalseEnable for evaluation

Compliance Monitoring​

VariableDefaultDescription
MONITORING_INTERVAL_HOURS24How often the compliance monitoring alert worker runs (hours)
INSTITUTION_NAMEFinancial EntityInstitution name written into the RT.01.01 sheet of the RoI export

LangSmith Monitoring​

VariableDescription
LANGSMITH_API_KEYLangSmith API key
LANGSMITH_PROJECTretrieva - Project name
LANGSMITH_ENABLEDtrue - Enable tracing

CORS & Security​

VariableDescription
FRONTEND_URLFrontend URL for OAuth redirects
ALLOWED_ORIGINSComma-separated allowed origins

Email Configuration​

VariableDefaultDescription
RESEND_API_KEY-Resend API key for sending emails
SMTP_FROM_NAMERetrievaDisplay name in the "From" field
RESEND_FROM_EMAILnoreply@retrieva.onlineSender email address (must match a verified Resend domain)
note

The email service uses the Resend HTTP API over HTTPS (port 443). No SMTP ports (25, 465, 587) are needed — this is important because DigitalOcean blocks outbound SMTP traffic.

Optional Microservice Extension Points​

The following env vars are not set in production and are not required for development. They exist as future extension points — when set, each corresponding service is delegated to a standalone process instead of running in-process in the backend.

VariableDefaultDescription
EMAIL_SERVICE_URLunsetWhen set, email is proxied to a standalone email service instead of calling Resend directly in-process.
NOTIFICATION_SERVICE_URLunsetWhen set, notifications are proxied to a standalone notification service instead of in-process delivery.
REALTIME_SERVICE_URLunsetWhen set, Socket.io events are published via Redis pub/sub to a standalone realtime service.
INTERNAL_API_KEYunsetShared secret for X-Internal-Api-Key headers on service-to-service calls (only relevant if any *_SERVICE_URL is set).
INTERNAL_REQUEST_TIMEOUT_MS10000Timeout (ms) for internal HTTP calls between services.
SERVICE_NAMEmonolithIdentifies this service in X-Service-Name request headers.

Leave all of these unset in development and production — the backend handles email, notifications, and real-time fully in-process.

Logging​

VariableDefaultDescription
LOG_LEVELinfoLog level
LOG_RETRIEVAL_TRACEfalseDebug retrieval logging

Frontend Environment Variables​

VariableDefaultDescription
NEXT_PUBLIC_API_URLhttp://localhost:3007/api/v1Backend API URL
NEXT_PUBLIC_WS_URLhttp://localhost:3007WebSocket URL
NEXT_PUBLIC_APP_NAMERetrievaApplication name

Environment File Template​

Backend (.env.example)​

# Server
PORT=3007
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/enterprise_rag
REDIS_URL=redis://localhost:6378
QDRANT_URL=http://localhost:6333

# Azure OpenAI (REQUIRED)
LLM_PROVIDER=azure_openai
EMBEDDING_PROVIDER=azure
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_LLM_DEPLOYMENT=gpt-4o-mini
AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small

# JWT (REQUIRED - generate with: openssl rand -base64 48)
JWT_ACCESS_SECRET=
JWT_REFRESH_SECRET=

# Encryption (REQUIRED - generate with: openssl rand -hex 32)
ENCRYPTION_KEY=

# Object Storage (DigitalOcean Spaces) — optional, files stored in-memory only when unset
DO_SPACES_KEY=
DO_SPACES_SECRET=
DO_SPACES_ENDPOINT=https://fra1.digitaloceanspaces.com
DO_SPACES_BUCKET=
DO_SPACES_REGION=fra1

# Email (optional for local dev - emails will be skipped if not set)
RESEND_API_KEY=
SMTP_FROM_NAME=Retrieva
RESEND_FROM_EMAIL=noreply@yourdomain.com

# Frontend
FRONTEND_URL=http://localhost:3000
ALLOWED_ORIGINS=http://localhost:3000

Frontend (.env.example)​

NEXT_PUBLIC_API_URL=http://localhost:3007/api/v1
NEXT_PUBLIC_WS_URL=http://localhost:3007
NEXT_PUBLIC_APP_NAME=Retrieva

Secret Generation​

All Required Secrets​

# JWT Access Secret
echo "JWT_ACCESS_SECRET=$(openssl rand -base64 48)"

# JWT Refresh Secret
echo "JWT_REFRESH_SECRET=$(openssl rand -base64 48)"

# Encryption Key (32-byte hex)
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"

Environment-Specific Configurations​

Development​

NODE_ENV=development
LOG_LEVEL=debug
LOG_RETRIEVAL_TRACE=true
RAG_CACHE_ENABLED=false

Production​

NODE_ENV=production
LOG_LEVEL=info
LOG_RETRIEVAL_TRACE=false
RAG_CACHE_ENABLED=true
ENFORCE_TENANT_ISOLATION=true

Testing​

NODE_ENV=test
LOG_LEVEL=error
MONGODB_URI=mongodb://localhost:27017/enterprise_rag_test