Environment Variables

This reference provides comprehensive documentation for all environment variables used in Querri. Environment variables are configured in the .env-prod file for production deployments or .env file for development.

Configuration File Location

Production: /path/to/Querri/.env-prod (referenced in docker-compose.yml) Development: /path/to/Querri/.env (for local development)

Quick Reference

Required Variables

These must be configured for Querri to function:

MONGO_INITDB_ROOT_USERNAME - MongoDB admin username
MONGO_INITDB_ROOT_PASSWORD - MongoDB admin password
WORKOS_API_KEY - WorkOS API key
WORKOS_CLIENT_ID - WorkOS client ID
WORKOS_JWKS_ENDPOINT - WorkOS JWKS endpoint
WORKOS_REDIRECT_URI - OAuth callback URL
WORKOS_COOKIE_PASSWORD - Session cookie encryption key
JWT_PRIVATE_KEY - JWT signing private key
AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_API_KEY OR OPENAI_API_KEY - AI provider

Optional Variables

These have defaults or enable optional features:

Storage configuration (S3, local)
Billing integration (Stripe)
Email service (SendGrid)
Analytics and monitoring
Feature flags
Scaling parameters

Application Environment

ENVIRONMENT

ENVIRONMENT=production

Values: production, development Default: None (required) Description: Application environment mode Impact:

Controls logging verbosity
Enables/disables debug features
Affects error handling
Influences caching behavior

SDLC_ENVIRONMENT

SDLC_ENVIRONMENT=prod

Values: prod, dev, staging Default: None (recommended) Description: Software development lifecycle environment identifier Impact:

Used in logging and monitoring
Helps distinguish deployment tiers
Affects telemetry tagging

COOKIE_DOMAIN

COOKIE_DOMAIN=app.yourcompany.com

Default: None (required for production) Description: Domain for session cookies Format: Hostname without protocol Examples:

app.querri.com
localhost (for development)

Note: Must match your deployment domain

Web Application

PUBLIC_BASE_URL

PUBLIC_BASE_URL="https://app.yourcompany.com"

Default: None (required) Description: Base URL for the application Usage:

Email links
OAuth redirects
Share links
API callbacks

Format: Full URL with protocol, no trailing slash

PUBLIC_DOMAIN

PUBLIC_DOMAIN="https://app.yourcompany.com"

Default: None (required) Description: Primary domain for the application Note: Typically same as PUBLIC_BASE_URL

PUBLIC_API_GATEWAY_LINK

PUBLIC_API_GATEWAY_LINK="/api"

Default: /api Description: API gateway path relative to base URL Format: Path starting with /

PUBLIC_LOGOUT_URL

PUBLIC_LOGOUT_URL="/hub/signout"

Default: /hub/signout Description: Logout endpoint path

PUBLIC_ISDEV

PUBLIC_ISDEV=false

Values: true, false Default: false Description: Enable development mode features in UI Impact:

Shows debug information
Enables dev tools
Displays additional logging

Database Configuration

MongoDB

MONGODB_HOST

MONGODB_HOST=mongo

Default: mongo Description: MongoDB hostname or IP address Docker: Use service name (mongo) External: Use hostname or IP

MONGODB_PORT

MONGODB_PORT=27017

Default: 27017 Description: MongoDB port

MONGO_INITDB_ROOT_USERNAME

MONGO_INITDB_ROOT_USERNAME=querri

Default: None (required) Description: MongoDB root username Security: Used for database initialization and connection

MONGO_INITDB_ROOT_PASSWORD

MONGO_INITDB_ROOT_PASSWORD=your_secure_password_here

Default: None (required) Description: MongoDB root password Security:

Use strong, randomly generated password
Minimum 16 characters recommended
Generate: openssl rand -base64 24

MONGODB_CONNECTION_STRING

MONGODB_CONNECTION_STRING=mongodb://username:password@host:27017/?authSource=admin

Default: None (optional) Description: Complete MongoDB connection URI Note: Overrides individual MONGODB_HOST, MONGODB_PORT if provided Format: Standard MongoDB connection string format

Redis

REDIS_HOST

REDIS_HOST=redis

Default: redis Description: Redis hostname or IP address Docker: Use service name (redis)

REDIS_PORT

REDIS_PORT=6379

Default: 6379 Description: Redis port

REDIS_PASSWORD

REDIS_PASSWORD=

Default: Empty (no authentication) Description: Redis password if authentication is enabled Optional: Leave empty for no authentication

Authentication (WorkOS)

WORKOS_API_KEY

WORKOS_API_KEY=sk_live_xxxxxxxxxxxxx

Default: None (required) Description: WorkOS secret API key Location: WorkOS Dashboard → API Keys Security: Keep secret, never commit to version control

WORKOS_CLIENT_ID

WORKOS_CLIENT_ID=client_xxxxxxxxxxxxx

Default: None (required) Description: WorkOS OAuth client identifier Location: WorkOS Dashboard → Configuration

WORKOS_API_ENDPOINT

WORKOS_API_ENDPOINT=https://auth.yourcompany.com

Default: WorkOS default endpoint Description: Custom WorkOS authentication endpoint Optional: Only needed for custom WorkOS deployments

WORKOS_JWKS_ENDPOINT

WORKOS_JWKS_ENDPOINT=https://api.workos.com/sso/jwks/client_xxxxx

Default: None (required) Description: JSON Web Key Set endpoint for JWT verification Format: https://api.workos.com/sso/jwks/{WORKOS_CLIENT_ID}

WORKOS_REDIRECT_URI

WORKOS_REDIRECT_URI=https://app.yourcompany.com/hub/auth/callback

Default: None (required) Description: OAuth callback URL after authentication Format: {PUBLIC_BASE_URL}/hub/auth/callback Important: Must match configuration in WorkOS dashboard

WORKOS_COOKIE_PASSWORD

WORKOS_COOKIE_PASSWORD=generate_random_32_character_string

Default: None (required) Description: Secret for encrypting session cookies Length: 32 characters minimum Generate: openssl rand -base64 32 Security: Use cryptographically secure random string

WORKOS_CODE_CHALLENGE

WORKOS_CODE_CHALLENGE=random_string

Default: None (required) Description: PKCE code challenge for OAuth flow Generate: Random string, 32+ characters

WORKOS_PUBLIC_ORG

WORKOS_PUBLIC_ORG=org_xxxxxxxxxxxxx

Default: None (optional) Description: Default organization for public access Use Case: Multi-tenant deployments with public workspace

WORKOS_ADMIN_ORG

WORKOS_ADMIN_ORG=org_xxxxxxxxxxxxx

Default: None (optional) Description: Organization ID for admin users Use Case: Enterprise admin segregation

AI Configuration

Azure OpenAI (Recommended for Enterprise)

AZURE_OPENAI_ENDPOINT

AZURE_OPENAI_ENDPOINT=https://yourcompany.openai.azure.com

Default: None (required if using Azure OpenAI) Description: Azure OpenAI service endpoint Location: Azure Portal → Azure OpenAI Resource → Keys and Endpoint

AZURE_OPENAI_API_KEY

AZURE_OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (required if using Azure OpenAI) Description: Azure OpenAI API key Location: Azure Portal → Azure OpenAI Resource → Keys

AZURE_OPENAI_API_VERSION

AZURE_OPENAI_API_VERSION=2024-02-15-preview

Default: 2024-02-15-preview Description: Azure OpenAI API version Note: Update as new API versions become available

STANDARD_MODEL

STANDARD_MODEL=gpt-4o

Default: None (required if using Azure OpenAI) Description: Azure OpenAI deployment name for standard operations Note: This is your deployment name in Azure, not the model name Use Case: General queries and analysis

FAST_MODEL

FAST_MODEL=gpt-4o-mini

Default: None (required if using Azure OpenAI) Description: Azure OpenAI deployment name for fast operations Note: Your deployment name for lightweight model Use Case: Quick responses, simple queries

SMART_MODEL

SMART_MODEL=gpt-4o

Default: None (required if using Azure OpenAI) Description: Azure OpenAI deployment name for complex operations Note: Your deployment name for most capable model Use Case: Complex analysis, code generation

OpenAI (Alternative)

OPENAI_API_KEY

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (required if NOT using Azure OpenAI) Description: OpenAI API key Location: OpenAI Dashboard → API Keys Note: Use this OR Azure OpenAI configuration, not both

Storage Configuration

METADATA_STORAGE

METADATA_STORAGE=MONGO

Values: MONGO Default: MONGO Description: Database for metadata storage Note: Currently only MongoDB supported

FILE_STORAGE

FILE_STORAGE=S3

Values: LOCAL, S3 Default: LOCAL Description: File storage backend Impact:

LOCAL: Files stored in container volume
S3: Files stored in Amazon S3 bucket

CACHE_STORAGE

CACHE_STORAGE=REDIS

Values: REDIS Default: REDIS Description: Caching backend Note: Redis integration in development

AWS S3 Configuration

Only required if FILE_STORAGE=S3

AWS_ACCESS_KEY_ID

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

Default: None (required for S3) Description: AWS access key for S3 access Security: Use IAM user with minimal S3 permissions

AWS_SECRET_ACCESS_KEY

AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Default: None (required for S3) Description: AWS secret access key Security: Keep secret, never commit

AWS_REGION

AWS_REGION=us-east-1

Default: us-east-1 Description: AWS region for S3 bucket Examples: us-west-2, eu-west-1, ap-southeast-1

Authorization (FGA)

FGA Configuration

Fine-grained authorization configuration (future enhancement).

Billing (Stripe)

STRIPE_KEY

STRIPE_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (optional) Description: Stripe secret API key Location: Stripe Dashboard → Developers → API Keys Use Case: Subscription billing and payment processing

STRIPE_TRIAL_PRODUCT

STRIPE_TRIAL_PRODUCT=prod_xxxxxxxxxx

Default: None (optional) Description: Stripe product ID for trial subscriptions Location: Stripe Dashboard → Products

STRIPE_TRIAL_PRICE

STRIPE_TRIAL_PRICE=price_xxxxxxxxxx

Default: None (optional) Description: Stripe price ID for trial subscriptions Location: Stripe Dashboard → Products → Pricing

STRIPE_TRIAL_DAYS

STRIPE_TRIAL_DAYS=14

Default: 14 Description: Number of days for trial period Values: Integer (days)

STRIPE_SYNC_FREQUENCY

STRIPE_SYNC_FREQUENCY=0

Default: 0 Description: Subscription sync interval in seconds Values:

0: Manual sync only
3600: Hourly
86400: Daily

PUBLIC_PAYMENT_LINK

PUBLIC_PAYMENT_LINK="https://billing.stripe.com/p/login/xxxxxxxxxx"

Default: None (optional) Description: Stripe customer portal link Use Case: User self-service billing management

Email (SendGrid)

SENDGRID_API_KEY

SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (optional) Description: SendGrid API key for transactional emails Location: SendGrid Dashboard → Settings → API Keys Use Case: Email notifications, reports, sharing

PUBLIC_SUPPORT_EMAIL

PUBLIC_SUPPORT_EMAIL=support@yourcompany.com

Default: None (optional) Description: Email address shown for support Usage: User-facing help text, contact information

Branding

PUBLIC_COMPANY_NAME

PUBLIC_COMPANY_NAME="Your Company"

Default: “Querri” Description: Company name displayed in UI White-label: Set to your company name

PUBLIC_LOGO_URL

PUBLIC_LOGO_URL="https://yourcompany.com/logo.png"

Default: None (optional) Description: URL to company logo Format: Full URL to image file Recommendations:

PNG with transparency
200x50 pixels (approximate)

Integration Marketplace (Prismatic)

PRISMATIC_KEY

PRISMATIC_KEY='-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----'

Default: None (optional) Description: Prismatic RSA private key for API authentication Format: Full PEM-encoded private key Use Case: Integration marketplace functionality

PRISMATIC_TOKEN

PRISMATIC_TOKEN='eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...'

Default: None (optional) Description: Prismatic JWT token for API calls Use Case: Integration marketplace

PRISMATIC_REFRESH

PRISMATIC_REFRESH='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Default: None (optional) Description: Prismatic refresh token Use Case: Token renewal for integration marketplace

Monitoring & Analytics

Sentry (Error Tracking)

PUBLIC_SENTRY_ORG_ID

PUBLIC_SENTRY_ORG_ID="xxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Sentry organization identifier

PUBLIC_SENTRY_PROJECT_ID

PUBLIC_SENTRY_PROJECT_ID="xxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Sentry project identifier

PUBLIC_SENTRY_KEY

PUBLIC_SENTRY_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Sentry DSN key

SENTRY_AUTH_TOKEN

SENTRY_AUTH_TOKEN="sntrys_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Sentry authentication token Use Case: Source map uploads, releases

User Analytics

PUBLIC_USERFLOW_TOKEN

PUBLIC_USERFLOW_TOKEN="ct_xxxxxxxxxxxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Userflow analytics token Use Case: User onboarding analytics

SEGMENT_TOKEN

SEGMENT_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Default: None (optional) Description: Segment analytics API token Use Case: Usage analytics

PUBLIC_ENABLE_ANALYTICS

PUBLIC_ENABLE_ANALYTICS=true

Values: true, false Default: false Description: Enable/disable analytics tracking Impact: Controls all analytics services

PUBLIC_GLEAP_API_KEY

PUBLIC_GLEAP_API_KEY="xxxxxxxxxxxxxxxx"

Default: None (optional) Description: Gleap support widget API key Use Case: In-app support widget

Maps & Geolocation

GMAPS_API_KEY

GMAPS_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (optional) Description: Google Maps API key Use Case: Geocoding, location-based features APIs Needed: Geocoding API, Maps JavaScript API

MAPBOX_ACCESS_TOKEN

MAPBOX_ACCESS_TOKEN=pk.eyJ1Ijoiexxxxxxxxxxxxxxxxxxxxxxxxx

Default: None (optional) Description: Mapbox API token Use Case: Mapping features (alternative to Google Maps)

Scaling & Performance

SERVER_API_REPLICAS

SERVER_API_REPLICAS=4

Default: 4 Description: Number of server-api container replicas Recommended:

Development: 1-2
Production (small): 4-6
Production (large): 8-12 Impact: Affects request handling capacity and resource usage

REVERSE_PROXY_BASE_URL

REVERSE_PROXY_BASE_URL=http://reverse-proxy:8888

Default: http://reverse-proxy:8888 Description: Internal URL for service-to-service communication Docker: Use service name and internal port

Security

JWT_PRIVATE_KEY

JWT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----'

Default: None (required) Description: RSA private key for signing JWT tokens Format: Full PEM-encoded private key Generation:

# Generate new RSA key pair
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

# View private key for .env
cat private.pem

Security:

Keep private, never commit
Use 2048-bit or higher
Rotate annually

Configuration Templates

Minimal Development Configuration

For local development and testing:

# Environment
ENVIRONMENT=production
COOKIE_DOMAIN=localhost

# URLs
PUBLIC_BASE_URL="http://localhost:8080"
PUBLIC_DOMAIN="http://localhost:8080"
PUBLIC_ISDEV=true

# Database
MONGO_INITDB_ROOT_USERNAME=querri
MONGO_INITDB_ROOT_PASSWORD=dev_password_123
MONGODB_HOST=mongo
MONGODB_PORT=27017

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# WorkOS (get from WorkOS dashboard)
WORKOS_API_KEY=sk_test_xxxxxxxxxx
WORKOS_CLIENT_ID=client_xxxxxxxxxx
WORKOS_JWKS_ENDPOINT=https://api.workos.com/sso/jwks/client_xxxxxxxxxx
WORKOS_REDIRECT_URI=http://localhost:8080/hub/auth/callback
WORKOS_COOKIE_PASSWORD=generate_with_openssl_rand_base64_32

# AI (choose one)
OPENAI_API_KEY=sk-proj-xxxxxxxxxx

# JWT
JWT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
[Your generated private key]
-----END PRIVATE KEY-----'

# Storage
FILE_STORAGE=LOCAL

# Scaling
SERVER_API_REPLICAS=2

Production Configuration

For production deployment:

# Environment
ENVIRONMENT=production
SDLC_ENVIRONMENT=prod
COOKIE_DOMAIN=app.yourcompany.com

# Web App
PUBLIC_BASE_URL="https://app.yourcompany.com"
PUBLIC_DOMAIN="https://app.yourcompany.com"
PUBLIC_ISDEV=false

# Database
MONGODB_HOST=mongo
MONGODB_PORT=27017
MONGO_INITDB_ROOT_USERNAME=querri_admin
MONGO_INITDB_ROOT_PASSWORD=[strong_random_password]

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Storage
FILE_STORAGE=S3
AWS_ACCESS_KEY_ID=[your_access_key]
AWS_SECRET_ACCESS_KEY=[your_secret_key]
AWS_REGION=us-east-1

# WorkOS
WORKOS_API_KEY=sk_live_xxxxxxxxxx
WORKOS_CLIENT_ID=client_xxxxxxxxxx
WORKOS_API_ENDPOINT=https://auth.yourcompany.com
WORKOS_JWKS_ENDPOINT=https://auth.yourcompany.com/sso/jwks/client_xxxxxxxxxx
WORKOS_REDIRECT_URI=https://app.yourcompany.com/hub/auth/callback
WORKOS_COOKIE_PASSWORD=[generated_secret]
WORKOS_CODE_CHALLENGE=[generated_challenge]

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://yourcompany.openai.azure.com
AZURE_OPENAI_API_KEY=[your_azure_key]
AZURE_OPENAI_API_VERSION=2024-02-15-preview
STANDARD_MODEL=gpt-4o
FAST_MODEL=gpt-4o-mini
SMART_MODEL=gpt-4o

# Scaling
SERVER_API_REPLICAS=6

# Billing
STRIPE_KEY=sk_live_xxxxxxxxxx
STRIPE_TRIAL_DAYS=14

# Email
SENDGRID_API_KEY=SG.xxxxxxxxxx
PUBLIC_SUPPORT_EMAIL=support@yourcompany.com

# JWT
JWT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
[Your generated private key]
-----END PRIVATE KEY-----'

# Analytics (optional)
PUBLIC_ENABLE_ANALYTICS=true
SEGMENT_TOKEN=xxxxxxxxxxxxxxxx

Security Best Practices

Credential Management

Never commit credentials to version control

echo ".env-prod" >> .gitignore
echo ".env" >> .gitignore

Use strong passwords

# Generate secure passwords
openssl rand -base64 32

Rotate credentials regularly
- JWT keys: Annually
- API keys: Quarterly
- Database passwords: Annually
- OAuth tokens: As needed
Restrict file permissions
Terminal window
```
chmod 600 .env-prod
```
Use secrets management for enterprise
- AWS Secrets Manager
- HashiCorp Vault
- Kubernetes Secrets
- Azure Key Vault

Validation

Validate your configuration before deployment:

# Check Docker Compose config
docker compose config

# Test MongoDB connection
docker compose exec hub python -c "from pymongo import MongoClient; client = MongoClient('mongodb://user:pass@mongo:27017/'); print('MongoDB OK')"

# Test Redis connection
docker compose exec server-api python -c "import redis; r = redis.Redis(host='redis', port=6379); r.ping(); print('Redis OK')"

# Verify WorkOS configuration
curl -H "Authorization: Bearer ${WORKOS_API_KEY}" https://api.workos.com/organizations

Troubleshooting

MongoDB Connection Issues

Symptoms: Services can’t connect to MongoDB Solutions:

Verify MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD
Check MongoDB container is running
Verify network connectivity
Review MongoDB logs: docker compose logs mongo

Authentication Failures

Symptoms: Login redirects fail or tokens invalid Solutions:

Verify WORKOS_REDIRECT_URI matches dashboard configuration
Check WORKOS_API_KEY and WORKOS_CLIENT_ID
Ensure WORKOS_JWKS_ENDPOINT is correct
Verify JWT_PRIVATE_KEY is properly formatted

AI Features Not Working

Symptoms: Chat doesn’t respond or errors Solutions:

Verify either OpenAI OR Azure OpenAI config (not both)
Check API keys are valid
For Azure: Verify deployment names match (STANDARD_MODEL, etc.)
Test API connectivity
Review API usage limits

File Upload Issues

Symptoms: File uploads fail or files not accessible Solutions:

If FILE_STORAGE=S3: Verify AWS credentials
If FILE_STORAGE=LOCAL: Check volume mounts
Review storage service logs
Verify file size limits

Environment Variable Checklist

Use this checklist to verify your configuration:

Next Steps

Complete installation with your configuration
Review security settings for your deployment
Set up monitoring to track system health
Configure white-label branding (optional)