Configuration¶

The RAG Chatbot is configured through environment variables. This guide covers all available settings.

Tenant Configuration¶

Each tenant has its own .env file in a dedicated directory:

/var/www/chatbot/tenants/<tenant-id>/.env

Create tenants using the CLI:

php cli/tenant.php create my-tenant --name="My Organization"

This generates the .env file with auto-generated API keys. Edit the tenant config to customize settings:

nano /var/www/chatbot/tenants/my-tenant/.env

See the Multi-Tenancy Guide for complete setup instructions.

Database Settings¶

Configure the PostgreSQL connection:

# Database host (localhost for same server)
DB_HOST=localhost

# PostgreSQL port (default: 5432)
DB_PORT=5432

# Database name
DB_NAME=ragdb

# Database user
DB_USER=raguser

# Database password (use a strong password!)
DB_PASSWORD=your_secure_password

Security

Never commit .env files to version control. Add .env to your .gitignore file.

LLM Provider Settings¶

Choosing a Provider¶

The chatbot supports two LLM providers for generating responses:

# Options: "openai" or "claude"
LLM_PROVIDER=openai

OpenAI Configuration¶

Required for embeddings (always) and chat (when using OpenAI):

# Your OpenAI API key
OPENAI_API_KEY=sk-your-openai-api-key-here

# Chat model (used when LLM_PROVIDER=openai)
OPENAI_MODEL=gpt-5.2

Available models:

Model	Description
`gpt-5.2`	Most capable, best for complex questions
`gpt-5.2-mini`	Faster, more cost-effective

Embeddings

Embeddings always use OpenAI's text-embedding-3-small model, regardless of which chat provider you choose. This ensures consistent vector dimensions (1536) across your knowledge base.

Claude (Anthropic) Configuration¶

Required when using Claude for chat:

# Your Anthropic API key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

# Claude model version
CLAUDE_MODEL=claude-sonnet-4-20250514

Available models:

Model	Description
`claude-sonnet-4-20250514`	Balanced performance and cost
`claude-opus-4-20250514`	Most capable
`claude-3-haiku-20240307`	Fastest, most economical

Docling Service Settings¶

Configure the document processing service:

# URL where Docling service is running
DOCLING_SERVICE_URL=http://localhost:8001

# Optional API key for authentication
DOCLING_API_KEY=

# Request timeout in seconds (increase for large files)
DOCLING_TIMEOUT=300

# Number of retry attempts on failure
DOCLING_MAX_RETRIES=3

Document Processing Options¶

# Output format: markdown, json, or text
DOCLING_DEFAULT_FORMAT=markdown

# Enable OCR for scanned documents
DOCLING_ENABLE_OCR=true

# Extract tables from documents
DOCLING_ENABLE_TABLES=true

# Analyze document layout/structure
DOCLING_ENABLE_LAYOUT=true

# Detect mathematical formulas
DOCLING_ENABLE_MATH=true

# OCR language (en, de, fr, es, zh, etc.)
DOCLING_OCR_LANGUAGE=en

Upload Settings¶

Configure file upload behavior:

# Maximum upload size in megabytes
MAX_UPLOAD_SIZE_MB=100

# API key to protect upload and media-info endpoints (required)
UPLOAD_API_KEY=your-random-upload-key

All upload and media-info requests must include the header:

X-API-Key: your-upload-api-key

Generate a secure key:

openssl rand -base64 24

Required

UPLOAD_API_KEY must be set. If empty, upload and media-info endpoints will return 401 Unauthorized.

CORS Settings¶

Configure which origins are allowed to make cross-origin requests:

# Comma-separated list of allowed origins
# Example: https://example.com,https://app.example.com
ALLOWED_ORIGINS=https://your-site.com

If ALLOWED_ORIGINS is empty, no CORS headers are sent (cross-origin requests blocked). IPs that send mismatched origins are rate-limited.

Admin Database Settings¶

The admin/widget configuration is stored in a shared chatdb database, separate from per-tenant RAG data:

# Admin Database (shared chatdb)
ADMIN_DB_HOST=localhost
ADMIN_DB_PORT=5432
ADMIN_DB_NAME=chatdb
ADMIN_DB_USER=chatuser
ADMIN_DB_PASSWORD=your_secure_password

Tables in chatdb (schema: tenant_settings): widget_settings, widget_prompts, widget_inquiries, tenant_prompts. All are isolated by tenant_id.

Admin Dashboard Settings¶

Configure admin dashboard authentication:

ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password

Access the dashboard at /admin-dashboard?tenant=<tenant-id>. Uses HTTP Basic Authentication.

Debug Settings¶

Production Warning

Debug features should be disabled in production as they expose sensitive information including API requests and responses.

# Enable API call logging (true/false)
API_DEBUG_LOGGING_ENABLED=false

# Directory for debug logs
API_DEBUG_LOG_PATH=/var/www/chatbot/logs/api_debug

# Credentials for debug interface
API_DEBUG_USERNAME=admin
API_DEBUG_PASSWORD=your_secure_password

# Optional: Restrict debug access to specific IPs
# Comma-separated list, supports CIDR notation
API_DEBUG_IP_WHITELIST=192.168.1.0/24,10.0.0.1

Complete Example¶

Here's a complete .env file for production:

# ===========================================
# Tenant Identification
# ===========================================
TENANT_ID=my-tenant
TENANT_NAME=My Organization

# ===========================================
# Database Configuration (per-tenant RAG data)
# ===========================================
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ragdb
DB_USER=raguser
DB_PASSWORD=super_secure_password_123

# ===========================================
# Admin Database (shared chatdb)
# ===========================================
ADMIN_DB_HOST=localhost
ADMIN_DB_PORT=5432
ADMIN_DB_NAME=chatdb
ADMIN_DB_USER=chatuser
ADMIN_DB_PASSWORD=another_secure_password

# ===========================================
# LLM Provider
# ===========================================
LLM_PROVIDER=openai

# OpenAI (required for embeddings, optional for chat)
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-5.2

# Claude/Anthropic (optional, for chat only)
# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
# CLAUDE_MODEL=claude-sonnet-4-20250514

# ===========================================
# Docling Service
# ===========================================
DOCLING_SERVICE_URL=http://localhost:8001
DOCLING_API_KEY=
DOCLING_TIMEOUT=300
DOCLING_MAX_RETRIES=3
DOCLING_DEFAULT_FORMAT=markdown
DOCLING_ENABLE_OCR=true
DOCLING_ENABLE_TABLES=true
DOCLING_ENABLE_LAYOUT=true
DOCLING_ENABLE_MATH=true
DOCLING_OCR_LANGUAGE=en

# ===========================================
# Upload Settings
# ===========================================
MAX_UPLOAD_SIZE_MB=100
UPLOAD_API_KEY=randomly_generated_key

# ===========================================
# API Keys
# ===========================================
ADMIN_API_KEY=randomly_generated_key
CHAT_API_KEY=randomly_generated_key

# ===========================================
# CORS Allowed Origins
# ===========================================
ALLOWED_ORIGINS=https://your-site.com

# ===========================================
# Admin Dashboard
# ===========================================
ADMIN_USERNAME=admin
ADMIN_PASSWORD=randomly_generated_password

# ===========================================
# Debug (disable in production!)
# ===========================================
API_DEBUG_LOGGING_ENABLED=false
API_DEBUG_LOG_PATH=/var/www/chatbot/logs/api_debug
API_DEBUG_USERNAME=admin
API_DEBUG_PASSWORD=debug_password_123
API_DEBUG_IP_WHITELIST=

Endpoint Toggles¶

Control which API endpoints are available for each tenant. All endpoints are enabled by default.

# Endpoint Toggles (default: true if not set)
ENDPOINT_CHAT_ENABLED=true
ENDPOINT_CUSTOMER_CHAT_ENABLED=true
ENDPOINT_WIDGET_CONFIG_ENABLED=true
ENDPOINT_UPLOAD_ENABLED=true
ENDPOINT_MEDIA_INFO_ENABLED=true
ENDPOINT_ADMIN_ENABLED=true
ENDPOINT_API_DEBUG_ENABLED=true

Variable	Endpoint	Description
`ENDPOINT_CHAT_ENABLED`	`/chat`	Main chat API (requires API key)
`ENDPOINT_CUSTOMER_CHAT_ENABLED`	`/customer-chat`	Public customer widget chat
`ENDPOINT_WIDGET_CONFIG_ENABLED`	`/widget-config`	Widget configuration
`ENDPOINT_UPLOAD_ENABLED`	`/upload`	Document/media uploads
`ENDPOINT_MEDIA_INFO_ENABLED`	`/media-info`	Media URL info lookup
`ENDPOINT_ADMIN_ENABLED`	`/admin/*`	All admin endpoints
`ENDPOINT_API_DEBUG_ENABLED`	`/api-debug/logs`	API debug logs viewer

When an endpoint is disabled, requests return:

HTTP 403
{"error": "The <endpoint> endpoint is disabled for this tenant"}

Use Cases

Disable /upload for read-only tenants
Disable /api-debug in production
Disable /chat if only using customer widget

Validating Configuration¶

Test your tenant configuration:

cd /var/www/chatbot

# Test tenant database connection
php test_db.php my-tenant

# Test OpenAI API key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $(grep OPENAI_API_KEY tenants/my-tenant/.env | cut -d= -f2)"

Environment-Specific Configurations¶

Development¶

API_DEBUG_LOGGING_ENABLED=true
OPENAI_MODEL=gpt-3.5-turbo  # Lower cost for testing

Staging¶

API_DEBUG_LOGGING_ENABLED=true
API_DEBUG_IP_WHITELIST=10.0.0.0/8
OPENAI_MODEL=gpt-5.2

Production¶

API_DEBUG_LOGGING_ENABLED=false
UPLOAD_API_KEY=randomly_generated_key
OPENAI_MODEL=gpt-5.2

Updating Configuration¶

After changing a tenant's .env file (/var/www/chatbot/tenants/<tenant-id>/.env):

No restart required - PHP reads the file on each request
Clear opcache (if enabled) - php -r "opcache_reset();"
Test the changes - Make a test API request with the tenant ID

Next Steps¶

Deploy the Docling service for document processing
Learn about the chat interface
Review security settings