Skip to main content

​
Overview

Vega AI can be configured using environment variables. Most settings have sensible defaults and only need to be overridden for specific use cases.

​
Configuration Priority

Vega AI reads configuration in this order (later sources override earlier ones):
  1. Default values (built into application)
  2. Environment variables
  3. Environment variables from files (using _FILE suffix)

​
Required Settings

These variables are required for Vega AI to function:

​
GEMINI_API_KEY

  • Description: Google Gemini API key for AI features (document generation, job matching, CV parsing)
  • Required: Yes
  • Default: None
  • Example: GEMINI_API_KEY=AIzaSyB...
  • Get API Key: Google AI Studio
GEMINI_API_KEY=your-gemini-api-key-here

​
TOKEN_SECRET

  • Description: Secret key for signing JWT tokens (authentication)
  • Required: Highly recommended for production
  • Default: Auto-generated (not recommended for production)
  • Example: TOKEN_SECRET=your-super-secret-jwt-key-here
  • Generate: openssl rand -base64 32
TOKEN_SECRET=your-super-secret-jwt-key-here
Always set TOKEN_SECRET in production. Using the default or auto-generated value will invalidate all user sessions when the container restarts.

​
Optional Settings

​
Admin User Configuration

​
ADMIN_USERNAME

  • Description: Username for the default admin account (created on first startup)
  • Default: admin
  • Example: ADMIN_USERNAME=myadmin
ADMIN_USERNAME=admin

​
ADMIN_PASSWORD

  • Description: Password for the default admin account
  • Default: VegaAdmin
  • Example: ADMIN_PASSWORD=MySecurePassword123
ADMIN_PASSWORD=VegaAdmin
Change the default password immediately after first login via Settings → Account.

​
RESET_ADMIN_PASSWORD

  • Description: Reset admin password to the value in ADMIN_PASSWORD on startup
  • Default: false
  • Values: true, false
RESET_ADMIN_PASSWORD=true

​
Security Settings

  • Description: Require HTTPS for authentication cookies
  • Default: true (production), false (development)
  • Values: true, false
  • Use Case: Set to false only for local development without HTTPS
COOKIE_SECURE=true
  • Description: Domain for authentication cookies
  • Default: None (uses request domain)
  • Example: COOKIE_DOMAIN=yourdomain.com
  • Use Case: Cross-subdomain authentication
COOKIE_DOMAIN=yourdomain.com

​
ACCESS_TOKEN_EXPIRY

  • Description: Access token expiry time in minutes
  • Default: 60 (1 hour)
  • Example: ACCESS_TOKEN_EXPIRY=30
ACCESS_TOKEN_EXPIRY=60

​
REFRESH_TOKEN_EXPIRY

  • Description: Refresh token expiry time in hours
  • Default: 72 (3 days)
  • Example: REFRESH_TOKEN_EXPIRY=168
REFRESH_TOKEN_EXPIRY=72

​
OAuth Configuration

OAuth settings are only needed if you want to enable Google social login.

​
GOOGLE_CLIENT_ID

  • Description: Google OAuth client ID
  • Required: Only for Google OAuth
  • Default: None
  • Example: GOOGLE_CLIENT_ID=123456789-abc...apps.googleusercontent.com
GOOGLE_CLIENT_ID=your-google-client-id-here

​
GOOGLE_CLIENT_SECRET

  • Description: Google OAuth client secret
  • Required: Only for Google OAuth
  • Default: None
  • Example: GOOGLE_CLIENT_SECRET=GOCSPX-...
GOOGLE_CLIENT_SECRET=your-google-client-secret-here

​
GOOGLE_CLIENT_REDIRECT_URL

  • Description: OAuth redirect URL for Google authentication
  • Default: http://localhost:8765/auth/google/callback
  • Example: GOOGLE_CLIENT_REDIRECT_URL=https://yourdomain.com/auth/google/callback
GOOGLE_CLIENT_REDIRECT_URL=http://localhost:8765/auth/google/callback

​
CORS Configuration

​
CORS_ALLOWED_ORIGINS

  • Description: Comma-separated list of allowed CORS origins
  • Default: * (production), http://localhost:* (development)
  • Example: CORS_ALLOWED_ORIGINS=https://app.example.com,https://example.com
CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

​
Cloud Mode Features

​
CLOUD_MODE

  • Description: Enable cloud-native features (usage quotas, multi-tenancy)
  • Default: false
  • Values: true, false
  • Use Case: Set to true for managed cloud deployments
CLOUD_MODE=false
Cloud mode is designed for the hosted version at vega.benidevo.com. Self-hosted users should keep this disabled.

​
Development Settings

​
IS_DEVELOPMENT

  • Description: Enable development mode (verbose logging, hot reload)
  • Default: false
  • Values: true, false
IS_DEVELOPMENT=false

​
LOG_LEVEL

  • Description: Application log level
  • Default: info (production), debug (development)
  • Values: debug, info, warn, error
LOG_LEVEL=info

​
Database Configuration

​
DB_CONNECTION_STRING

  • Description: SQLite database connection string with optimized settings
  • Default: /app/data/vega.db?_journal_mode=WAL&_busy_timeout=5000&_foreign_keys=ON&_cache_size=10000&_synchronous=NORMAL
  • Example: /custom/path/vega.db?_journal_mode=WAL&_busy_timeout=5000
DB_CONNECTION_STRING=/app/data/vega.db?_journal_mode=WAL&_busy_timeout=5000&_foreign_keys=ON&_cache_size=10000&_synchronous=NORMAL
Only change this if you need a custom database path. The default includes optimized SQLite settings.

​
File-Based Configuration (Docker Secrets)

Vega AI supports reading sensitive configuration from files using the _FILE suffix pattern. This is ideal for Docker Secrets.

​
Supported _FILE Variables

  • GEMINI_API_KEY_FILE
  • TOKEN_SECRET_FILE
  • ADMIN_PASSWORD_FILE
  • GOOGLE_CLIENT_SECRET_FILE

​
Usage with Docker Secrets

docker-compose.yml
services:
  vega-ai:
    image: ghcr.io/benidevo/vega-ai:latest
    environment:
      - GEMINI_API_KEY_FILE=/run/secrets/gemini_api_key
      - TOKEN_SECRET_FILE=/run/secrets/token_secret
      - ADMIN_PASSWORD_FILE=/run/secrets/admin_password
    secrets:
      - gemini_api_key
      - token_secret
      - admin_password

secrets:
  gemini_api_key:
    external: true
  token_secret:
    external: true
  admin_password:
    external: true
Create secrets: 
echo "your-api-key" | docker secret create gemini_api_key -
echo "your-token-secret" | docker secret create token_secret -
echo "your-password" | docker secret create admin_password -

​
Security Features

  • Path validation: Prevents directory traversal attacks
  • Size limits: Maximum 1MB per secret file
  • Priority: _FILE variables override regular environment variables

​
Configuration Examples

​
Minimal Self-Hosted Setup

.env
# Required
GEMINI_API_KEY=your-gemini-api-key
.env
# Required
GEMINI_API_KEY=your-gemini-api-key
TOKEN_SECRET=your-super-secret-jwt-key

# Admin credentials
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123

# Security
COOKIE_SECURE=true
ACCESS_TOKEN_EXPIRY=60
REFRESH_TOKEN_EXPIRY=72

# Logging
LOG_LEVEL=info

​
Production with Custom CORS

.env
# Required
GEMINI_API_KEY=your-gemini-api-key
TOKEN_SECRET=your-super-secret-jwt-key

# Admin credentials
ADMIN_PASSWORD=YourSecurePassword123

# CORS for custom domain
CORS_ALLOWED_ORIGINS=https://vega.yourdomain.com,https://yourdomain.com
COOKIE_DOMAIN=yourdomain.com
COOKIE_SECURE=true

# Security
ACCESS_TOKEN_EXPIRY=60
REFRESH_TOKEN_EXPIRY=72

​
Development Setup

.env
# Required
GEMINI_API_KEY=your-gemini-api-key
TOKEN_SECRET=dev-secret-key

# Development mode
IS_DEVELOPMENT=true
LOG_LEVEL=debug

# Security (relaxed for local dev)
COOKIE_SECURE=false

# Admin (use defaults)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=VegaAdmin

​
Complete Configuration Template

.env
# =============================================================================
# REQUIRED SETTINGS
# =============================================================================

# AI Provider Configuration
GEMINI_API_KEY=your-gemini-api-key

# JWT Token Secret
TOKEN_SECRET=your-super-secret-jwt-key

# =============================================================================
# ADMIN USER CONFIGURATION
# =============================================================================

ADMIN_USERNAME=admin
ADMIN_PASSWORD=VegaAdmin
RESET_ADMIN_PASSWORD=false

# =============================================================================
# SECURITY SETTINGS
# =============================================================================

COOKIE_SECURE=true
COOKIE_DOMAIN=
ACCESS_TOKEN_EXPIRY=60
REFRESH_TOKEN_EXPIRY=72

# =============================================================================
# OAUTH CONFIGURATION (Optional)
# =============================================================================

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CLIENT_REDIRECT_URL=http://localhost:8765/auth/google/callback

# =============================================================================
# CORS CONFIGURATION
# =============================================================================

CORS_ALLOWED_ORIGINS=*

# =============================================================================
# CLOUD MODE FEATURES
# =============================================================================

CLOUD_MODE=false

# =============================================================================
# DEVELOPMENT SETTINGS
# =============================================================================

IS_DEVELOPMENT=false
LOG_LEVEL=info

# =============================================================================
# DATABASE CONFIGURATION
# =============================================================================

# DB_CONNECTION_STRING=/app/data/vega.db?_journal_mode=WAL&_busy_timeout=5000&_foreign_keys=ON&_cache_size=10000&_synchronous=NORMAL

​
Validation and Troubleshooting

​
Verify Environment Variables

# Inspect container environment
docker inspect vega-ai --format='{{range .Config.Env}}{{println .}}{{end}}'

# Or with Docker Compose
docker compose config

​
Common Issues

​
Variables Not Loading

  1. Check .env file syntax:
    • No spaces around = signs
    • No quotes around values (unless part of the value)
    • One variable per line
    # WRONG
GEMINI_API_KEY = "value"

# RIGHT
GEMINI_API_KEY=value
  2. Verify file is being loaded: 
    # Docker Compose
docker compose config

# Docker Swarm
docker-compose config | grep -A 5 environment

​
Authentication Issues

  1. TOKEN_SECRET not set: Sessions will be invalidated on restart
  2. ADMIN_PASSWORD not applied: Use RESET_ADMIN_PASSWORD=true to force reset

​
CORS Errors

  1. Check CORS_ALLOWED_ORIGINS: Must include your frontend domain
  2. Verify format: Comma-separated, no spaces
  3. Check protocol: Must match exactly (http vs https)
# Multiple origins
CORS_ALLOWED_ORIGINS=https://app.example.com,https://example.com

​
Best Practices

1

Use .env files

Store configuration in .env files, never hardcode in compose files
2

Generate secure secrets

Always generate secure random values for TOKEN_SECRET:
openssl rand -base64 32
3

Use Docker Secrets in production

For production Swarm deployments, use Docker Secrets instead of environment variables
4

Never commit secrets

Add .env to .gitignore. Use .env.example as a template
5

Change default passwords

Always change ADMIN_PASSWORD from the default value
6

Enable security features

Set COOKIE_SECURE=true and configure CORS_ALLOWED_ORIGINS in production

​
Next Steps

Docker Deployment

Deploy Vega AI with Docker

Docker Compose

Use Docker Compose for easier management

Docker Swarm

Scale with Docker Swarm

Build docs developers (and LLMs) love

Get started for freeTalk to us