Environment Variables

This document provides a comprehensive guide to all environment variables used in the Mitigate Chatbot application. For default ENV used in helm, see helm/values.yaml.

Core Application Settings

TZ

• Required: Yes
• Description: Timezone setting for the application
• Example: TZ=America/New_York

RAILS_ENV

• Required: Yes
• Description: Rails environment mode
• Options: production
• Example: RAILS_ENV=production

NODE_ENV

• Required: Yes
• Description: Node.js environment mode
• Options: production
• Example: NODE_ENV=production

SECRET_KEY_BASE

• Required: Yes
• Description: Secret key for Rails application encryption and signing
• Setup: Generate with SecureRandom.hex(64)
• Example: SECRET_KEY_BASE=abc123...

Application Configuration

APP_HOST

• Required: Yes
• Description: The hostname where the application is hosted
• Example: APP_HOST=chatbot.example.com

ORGANIZATION_NAME

• Required: Yes
• Description: Name of the organization using the chatbot. Used for branding in UI and also chatting.
• Example: ORGANIZATION_NAME=Acme Corp

ENABLED_FEATURES

• Required: Yes
• Description: Comma-separated list of enabled features
• Available Features:
  • embeddable_chat - Embed chat widget on external websites
  • jira_integration - Connect with JIRA for issue tracking
  • hansa_crm_api - Integrate with Hansa CRM for customer management
  • chat_api_endpoint - Manage chat API endpoint for chat integration
  • password_auth - Enable password-based authentication for users
  • openid_connect - Configure OAuth authentication with OpenID Connect providers like Microsoft Entra ID
  • ecomap_api - Integrate with Ecomap API for environmental data
  • documents_translation - Translate document chunks into a base language for enhanced RAG performance
  • mcp_tools - Connect to Model Context Protocol (MCP) servers to extend LLM capabilities
  • chat_file_upload - Allow users to upload files in chat messages for multi-modal AI processing
  • chat_api_file_upload - Allow base64-encoded file attachments in chat API requests for multi-modal AI processing
  • data_retention_policy - Define and manage data retention policies for compliance
• Example: ENABLED_FEATURES=password_auth,openid_connect,embeddable_chat,chat_file_upload

EXTERNAL_WIDGET_HOSTS

• Required: When using embeddable_chat feature
• Description: Allowed hosts for embedding the chat widget (CORS)
• Format: Comma-separated list of domains
• Example: EXTERNAL_WIDGET_HOSTS=https://example.com,https://app.example.com

Assistant Configuration

ASSISTANT_NAME

• Required: No
• Description: Display name for the AI assistant
• Example: ASSISTANT_NAME=Support Assistant

ASSISTANT_WELCOME_PROMPT_1

• Required: No
• Description: First welcome message shown to users
• Example: ASSISTANT_WELCOME_PROMPT_1=Hello! Welcome to our support chat.

ASSISTANT_WELCOME_PROMPT_2

• Required: No
• Description: Alternative welcome message
• Example: ASSISTANT_WELCOME_PROMPT_2=I'm here to help with your questions.

Session Management

SESSION_TIMEOUT_MINUTES

• Required: No
• Description: User session timeout in minutes
• Example: SESSION_TIMEOUT_MINUTES=480 (8 hours)

Email Configuration

EMAIL_FROM

• Required: Yes
• Description: From email address for system emails
• Example: EMAIL_FROM=noreply@chatbot.example.com

Widget Security (JWE)

WIDGET_JWE_ENCRYPTION_PRIVATE_KEY

@deprecated Use workspaces instead

• Required: When using embeddable_chat feature
• Description: Private key for widget JWE encryption
• Setup: Generate RSA private key for secure widget communication
• Format: Base64-encoded RSA private key

WIDGET_JWE_SIGNING_PUBLIC_KEY

@deprecated Use workspaces instead

• Required: When using embeddable_chat feature
• Description: Public key for widget JWE signing verification
• Setup: Extract public key from the private key
• Format: Base64-encoded RSA public key

OpenID Connect Authentication

OPENID_CONNECT_CLIENT_ID

• Required: When using OpenID Connect authentication
• Description: Client ID for OpenID Connect provider
• Example: OPENID_CONNECT_CLIENT_ID=chatbot-client-123

OPENID_CONNECT_CLIENT_SECRET

• Required: When using OpenID Connect authentication
• Description: Client secret for OpenID Connect provider
• Security: Keep this secret secure
• Example: OPENID_CONNECT_CLIENT_SECRET=abc123secret...

OPENID_CONNECT_ISSUER_URL

• Required: When using OpenID Connect authentication
• Description: OpenID Connect provider's issuer URL
• Example: OPENID_CONNECT_ISSUER_URL=https://auth.example.com

OPENID_CONNECT_ISSUER_NAME

• Required: When using OpenID Connect authentication
• Description: Display name for the OpenID Connect provider
• Example: OPENID_CONNECT_ISSUER_NAME=Company SSO

OPENID_CONNECT_ROLES_ENABLED

• Required: No
• Description: Enable role-based access control from OpenID Connect
• Options: true, false
• Example: OPENID_CONNECT_ROLES_ENABLED=true

AI Provider Configuration

OPENAI_API_KEY

• Required: When using OpenAI models
• Description: API key for OpenAI services
• Security: Keep this key secure
• Example: OPENAI_API_KEY=sk-...

GEMINI_API_KEY

• Required: When using Gemini models
• Description: API key for Google Gemini
• Security: Keep this key secure
• Example: GEMINI_API_KEY=AIza...

ANTHROPIC_API_KEY

• Required: When using Claude models
• Description: API key for Anthropic Claude
• Security: Keep this key secure
• Example: ANTHROPIC_API_KEY=sk-ant-...

YOUTUBE_API_KEY

• Required: When processing YouTube videos
• Description: API key for YouTube Data API (for video processing)
• Example: YOUTUBE_API_KEY=AIza...

LLM Configuration

LLM_DEFAULT_MODEL

• Required: No
• Description: Default language model for chat responses
• Example: LLM_DEFAULT_MODEL=gpt-4.1

LLM_DEFAULT_EMBEDDING_MODEL

• Required: No
• Description: Default model for text embeddings
• Example: LLM_DEFAULT_EMBEDDING_MODEL=text-embedding-3-small

LLM_DEFAULT_IMAGE_MODEL

• Required: No
• Description: Default model for image generation
• Example: LLM_DEFAULT_IMAGE_MODEL=dall-e-2

LLM_METADATA_GENERATION_MODEL

• Required: No
• Description: Specific model for generating document metadata
• Example: LLM_METADATA_GENERATION_MODEL=gpt-4o-mini

LLM_CONTEXTUAL_CHUNK_MODEL

• Required: No
• Description: Model for contextual chunk processing and enhancement
• Example: LLM_CONTEXTUAL_CHUNK_MODEL=gpt-4o-mini

LLM_TRANSLATION_MODEL

• Required: No
• Description: Model for translating document chunks (when documents_translation feature is enabled)
• Example: LLM_TRANSLATION_MODEL=gpt-4o-mini

LLM_MAX_RETRIES

• Required: No
• Description: Maximum number of retries for LLM API calls
• Example: LLM_MAX_RETRIES=5

LLM_RETRY_INTERVAL

• Required: No
• Description: Interval between retries in seconds
• Example: LLM_RETRY_INTERVAL=0.5

Observability - Langfuse

LANGFUSE_PUBLIC_KEY

• Required: Yes
• Description: Public key for Langfuse LLM observability
• Example: LANGFUSE_PUBLIC_KEY=pk-lf-...

LANGFUSE_SECRET_KEY

• Required: Yes
• Description: Secret key for Langfuse
• Security: Keep this key secure
• Example: LANGFUSE_SECRET_KEY=sk-lf-...

LANGFUSE_DOMAIN

• Required: No
• Description: Langfuse instance domain
• Example: LANGFUSE_DOMAIN=https://langfuse.example.com

LANGFUSE_API_PATH

• Required: No
• Description: API path for Langfuse
• Example: LANGFUSE_API_PATH=/api/public

Error Tracking - Sentry

SENTRY_DSN

• Required: Yes
• Description: Sentry Data Source Name for error tracking
• Required: When using Sentry for error monitoring
• Example: SENTRY_DSN=https://...@sentry.io/...

SENTRY_TRACES_SAMPLE_RATE

• Required: No
• Description: Sample rate for Sentry performance monitoring (0.0 to 1.0)
• Example: SENTRY_TRACES_SAMPLE_RATE=0.1 (10% sampling)

Storage Configuration

ACTIVE_STORAGE_CONFIG

• Required: When using non-local disk storage
• Description: Base64-encoded JSON configuration for Active Storage
• Reference: See ./storage-configuration.md for detailed setup

Development and Debugging

RUBYLLM_DEBUG

• Required: No
• Description: Enable debug logging for RubyLLM gem
• Options: true, false
• Example: RUBYLLM_DEBUG=false

FRONTEND_CHAT_DEBUG

• Required: No
• Description: Enable debug mode for frontend chat
• Options: true, false
• Example: FRONTEND_CHAT_DEBUG=true

Document Processing - Docling

DOCLING_URL

• Required: Yes
• Description: URL for Docling document processing service
• Example: DOCLING_URL=http://docling-service:5001

DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT

• Required: No
• Description: Maximum timeout for document processing (seconds)
• Example: DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT=2400

DOCLING_SERVE_MAX_SYNC_WAIT

• Required: No
• Description: Maximum wait time for synchronous processing (seconds)
• Example: DOCLING_SERVE_MAX_SYNC_WAIT=1800

Database Configuration

DATABASE_URL

• Required: Yes
• Description: PostgreSQL database connection URL
• Format: postgresql://username:password@host:port/database
• Example: DATABASE_URL=postgresql://user:pass@db.example.com:5432/chatbot_prod