Skip to content
Documentation

Environment Configuration

Environment Configuration

Section titled “Environment Configuration”

This guide provides a complete reference for all environment variables used in Querri deployment.

Configuration File

Section titled “Configuration File”

Querri uses a .env-prod file located in the repository root (/path/to/Querri/.env-prod). This file is referenced by all services via the env_file directive in docker-compose.yml.

Required vs Optional Variables

Section titled “Required vs Optional Variables”

Required Variables (Must Configure)

Section titled “Required Variables (Must Configure)”

These variables 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 for authentication
  • WORKOS_CLIENT_ID - WorkOS client identifier
  • JWT_PRIVATE_KEY - Private key for JWT token signing
  • AZURE_OPENAI_ENDPOINT or OPENAI_API_KEY - AI provider credentials

Optional Variables

Section titled “Optional Variables”

These variables have defaults or are optional features:

  • SERVER_API_REPLICAS - Number of API service replicas (default: 4)
  • STRIPE_KEY - Stripe integration for billing
  • PRISMATIC_KEY - Prismatic integration marketplace
  • SENDGRID_API_KEY - Email sending via SendGrid
  • Storage and analytics configurations

Environment Variables Reference

Section titled “Environment Variables Reference”

Application Environment

Section titled “Application Environment”

ENVIRONMENT

Section titled “ENVIRONMENT”
Terminal window
ENVIRONMENT=production

Values: production, development Description: Determines application behavior and logging levels Required: Yes

Section titled “COOKIE_DOMAIN”
Terminal window
COOKIE_DOMAIN=app.querri.com

Description: Domain for session cookies Required: Yes (production)

SDLC_ENVIRONMENT

Section titled “SDLC_ENVIRONMENT”
Terminal window
SDLC_ENVIRONMENT=prod

Values: prod, dev, staging Description: Software development lifecycle environment identifier Required: Yes

Web Application Configuration

Section titled “Web Application Configuration”

PUBLIC_BASE_URL

Section titled “PUBLIC_BASE_URL”
Terminal window
PUBLIC_BASE_URL="https://app.yourcompany.com"

Description: Base URL for the application (used in emails, redirects) Required: Yes

PUBLIC_DOMAIN

Section titled “PUBLIC_DOMAIN”
Terminal window
PUBLIC_DOMAIN="https://app.yourcompany.com"

Description: Primary domain for the application Required: Yes

Section titled “PUBLIC_API_GATEWAY_LINK”
Terminal window
PUBLIC_API_GATEWAY_LINK="/api"

Description: API gateway path relative to base URL Default: /api

PUBLIC_LOGOUT_URL

Section titled “PUBLIC_LOGOUT_URL”
Terminal window
PUBLIC_LOGOUT_URL="/hub/signout"

Description: Logout endpoint path Default: /hub/signout

PUBLIC_ISDEV

Section titled “PUBLIC_ISDEV”
Terminal window
PUBLIC_ISDEV=false

Description: Enable development mode features Values: true, false

Database Configuration

Section titled “Database Configuration”

MongoDB Settings

Section titled “MongoDB Settings”
Terminal window
# MongoDB Host
MONGODB_HOST=mongo

Description: MongoDB hostname (use service name for Docker) Default: mongo

Terminal window
# MongoDB Port
MONGODB_PORT=27017

Description: MongoDB port Default: 27017

Terminal window
# MongoDB Root Username
MONGO_INITDB_ROOT_USERNAME=querri

Description: MongoDB admin username Required: Yes

Terminal window
# MongoDB Root Password
MONGO_INITDB_ROOT_PASSWORD=your_secure_password_here

Description: MongoDB admin password Required: Yes Security: Use strong, randomly generated password

Alternative: MongoDB Connection String

Section titled “Alternative: MongoDB Connection String”
Terminal window
# Full MongoDB Connection String (alternative to individual settings)
MONGODB_CONNECTION_STRING=mongodb://username:password@host:27017/?authSource=admin

Description: Complete MongoDB connection URI Note: Overrides individual MONGODB_HOST, MONGODB_PORT settings if provided

Redis Configuration

Section titled “Redis Configuration”
Terminal window
# Redis Host
REDIS_HOST=redis

Description: Redis hostname (use service name for Docker) Default: redis

Terminal window
# Redis Port
REDIS_PORT=6379

Description: Redis port Default: 6379

Terminal window
# Redis Password (optional)
REDIS_PASSWORD=

Description: Redis password if authentication is enabled Optional: Leave empty for no authentication

Authentication (WorkOS)

Section titled “Authentication (WorkOS)”

WorkOS provides SSO and authentication services.

Terminal window
# WorkOS API Key
WORKOS_API_KEY=sk_live_xxxxxxxxxxxxx

Description: WorkOS secret API key Required: Yes Location: WorkOS Dashboard > API Keys

Terminal window
# WorkOS Client ID
WORKOS_CLIENT_ID=client_xxxxxxxxxxxxx

Description: WorkOS OAuth client ID Required: Yes Location: WorkOS Dashboard > Configuration

Terminal window
# WorkOS API Endpoint
WORKOS_API_ENDPOINT=https://auth.yourcompany.com

Description: Custom WorkOS authentication endpoint Default: Uses WorkOS default endpoint

Terminal window
# WorkOS JWKS Endpoint
WORKOS_JWKS_ENDPOINT=https://auth.yourcompany.com/sso/jwks/client_xxxxx

Description: JSON Web Key Set endpoint for JWT verification Required: Yes

Terminal window
# WorkOS Redirect URI
WORKOS_REDIRECT_URI=https://app.yourcompany.com/hub/auth/callback

Description: OAuth callback URL after authentication Required: Yes Format: {PUBLIC_BASE_URL}/hub/auth/callback

Terminal window
# WorkOS Cookie Password
WORKOS_COOKIE_PASSWORD=generate_random_32_character_string

Description: Secret for encrypting session cookies Required: Yes Security: Generate with openssl rand -base64 32

Terminal window
# WorkOS Code Challenge
WORKOS_CODE_CHALLENGE=random_string

Description: PKCE code challenge for OAuth flow Required: Yes

Terminal window
# WorkOS Public Organization
WORKOS_PUBLIC_ORG=org_xxxxxxxxxxxxx

Description: Default organization for public access Optional: Required for multi-tenant deployments

Terminal window
# WorkOS Admin Organization
WORKOS_ADMIN_ORG=org_xxxxxxxxxxxxx

Description: Organization ID for admin users Optional: For enterprise admin segregation

AI Configuration

Section titled “AI Configuration”

Querri supports both OpenAI and Azure OpenAI.

Section titled “Azure OpenAI (Recommended for Enterprise)”
Terminal window
# Azure OpenAI Endpoint
AZURE_OPENAI_ENDPOINT=https://yourcompany.openai.azure.com

Description: Azure OpenAI service endpoint Required: If using Azure OpenAI

Terminal window
# Azure OpenAI API Key
AZURE_OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Description: Azure OpenAI API key Required: If using Azure OpenAI Location: Azure Portal > Azure OpenAI Resource > Keys

Terminal window
# Azure OpenAI API Version
AZURE_OPENAI_API_VERSION=2024-02-15-preview

Description: Azure OpenAI API version Default: 2024-02-15-preview

Terminal window
# Model Deployment Names
STANDARD_MODEL=gpt-4o
FAST_MODEL=gpt-4o-mini
SMART_MODEL=gpt-4o

Description: Azure OpenAI deployment names for different use cases Required: If using Azure OpenAI Note: These are your deployment names in Azure, not model names

OpenAI (Alternative)

Section titled “OpenAI (Alternative)”
Terminal window
# OpenAI API Key
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Description: OpenAI API key Required: If using OpenAI (not Azure) Location: OpenAI Dashboard > API Keys

Storage Configuration

Section titled “Storage Configuration”

Storage System Selection

Section titled “Storage System Selection”
Terminal window
# Metadata Storage
METADATA_STORAGE=MONGO

Description: Database for metadata Values: MONGO Default: MONGO

Terminal window
# File Storage
FILE_STORAGE=S3

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

Terminal window
# Cache Storage
CACHE_STORAGE=REDIS

Description: Caching backend Values: REDIS Note: Not fully implemented

AWS S3 Configuration (if FILE_STORAGE=S3)

Section titled “AWS S3 Configuration (if FILE_STORAGE=S3)”
Terminal window
# AWS Access Key ID
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

Description: AWS access key for S3 Required: If using S3 storage

Terminal window
# AWS Secret Access Key
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Description: AWS secret access key Required: If using S3 storage

Terminal window
# AWS Region
AWS_REGION=us-east-1

Description: AWS region for S3 bucket Default: us-east-1

Billing (Stripe)

Section titled “Billing (Stripe)”
Terminal window
# Stripe API Key
STRIPE_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Description: Stripe secret API key Optional: Required for subscription billing Location: Stripe Dashboard > Developers > API Keys

Terminal window
# Stripe Trial Product
STRIPE_TRIAL_PRODUCT=prod_xxxxxxxxxx

Description: Stripe product ID for trial subscriptions Optional

Terminal window
# Stripe Trial Price
STRIPE_TRIAL_PRICE=price_xxxxxxxxxx

Description: Stripe price ID for trial subscriptions Optional

Terminal window
# Stripe Trial Days
STRIPE_TRIAL_DAYS=14

Description: Number of days for trial period Default: 14

Terminal window
# Stripe Sync Frequency
STRIPE_SYNC_FREQUENCY=0

Description: Subscription sync interval in seconds (0 = manual) Default: 0

Terminal window
# Payment Link
PUBLIC_PAYMENT_LINK="https://billing.stripe.com/p/login/xxxxxxxxxx"

Description: Stripe customer portal link Optional: For user self-service billing

Integration Marketplace (Prismatic)

Section titled “Integration Marketplace (Prismatic)”
Terminal window
# Prismatic Private Key
PRISMATIC_KEY='-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----'

Description: Prismatic RSA private key for API authentication Optional: Required for integration marketplace Format: Full PEM-encoded private key

Terminal window
# Prismatic API Token
PRISMATIC_TOKEN='eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...'

Description: Prismatic JWT token for API calls Optional: Required for integration marketplace

Terminal window
# Prismatic Refresh Token
PRISMATIC_REFRESH='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Description: Prismatic refresh token Optional: For token renewal

Email Configuration (SendGrid)

Section titled “Email Configuration (SendGrid)”
Terminal window
# SendGrid API Key
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Description: SendGrid API key for transactional emails Optional: Required for email notifications Location: SendGrid Dashboard > Settings > API Keys

Terminal window
# Support Email
PUBLIC_SUPPORT_EMAIL=support@yourcompany.com

Description: Email address shown for support Optional: Used in user-facing help text

Security & Authorization

Section titled “Security & Authorization”

JWT Configuration

Section titled “JWT Configuration”
Terminal window
# JWT Private Key
JWT_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----'

Description: RSA private key for signing JWT tokens Required: Yes Format: Full PEM-encoded private key Generation:

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

Reverse Proxy Configuration

Section titled “Reverse Proxy Configuration”
Terminal window
# Reverse Proxy Base URL
REVERSE_PROXY_BASE_URL=http://reverse-proxy:8888

Description: Internal URL for service-to-service communication Default: http://reverse-proxy:8888

Monitoring & Analytics

Section titled “Monitoring & Analytics”

Sentry (Error Tracking)

Section titled “Sentry (Error Tracking)”
Terminal window
# Sentry Organization ID
PUBLIC_SENTRY_ORG_ID="xxxxxxxxxxxxxxxxx"

Description: Sentry organization identifier Optional

Terminal window
# Sentry Project ID
PUBLIC_SENTRY_PROJECT_ID="xxxxxxxxxxxxxxxxx"

Description: Sentry project identifier Optional

Terminal window
# Sentry Key
PUBLIC_SENTRY_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Description: Sentry DSN key Optional

Terminal window
# Sentry Auth Token
SENTRY_AUTH_TOKEN="sntrys_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Description: Sentry authentication token Optional

User Analytics

Section titled “User Analytics”
Terminal window
# Userflow Token
PUBLIC_USERFLOW_TOKEN="ct_xxxxxxxxxxxxxxxxxxxxxxxxxx"

Description: Userflow analytics token Optional: For user onboarding analytics

Terminal window
# Segment Token
SEGMENT_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Description: Segment analytics API token Optional: For usage analytics

Terminal window
# Enable Analytics
PUBLIC_ENABLE_ANALYTICS=true

Description: Enable/disable analytics tracking Values: true, false Default: false

Help Widget

Section titled “Help Widget”
Terminal window
# Gleap API Key
PUBLIC_GLEAP_API_KEY="xxxxxxxxxxxxxxxx"

Description: Gleap support widget API key Optional: For in-app support widget

Maps & Geolocation

Section titled “Maps & Geolocation”
Terminal window
# Google Maps API Key
GMAPS_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Description: Google Maps API key for geocoding Optional: Required for location-based features

Terminal window
# Mapbox Access Token
MAPBOX_ACCESS_TOKEN=pk.eyJ1Ijoiexxxxxxxxxxxxxxxxxxxxxxxxx

Description: Mapbox API token for mapping features Optional: Alternative to Google Maps

Scaling & Performance

Section titled “Scaling & Performance”
Terminal window
# Server API Replicas
SERVER_API_REPLICAS=4

Description: Number of server-api container replicas Default: 4 Recommended: 4-6 for production, 1-2 for development

Configuration Templates

Section titled “Configuration Templates”

Minimal Configuration

Section titled “Minimal Configuration”

For basic development/testing deployment:

Terminal window
# Environment
ENVIRONMENT=production
COOKIE_DOMAIN=localhost


# Database
MONGO_INITDB_ROOT_USERNAME=querri
MONGO_INITDB_ROOT_PASSWORD=secure_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=$(openssl rand -base64 32)


# AI
OPENAI_API_KEY=sk-proj-xxxxxxxxxx


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


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

Production Configuration

Section titled “Production Configuration”

For full production deployment:

Terminal window
# 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_password]


# Redis
REDIS_HOST=redis
REDIS_PORT=6379


# Storage
FILE_STORAGE=S3
AWS_ACCESS_KEY_ID=[your_key]
AWS_SECRET_ACCESS_KEY=[your_secret]
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-----'


# Integrations (optional)
PRISMATIC_KEY='[your_private_key]'
PRISMATIC_TOKEN='[your_token]'

Security Best Practices

Section titled “Security Best Practices”

  1. Never commit .env-prod to version control

    Terminal window
    # Add to .gitignore
    echo ".env-prod" >> .gitignore

  2. Use strong passwords

    Terminal window
    # Generate secure passwords
    openssl rand -base64 32

  3. Rotate keys regularly

    • JWT private keys: Annually
    • API keys: Quarterly
    • Database passwords: Annually

  4. Restrict file permissions

    Terminal window
    chmod 600 .env-prod

  5. Use secrets management (for enterprise)

    • AWS Secrets Manager
    • HashiCorp Vault
    • Kubernetes Secrets

Validating Configuration

Section titled “Validating Configuration”

After configuration, validate your environment:

Terminal window
# Check required variables are set
docker compose config


# Test database connection
docker compose exec hub python -c "from pymongo import MongoClient; client = MongoClient('mongodb://querri:password@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')"


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

Troubleshooting

Section titled “Troubleshooting”

Common Configuration Issues

Section titled “Common Configuration Issues”

Issue: Services can’t connect to MongoDB Solution: Verify MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD match MongoDB initialization

Issue: Authentication fails Solution: Check WorkOS credentials and ensure WORKOS_REDIRECT_URI matches your configured callback URL

Issue: AI features not working Solution: Verify either OPENAI_API_KEY or all three Azure OpenAI variables are set correctly

Issue: File uploads failing Solution: Check FILE_STORAGE setting and corresponding AWS credentials if using S3

Next Steps

Section titled “Next Steps”