Skip to main content

Core Application Variables

Essential environment variables for Chatty AI application configuration.

Required Variables​

These variables MUST be set before deployment.

Domain Configuration​

CHATTYAI_DOMAIN​

  • Type: String (domain or IP)
  • Required: ✅ Yes
  • Example: chat.example.com or 192.168.1.100
  • Description: Primary domain or IP address for Chatty AI web interface
  • Usage: If using domain, HTTPS will be configured. If using IP, HTTP with port will be used.

N8N_DOMAIN​

  • Type: String (domain or IP)
  • Required: ✅ Yes
  • Example: n8n.example.com or 192.168.1.100
  • Description: Domain or IP address for n8n workflow automation interface

DATABASES_DOMAIN​

  • Type: String (domain or IP)
  • Required: ✅ Yes
  • Example: databases.example.com or 192.168.1.100
  • Description: Domain or IP address for Databases interface

Security & Secrets​

CHATTYAI_JWT_SECRET_KEY​

  • Type: String (secret key)
  • Required: ✅ Yes
  • Security: 🔴 CRITICAL
  • Length: 32+ characters
  • Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  • Description: Secret key for signing JWT authentication tokens
  • Generate: 
    openssl rand -hex 32
  • ⚠️ Never share or commit to version control

CHATTYAI_API_KEY​

  • Type: String (API key)
  • Required: ✅ Yes
  • Security: 🔴 HIGH
  • Example: sk-chattyai-1234567890abcdef
  • Description: API key for Chatty AI integrations and n8n workflows
  • Generate: 
    echo "sk-chattyai-$(openssl rand -hex 16)"

CHATTYAI_AI_API_KEY​

  • Type: String (API key)
  • Required: ✅ Yes (unless using local Ollama)
  • Security: 🔴 HIGH
  • Example: sk-proj-abc123... (OpenAI format)
  • Description: API key for LLM service (OpenAI, Azure, LiteLLM, etc.)
  • Usage: Used for chat completions and embeddings

Admin Account​

CHATTYAI_ADMIN_EMAIL​

  • Type: String (email)
  • Required: No
  • Default: admin@example.com
  • Example: admin@company.com
  • Description: Email address for admin user (auto-created on first startup)

CHATTYAI_ADMIN_NAME​

  • Type: String
  • Required: No
  • Default: Admin
  • Example: System Administrator
  • Description: Display name for admin user

CHATTYAI_ADMIN_PASSWORD​

  • Type: String (password)
  • Required: ✅ Yes
  • Security: 🔴 HIGH
  • Example: Admin@2024!Secure
  • Description: Password for admin user account
  • Best Practice: Use strong password (16+ characters, mixed case, numbers, symbols)

Application Settings​

CHATTYAI_NAME​

  • Type: String
  • Required: No
  • Default: Chatty AI
  • Example: Company AI Assistant
  • Description: Display name shown in UI header and branding

ENABLE_API_KEYS​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Enable API key generation for users
  • Note: Required for n8n integration and external API access

MAX_USERS​

  • Type: Integer
  • Required: No
  • Default: 0 (unlimited)
  • Example: 50
  • Description: Maximum number of users (excluding global admin)
  • Note: 0 = unlimited

LLM Configuration​

CHATTYAI_AI_API_BASE_URL​

  • Type: String (URL)
  • Required: No
  • Default: https://llm.chatty-ai.ai
  • Example:
    • https://api.openai.com/v1
    • https://your-litellm.com
    • http://localhost:11434 (Ollama)
  • Description: Base URL for OpenAI-compatible LLM API endpoint
  • Supported: OpenAI, Azure OpenAI, LiteLLM, vLLM, Ollama

ENABLE_OLLAMA_API​

  • Type: Boolean
  • Required: No
  • Default: false
  • Values: true or false
  • Description: Enable Ollama integration for local LLM models

Service URLs​

Full URLs for each service (must be set manually):

CHATTYAI_URL​

  • Type: String (URL)
  • Required: ✅ Yes
  • Format: https://DOMAIN or http://IP:PORT
  • Example:
    • https://chat.example.com (with domain)
    • http://192.168.1.100:3000 (with IP)
  • Description: Full URL for Chatty AI application
  • Note: Must match CHATTYAI_DOMAIN

N8N_URL​

  • Type: String (URL)
  • Required: ✅ Yes
  • Format: https://DOMAIN or http://IP:PORT
  • Example:
    • https://n8n.example.com (with domain)
    • http://192.168.1.100:5678 (with IP)
  • Description: Full URL for n8n interface
  • Note: Must match N8N_DOMAIN

DATABASES_URL​

  • Type: String (URL)
  • Required: ✅ Yes
  • Format: https://DOMAIN or http://IP:PORT
  • Example:
    • https://databases.example.com (with domain)
    • http://192.168.1.100:8000 (with IP)
  • Description: Full URL for Databases interface
  • Note: Must match DATABASES_DOMAIN

Docker Image Versions​

CHATTYAI_VERSION​

  • Type: String (tag)
  • Required: No
  • Default: arm64
  • Example: arm64, amd64, arm64-v4.0.2, latest
  • Description: Docker image tag for Chatty AI application
  • Image: ghcr.io/chattyai-org/chatty-app:${CHATTYAI_VERSION}

PIPELINES_VERSION​

  • Type: String (tag)
  • Required: No
  • Default: amd64
  • Example: arm64, amd64, latest
  • Description: Docker image tag for AI pipelines service
  • Image: ghcr.io/chattyai-org/chattyai-pipelines:${PIPELINES_VERSION}

N8N_VERSION​

  • Type: String (tag)
  • Required: No
  • Default: amd64
  • Example: arm64, amd64, latest
  • Description: Docker image tag for n8n with Chatty AI customizations
  • Image: ghcr.io/chattyai-org/chatty-app-n8n:${N8N_VERSION}

Port Configuration​

CHATTYAI_PORT​

  • Type: Integer
  • Required: No
  • Default: 3000
  • Example: 3000
  • Description: Port for Chatty AI web interface (when using IP-based deployment)
  • Note: Only used when CHATTYAI_DOMAIN is an IP address

N8N_PORT​

  • Type: Integer
  • Required: No
  • Default: 5678
  • Example: 5678
  • Description: Port for n8n web interface

DATABASES_PORT​

  • Type: Integer
  • Required: No
  • Default: 8000
  • Example: 8000
  • Description: Port for Databases UI (when using IP-based deployment)

n8n Workflow Automation​

N8N_ENABLED​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Enable n8n integration in Chatty AI UI
  • Used in: chattyai service

N8N_API_KEY​

  • Type: String (API key)
  • Required: Yes
  • Default: Uses CHATTYAI_API_KEY
  • Security: 🔴 HIGH - Keep secret
  • Example: sk-n8n-1234567890abcdef
  • Description: API key for n8n workflows (typically same as CHATTYAI_API_KEY)
  • Used in: chattyai service

N8N_USER_MANAGEMENT_DISABLED​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Disable n8n's built-in user management (uses Chatty AI auth)
  • Used in: n8n service
  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Require secure cookies (HTTPS) for n8n sessions
  • Used in: n8n service

N8N_DIAGNOSTICS_ENABLED​

  • Type: Boolean
  • Required: No
  • Default: false
  • Values: true or false
  • Description: Enable n8n diagnostics and telemetry
  • Used in: n8n service

N8N_PERSONALIZATION_ENABLED​

  • Type: Boolean
  • Required: No
  • Default: false
  • Values: true or false
  • Description: Enable n8n personalization features
  • Used in: n8n service

RAG Configuration​

RAG_TOP_K​

  • Type: Integer
  • Required: No
  • Default: 20
  • Example: 20
  • Description: Number of document chunks to retrieve from vector database
  • Range: 1-100 (higher = more context, slower)
  • Used in: chattyai service

RAG_TOP_K_RERANKER​

  • Type: Integer
  • Required: No
  • Default: 5
  • Example: 5
  • Description: Number of results after reranking (final results sent to LLM)
  • Range: 1-20 (should be ≤ RAG_TOP_K)
  • Used in: chattyai service

RAG_RELEVANCE_THRESHOLD​

  • Type: Float
  • Required: No
  • Default: 0
  • Example: 0.7
  • Description: Minimum relevance score for retrieved chunks (0.0 = no threshold)
  • Range: 0.0-1.0
  • Used in: chattyai service
  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Enable hybrid search (combines vector similarity + keyword BM25)
  • Benefit: Better retrieval accuracy
  • Used in: chattyai service

RAG_EMBEDDING_MODEL​

  • Type: String
  • Required: No
  • Default: text-embedding-3-large
  • Example: text-embedding-3-large, text-embedding-ada-002
  • Description: Model name for embeddings
  • Used in: chattyai service

CHUNK_SIZE​

  • Type: Integer
  • Required: No
  • Default: 512
  • Example: 512
  • Description: Size of document chunks (in tokens or characters)
  • Range: 100-2000
  • Used in: chattyai service

CHUNK_OVERLAP​

  • Type: Integer
  • Required: No
  • Default: 100
  • Example: 100
  • Description: Overlap between consecutive chunks
  • Range: 0-500 (should be < CHUNK_SIZE)
  • Used in: chattyai service

File Storage​

FILE_KEEP_SOURCE​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Keep original uploaded files after processing
  • Used in: chattyai service

FILE_RETENTION_DAYS​

  • Type: Integer
  • Required: No
  • Default: 14
  • Example: 14, 30, 90
  • Description: Number of days to retain uploaded files
  • Used in: chattyai service

ENABLE_DEFAULT_WEBSEARCH_TOOL​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Automatically enable websearch tool for all models
  • Used in: chattyai service

DEFAULT_WEBSEARCH_TOOL_ID​

  • Type: String
  • Required: No
  • Default: web_search
  • Example: web_search
  • Description: Tool ID for websearch (must match installed tool)
  • Used in: chattyai service

DEFAULT_WEBSEARCH_MODEL​

  • Type: String
  • Required: No
  • Default: chattyAI-search-model
  • Example: chattyAI-search-model, chattyAI-search-model2
  • Description: Model to use for websearch queries
  • Used in: chattyai service

Databases​

ENABLE_DATABASES​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Enable/disable the Databases feature (natural language to SQL)
  • Used in: chattyai service

DATABASES_GENERATION_MODEL​

  • Type: String
  • Required: No
  • Default: gpt-4o-mini
  • Example: gpt-4o-mini, gpt-4, gpt-3.5-turbo
  • Description: LLM model used for SQL generation in Databases
  • Used in: chattydatabases-ai-service, chattydatabases

DATABASES_VERSION​

  • Type: String (tag)
  • Required: No
  • Default: amd64
  • Example: arm64, amd64, latest
  • Description: Docker image tag for Databases UI
  • Image: ghcr.io/chattyai-org/chatty-app-databases:${DATABASES_VERSION}

DATABASES_AI_VERSION​

  • Type: String (tag)
  • Required: No
  • Default: arm64
  • Example: arm64, amd64, latest
  • Description: Docker image tag for Databases AI service
  • Image: ghcr.io/chattyai-org/chatty-app-databases-ai-service:${DATABASES_AI_VERSION}

ChattyAI App Servers (MS365 & Jira)​

CHATTY_APP_SHOW_APPS​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Show/hide entire ChattyAI apps section in admin UI
  • Effect: Controls visibility of pre-configured MS365 and Jira integrations
  • Used in: chattyai service

CHATTY_APP_AUTO_CONNECT_ON_STARTUP​

  • Type: Boolean
  • Required: No
  • Default: false
  • Values: true or false
  • Description: Auto-connect all ChattyAI apps on startup
  • Effect:
    • true: Create DB instances (users can customize enable/disable, access grants)
    • false: Apps are purely dynamic from env vars (no DB storage)
  • Used in: chattyai service

CHATTY_APP_MS365_OAUTH_CLIENT_ID​

  • Type: String (UUID)
  • Required: Yes (for MS365 apps)
  • Default: 830a4b0b-e149-46f2-8840-a983dad84cdd (ChattyAI official)
  • Example: 830a4b0b-e149-46f2-8840-a983dad84cdd
  • Description: Azure App Registration Client ID for Microsoft 365 services
  • Services: Outlook, OneDrive, Excel, OneNote, To Do, Planner, Teams, SharePoint, Calendar
  • Security: 🔴 CRITICAL - These credentials are managed by ChattyAI vendor
  • Note: ⚠️ DO NOT CHANGE - Uses ChattyAI's multitenant Azure app
  • Portainer Only: These values are pre-configured by vendor and cannot be manually set
  • Used in: chattyai service

CHATTY_APP_MS365_OAUTH_CLIENT_SECRET​

  • Type: String (secret)
  • Required: Yes (for MS365 apps)
  • Default: Yz58Q~vx5DB5aDg1iAThLm3WVRVw8ZApB6nVkbn5 (ChattyAI official)
  • Security: 🔴 CRITICAL - Vendor-managed secret, keep secure
  • Example: Yz58Q~vx5DB5aDg1iAThLm3WVRVw8ZApB6nVkbn5
  • Description: Azure App Registration Client Secret for Microsoft 365 services
  • Note: ⚠️ DO NOT CHANGE - Uses ChattyAI's multitenant Azure app
  • Portainer Only: This value is pre-configured by vendor and cannot be manually set
  • Access: Only accessible through Portainer environment variables (vendor-managed)
  • Used in: chattyai service

⚠️ SECURITY NOTICE:

  • These MS365 credentials are vendor-managed and pre-configured in Portainer deployments
  • Customers cannot and should not modify these values manually
  • The credentials are stored securely in Portainer environment variables
  • Only the vendor has access to modify these credentials
  • For Docker Compose deployments, customers must use their own Azure App Registration

CHATTY_APP_MS365_OAUTH_TENANT_ID​

  • Type: String
  • Required: No
  • Default: common
  • Example: common or 12345678-1234-1234-1234-123456789012
  • Description: Azure tenant ID for MS365 OAuth. "common" allows any Microsoft account
  • Used in: chattyai service

Advanced Settings​

CHATTYAI_NAME​

  • Type: String
  • Required: No
  • Default: Chatty AI
  • Example: Company AI Assistant
  • Description: Display name shown in the UI header and branding
  • Used in: chattyai service

ENABLE_API_KEYS​

  • Type: Boolean
  • Required: No
  • Default: true
  • Values: true or false
  • Description: Enable API key generation for users (required for n8n integration and external API access)
  • Used in: chattyai service

MAX_USERS​

  • Type: Integer
  • Required: No
  • Default: 0 (unlimited)
  • Example: 50
  • Description: Maximum number of users (excluding global admin). 0 = unlimited
  • Used in: chattyai service

NODE_MAX_MEMORY​

  • Type: Integer (MB)
  • Required: No
  • Default: 8192
  • Example: 8192, 16384
  • Description: Maximum memory (MB) for Node.js processes
  • Range: 2048-32768 (depends on available RAM)
  • Used in: chattyai service

CORS_ALLOW_ORIGIN​

  • Type: String
  • Required: No
  • Default: *
  • Example: *, https://example.com
  • Description: CORS allowed origins for API requests
  • Security: ⚠️ Use specific origins in production, not *
  • Used in: chattyai service

Quick Reference​

Minimal Required Configuration​

# Domains
CHATTYAI_DOMAIN=chat.example.com
N8N_DOMAIN=n8n.example.com
DATABASES_DOMAIN=databases.example.com

# URLs (must match domains)
CHATTYAI_URL=https://chat.example.com
N8N_URL=https://n8n.example.com
DATABASES_URL=https://databases.example.com

# Database
DB_PASSWORD=$(openssl rand -base64 32)

# Security
CHATTYAI_JWT_SECRET_KEY=$(openssl rand -hex 32)
CHATTYAI_API_KEY=sk-chattyai-$(openssl rand -hex 16)
CHATTYAI_AI_API_KEY=sk-proj-your-llm-api-key

# Admin
CHATTYAI_ADMIN_EMAIL=admin@company.com
CHATTYAI_ADMIN_PASSWORD=YourSecurePassword123!

Next Steps​