Skip to main content

Environment Variables Overview

How to configure Chatty AI using environment variables.

What is the .env File?​

The .env file contains all configuration settings for your Chatty AI deployment. It's a simple text file with KEY=VALUE pairs that Docker Compose reads when starting containers.

Location: /path/to/chatty-app-deploy/deploy/.env

Creating Your .env File​

Step 1: Copy Example File​

cd chatty-app-deploy/deploy
cp .env.example .env

Step 2: Edit Required Variables​

Open the file:

nano .env

Set the required variables (see sections below for details).

Step 3: Verify Configuration​

Check your settings:

# View domains
grep DOMAIN .env

# Check secrets are set (not default values)
grep -E "JWT_SECRET|API_KEY|PASSWORD" .env

Required vs Optional Variables​

✅ Required Variables​

These MUST be set before deployment:

  • Domains: CHATTYAI_DOMAIN, N8N_DOMAIN, DATABASES_DOMAIN
  • URLs: CHATTYAI_URL, N8N_URL, DATABASES_URL
  • Database: DB_PASSWORD
  • Security: CHATTYAI_JWT_SECRET_KEY, CHATTYAI_API_KEY, CHATTYAI_AI_API_KEY
  • Admin: CHATTYAI_ADMIN_PASSWORD

🔧 Optional Variables​

All other variables have sensible defaults. Only set them if you need to customize:

  • Database settings (user, name, port)
  • LDAP authentication
  • Microsoft SSO
  • Image versions
  • Performance tuning
  • Feature toggles

Variable Categories​

Chatty AI environment variables are organized into categories. Click each section for detailed documentation:

🔑 Core Application Variables​

Domains, URLs, secrets, admin account, LLM configuration, image versions

🗄️ Database Variables​

PostgreSQL connection settings

🔍 Qdrant Variables​

Vector database configuration

🔒 Nginx & TLS Variables​

SSL certificates and nginx settings

👥 LDAP Configuration​

LDAP authentication setup

🔐 SSO Configuration​

Microsoft Entra ID (Azure AD) SSO

📝 Example .env File​

Complete working example

Generating Secrets​

Use these commands to generate secure values:

# JWT Secret (32+ characters)
openssl rand -hex 32

# API Key
echo "sk-chattyai-$(openssl rand -hex 16)"

# Strong Password
openssl rand -base64 32

# Database Password
openssl rand -base64 24

Security Best Practices​

  1. Never commit secrets to version control

    • Use .env file (gitignored)
    • Use Portainer environment variables

  2. Generate strong random values

    • JWT secrets: 32+ characters
    • Passwords: 16+ characters with mixed case, numbers, symbols
    • API keys: Use provided generation commands

  3. Rotate credentials regularly

    • API keys: Every 90 days
    • Passwords: Every 180 days
    • JWT secrets: Annually

  4. Use HTTPS in production

    • Configure proper domains
    • Mount SSL certificates
    • Enable secure cookies

  5. Limit CORS origins

    • Don't use * in production
    • Specify exact allowed origins in CORS_ALLOW_ORIGIN

Environment Variable Priority​

Variables are resolved in this order:

  1. Explicit .env value - Highest priority
  2. Docker-compose default - ${VAR:-default}
  3. Application default - Hardcoded in application

How to Use This Documentation​

  1. Start here to understand how .env files work
  2. Review required variables list above
  3. Visit each category page for detailed variable documentation:
  4. Copy and customize the example for your deployment

Troubleshooting​

.env File Not Loading​

Check file location:

ls -la /path/to/chatty-app-deploy/deploy/.env

Variables Not Taking Effect​

Restart containers after changing .env:

docker compose down
docker compose up -d

Syntax Errors​

Common mistakes:

  • ❌ Spaces around =: KEY = value
  • ✅ No spaces: KEY=value
  • ❌ Quotes in wrong place: KEY="value with spaces
  • ✅ Proper quotes: KEY="value with spaces"
  • ❌ Comments on same line: KEY=value # comment
  • ✅ Comments on separate line: # comment then KEY=value
  • See Example .env File for complete configuration template

Complete Documentation​

For complete, detailed documentation of every environment variable, see: /root/chattyai/chatty-app/deploy/ENV_DOCUMENTATION.md