TurfAI Environment Variables Inventory

Synced from the TurfAI source on 2026-09-14 · 7c101c0.

Overview

This document provides a comprehensive inventory of all environment variables used across TurfAI services for both local development and cloud deployment.

Last Updated: November 4, 2025 Project: TurfAI v0.9.1 GCP Project: turfai-476911

Table of Contents

1. Shared Secrets
2. DMS (Strapi)
3. Router Service
4. Processor Service
5. LLM Service
6. RAG Query Service
7. RAG Embeddings Worker
8. Infrastructure
9. Local Development Setup
10. Cloud Deployment Setup

Legend

• 🔴 Required - Must be set for service to function
• 🟡 Recommended - Should be set for full functionality
• 🟢 Optional - Can be omitted (has default)
• 🔐 Secret - Sensitive value, store securely
• 🔗 Shared - Must be identical across multiple services

Shared Secrets

These secrets MUST be identical across all services for proper authentication and communication.

Generation Commands:

# Generate JWT Secret
openssl rand -base64 32

# Generate Router API Key
uuidgen
# or
openssl rand -hex 16

Services Using JWT_SECRET:

• DMS (as JWT_SECRET)
• Router (as STRAPI_JWT_SECRET)
• Processor (as STRAPI_JWT_SECRET)
• RAG Query Service (as STRAPI_JWT_SECRET)
• RAG Embeddings Worker (as STRAPI_JWT_SECRET)

Services Using ROUTER_API_KEY:

• DMS (for submitting jobs)
• Router (for validating requests)

DMS (Strapi)

Service: Document Management System (Strapi CMS) Location: /dms/ Port: 1338 (local), Cloud Run (cloud) Config File: .env

Database Configuration

Strapi Secrets

Storage Configuration

Redis Configuration

Service URLs

Application Configuration

Router Service

Service: Job routing and API gateway Location: /router/ Port: 8000 (local), Cloud Run (cloud) Config File: .env

Database Configuration

Redis Configuration

Authentication

Service URLs

Application Configuration

Processor Service

Service: Document processing and workflow execution Location: /processors/ Port: 8001 (local), Cloud Run (cloud) Config File: .env

Database Configuration

Redis Configuration

Authentication

Service URLs

GCS Configuration

Application Configuration

LLM Service

Service: LLM abstraction layer Location: /llm-service/ Port: 9090 (local), Cloud Run (cloud) Config File: .env

LLM Provider API Keys

Vertex AI Configuration

Ollama Configuration (Local Models)

Application Configuration

RAG Query Service

Service: Real-time RAG query processing Location: /rag_query_service/ Port: 8003 (local), Cloud Run (cloud) Config File: .env

Database Configuration

Authentication

Service URLs

GCS Configuration

Application Configuration

RAG Embeddings Worker

Service: Background RAG embedding generation Location: /processors/rag_embeddings/ Port: N/A (background worker), Cloud Run (cloud) Config File: .env

Database Configuration

Redis Configuration

Authentication

Service URLs

GCS Configuration

OCR Configuration

Application Configuration

Infrastructure

These are not environment variables but configuration values used during infrastructure setup.

Cloud SQL

Redis Memorystore

Cloud Storage

Service Account

Local Development Setup

Quick Start

1. Copy example environment file:

   cp .env.example .env

2. Generate shared secrets:

   # JWT Secret
   export JWT_SECRET=$(openssl rand -base64 32)
   echo "JWT_SECRET=$JWT_SECRET" >> .env
   
   # Router API Key
   export ROUTER_API_KEY=$(uuidgen)
   echo "ROUTER_API_KEY=$ROUTER_API_KEY" >> .env

3. Configure local infrastructure:

   # PostgreSQL (via Docker or local install)
   export DATABASE_HOST=localhost
   export DATABASE_PORT=5432
   export DATABASE_NAME=turfai_dms
   export DATABASE_USERNAME=postgres
   export DATABASE_PASSWORD=your_local_password
   
   # Redis (via Docker or local install)
   export REDIS_HOST=localhost
   export REDIS_PORT=6379
   
   # GCS (use local bucket or dev bucket)
   export GCS_BUCKET_NAME=turfai-documents-dev
   export GOOGLE_CLOUD_PROJECT=your-gcp-project
   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

4. Configure service URLs (all local):

   export DMS_URL=http://localhost:1338
   export ROUTER_URL=http://localhost:8000
   export LLM_SERVICE_URL=http://localhost:9090
   export RAG_QUERY_SERVICE_URL=http://localhost:8003

5. Propagate to all services:

   # Copy .env to each service directory
   cp .env dms/.env
   cp .env router/.env
   cp .env processors/.env
   cp .env llm-service/.env
   cp .env rag_query_service/.env

Running Locally

# Terminal 1: Start PostgreSQL and Redis (via Docker Compose)
cd dev/bootstrap
docker-compose up -d postgres redis

# Terminal 2: Start DMS
cd dms
npm run develop

# Terminal 3: Start LLM Service
cd llm-service
python -m uvicorn api.main:app --host 0.0.0.0 --port 9090 --reload

# Terminal 4: Start RAG Query Service
cd rag_query_service
python -m uvicorn main:app --host 0.0.0.0 --port 8003 --reload

# Terminal 5: Start Router
cd router
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 6: Start Processor
cd processors
python -m uvicorn main:app --host 0.0.0.0 --port 8001 --reload

# Terminal 7: Start RAG Embeddings Worker
cd processors/rag_embeddings
python worker.py

Cloud Deployment Setup

Environment Variables Checklist

Before deploying, ensure you have:

1. Generated shared secrets:

   • ✅ JWT_SECRET (used across all services)
   • ✅ ROUTER_API_KEY (used by DMS and Router)
   • ✅ Strapi secrets (APP_KEYS, API_TOKEN_SALT, etc.)

2. Infrastructure configured:

   • ✅ Cloud SQL instance created
   • ✅ Redis Memorystore created
   • ✅ GCS bucket created
   • ✅ Service account created with all permissions

3. Secrets stored:

   • ✅ Database password in Secret Manager
   • ✅ LLM API keys in Secret Manager (if using)
   • ✅ Service account key in Secret Manager

4. Service URLs discovered:

   • ✅ DMS URL (from first deployment)
   • ✅ Router URL (from deployment)
   • ✅ LLM Service URL (from deployment)
   • ✅ RAG Query Service URL (from deployment)

Deployment Order

1. Infrastructure (Cloud SQL, Redis, GCS, Service Account)
2. DMS - Base URL needed by all other services
3. LLM Service - Required by RAG and Processor
4. RAG Query Service - Required by DMS RAG proxy
5. RAG Embeddings Worker - Background processing
6. Router - Job routing
7. Processor - Job execution

Configuration Management

All deployment scripts auto-detect URLs from previous deployments:

# Configuration stored in deploy/.config/
deploy/.config/
├── cloudsql.env                 # Cloud SQL connection info
├── redis.env                    # Redis connection info
├── storage.env                  # GCS bucket info
├── service-account.env          # Service account details
├── shared-secrets.env           # JWT secrets, API keys
├── dms-deployment.env           # DMS URL
├── router-deployment.env        # Router URL
├── llm-deployment.env           # LLM URL
├── rag-deployment.env           # RAG Query URL
└── rag-embeddings-deployment.env # RAG Embeddings URL

Validation

Check All Required Variables

# Run this script to validate environment variables
bash deploy/scripts/validate-env-vars.sh

Test Connectivity

# Test database connection
psql -h $DATABASE_HOST -U $DATABASE_USERNAME -d $DATABASE_NAME -c "SELECT version();"

# Test Redis connection
redis-cli -h $REDIS_HOST -p $REDIS_PORT ping

# Test GCS access
gsutil ls gs://$GCS_BUCKET_NAME/

# Test service URLs
curl $DMS_URL/_health
curl $LLM_SERVICE_URL/health
curl $RAG_QUERY_SERVICE_URL/health

Troubleshooting

Common Issues

Issue: Services can't authenticate with DMS

• Check that JWT_SECRET / STRAPI_JWT_SECRET matches across all services
• Verify JWT secret is exactly the same (no extra whitespace)

Issue: Router API calls fail

• Check that ROUTER_API_KEY matches between DMS and Router
• Ensure API key is in UUID format

Issue: Database connection fails

• For local: Check PostgreSQL is running
• For cloud: Verify Cloud SQL connection string format
• Check DATABASE_PASSWORD is correct

Issue: Redis connection fails

• For local: Check Redis is running on port 6379
• For cloud: Verify VPC connector is configured
• Check internal IP address is correct

Issue: GCS operations fail

• Check GCS_BUCKET_NAME is correct
• Verify service account has storage.objectAdmin role
• For local: Check GOOGLE_APPLICATION_CREDENTIALS path
• For cloud: Verify Workload Identity is configured

Issue: RAG embeddings not generating

• Check Cloud Vision API is enabled
• Verify service account has aiplatform.user role
• Check LLM_SERVICE_URL is accessible

Security Best Practices

1. Never commit secrets to git

   • Use .env.example for templates
   • Keep actual .env files in .gitignore

2. Use Secret Manager in cloud

   • Store all passwords in Secret Manager
   • Reference via secrets, not environment variables

3. Rotate secrets regularly

   • JWT secrets should be rotated quarterly
   • API keys should be rotated on compromise

4. Limit service account permissions

   • Use least-privilege principle
   • Only grant necessary roles

5. Enable audit logging

   • Log all authentication attempts
   • Monitor for suspicious activity

Related Documentation

• Deployment Lessons Learned: /docs/deployment-lessons-learned-2025-11-04.md
• Deployment Checklist: /docs/deployment-checklist.md
• Database Schema: /docs/database-schema-complete.md
• Architecture: /CLAUDE.md

Last Updated: November 4, 2025 Maintainers: TurfAI Development Team