Environment Variables

GoPie uses environment variables for configuration across all components. This guide covers all required and optional environment variables for each service.

Configuration Files

GoPie uses different environment files for different deployment scenarios:

.env - Main configuration file
config-noauth.env - Development configuration without authentication
.env.production - Production-specific overrides

Core Environment Variables

Application Settings

# Application name and environment
APP_NAME=gopie
ENVIRONMENT=development  # development, staging, production

# Server URLs
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CHAT_SERVER_URL=http://localhost:8001
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Feature flags
NEXT_PUBLIC_ENABLE_AUTH=true
NEXT_PUBLIC_ENABLE_VOICE=false
NEXT_PUBLIC_ENABLE_MONITORING=true

Service-Specific Variables

Go Backend Server

# Server configuration
SERVER_PORT=8000
SERVER_HOST=0.0.0.0
SERVER_READ_TIMEOUT=30s
SERVER_WRITE_TIMEOUT=30s

# Database configuration
DATABASE_URL=postgres://gopie:gopie@localhost:5432/gopie?sslmode=disable
DB_MAX_CONNECTIONS=100
DB_MAX_IDLE_CONNECTIONS=10
DB_CONNECTION_MAX_LIFETIME=1h

# Storage configuration
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_NAME=gopie-datasets
S3_REGION=us-east-1
S3_USE_SSL=false

# DuckDB configuration
DUCKDB_PATH=/tmp/gopie.duckdb
DUCKDB_MEMORY_LIMIT=4GB
DUCKDB_THREADS=4

# Authentication (Zitadel)
ZITADEL_DOMAIN=http://localhost:4455
ZITADEL_KEY_PATH=./zitadel/key.json
ZITADEL_PROJECT_ID=your-project-id
ZITADEL_CLIENT_ID=your-client-id

# CORS configuration
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
CORS_ALLOWED_HEADERS=Content-Type,Authorization

Chat Server (Python/FastAPI)

# Server configuration
CHAT_SERVER_HOST=0.0.0.0
CHAT_SERVER_PORT=8001
CHAT_SERVER_WORKERS=4

# AI/LLM configuration
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
DEFAULT_MODEL=gpt-4
TEMPERATURE=0.7
MAX_TOKENS=2000

# Vector database (Qdrant)
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=optional-api-key
QDRANT_COLLECTION_NAME=gopie_schemas
EMBEDDING_MODEL=text-embedding-ada-002
EMBEDDING_DIMENSION=1536

# Agent configuration
AGENT_MAX_ITERATIONS=10
AGENT_TIMEOUT=300  # seconds
ENABLE_PYTHON_EXECUTION=true
PYTHON_SANDBOX_MEMORY_LIMIT=512MB

# Backend integration
BACKEND_URL=http://localhost:8000
BACKEND_API_KEY=internal-api-key

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

Web Frontend (Next.js)

# Public environment variables (exposed to browser)
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CHAT_SERVER_URL=http://localhost:8001
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Authentication
NEXT_PUBLIC_ZITADEL_ISSUER=http://localhost:4455
NEXT_PUBLIC_ZITADEL_CLIENT_ID=your-client-id
NEXT_PUBLIC_ZITADEL_REDIRECT_URI=http://localhost:3000/auth/callback
NEXT_PUBLIC_ZITADEL_POST_LOGOUT_REDIRECT_URI=http://localhost:3000

# Feature toggles
NEXT_PUBLIC_ENABLE_AUTH=true
NEXT_PUBLIC_ENABLE_VOICE=false
NEXT_PUBLIC_ENABLE_CHARTS=true
NEXT_PUBLIC_ENABLE_EXPORT=true

# Analytics and monitoring
NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

# Voice features (LiveKit)
NEXT_PUBLIC_LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your-livekit-api-key
LIVEKIT_API_SECRET=your-livekit-api-secret

# Server-side only variables
DATABASE_URL=postgres://gopie:gopie@localhost:5432/gopie
NEXTAUTH_SECRET=your-nextauth-secret
NEXTAUTH_URL=http://localhost:3000

Infrastructure Services

PostgreSQL

# Database credentials
POSTGRES_USER=gopie
POSTGRES_PASSWORD=gopie
POSTGRES_DB=gopie
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Performance tuning
POSTGRES_MAX_CONNECTIONS=200
POSTGRES_SHARED_BUFFERS=256MB
POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
POSTGRES_WORK_MEM=4MB

MinIO (S3-compatible storage)

# MinIO credentials
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin
MINIO_DOMAIN=localhost
MINIO_SERVER_URL=http://localhost:9000
MINIO_CONSOLE_ADDRESS=:9001

# Bucket configuration
MINIO_DEFAULT_BUCKETS=gopie-datasets:public,gopie-exports:private
MINIO_REGION=us-east-1

Qdrant (Vector Database)

# Qdrant configuration
QDRANT__SERVICE__HTTP_PORT=6333
QDRANT__SERVICE__GRPC_PORT=6334
QDRANT__STORAGE__PATH=/qdrant/storage
QDRANT__LOG_LEVEL=INFO

# Performance settings
QDRANT__STORAGE__PERFORMANCE__MAX_SEARCH_THREADS=8
QDRANT__STORAGE__PERFORMANCE__MAX_OPTIMIZATION_THREADS=2

Zitadel (Authentication)

# Zitadel configuration
ZITADEL_EXTERNALSECURE=false
ZITADEL_EXTERNALPORT=4455
ZITADEL_EXTERNALHOST=localhost
ZITADEL_DATABASE_HOST=localhost
ZITADEL_DATABASE_PORT=5432
ZITADEL_DATABASE_DATABASE=zitadel
ZITADEL_DATABASE_USER_USERNAME=zitadel
ZITADEL_DATABASE_USER_PASSWORD=zitadel

# First instance configuration
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME=admin
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD=Admin123!

Environment-Specific Configurations

Development Environment

# .env.development
ENVIRONMENT=development
LOG_LEVEL=DEBUG
ENABLE_HOT_RELOAD=true
ENABLE_DEBUG_ENDPOINTS=true
DISABLE_RATE_LIMITING=true

Staging Environment

# .env.staging
ENVIRONMENT=staging
LOG_LEVEL=INFO
ENABLE_MONITORING=true
ENABLE_ERROR_TRACKING=true
RATE_LIMIT_REQUESTS=1000
RATE_LIMIT_WINDOW=1h

Production Environment

# .env.production
ENVIRONMENT=production
LOG_LEVEL=WARN
ENABLE_MONITORING=true
ENABLE_ERROR_TRACKING=true
ENABLE_PERFORMANCE_TRACKING=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=15m

# Security
SECURE_COOKIES=true
HTTPS_ONLY=true
HSTS_MAX_AGE=31536000
CSP_POLICY="default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline';"

Security Best Practices

Sensitive Variables

Never commit these variables to version control:

API keys (*_API_KEY, *_SECRET)
Database passwords
JWT secrets
OAuth client secrets
Encryption keys

Variable Management

Use a secrets manager in production:

# AWS Secrets Manager
AWS_SECRETS_MANAGER_REGION=us-east-1
AWS_SECRETS_MANAGER_PREFIX=gopie/

# HashiCorp Vault
VAULT_ADDR=https://vault.example.com
VAULT_TOKEN=your-vault-token
VAULT_PATH=secret/data/gopie

Rotate secrets regularly:

# Rotation configuration
SECRET_ROTATION_DAYS=90
API_KEY_ROTATION_DAYS=30

Use strong passwords:

# Password policy
MIN_PASSWORD_LENGTH=12
REQUIRE_UPPERCASE=true
REQUIRE_LOWERCASE=true
REQUIRE_NUMBERS=true
REQUIRE_SPECIAL_CHARS=true

Validation and Testing

Environment Validation Script

#!/bin/bash
# validate-env.sh

required_vars=(
    "DATABASE_URL"
    "S3_ENDPOINT"
    "QDRANT_URL"
    "OPENAI_API_KEY"
)

missing_vars=()

for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        missing_vars+=("$var")
    fi
done

if [ ${#missing_vars[@]} -ne 0 ]; then
    echo "Missing required environment variables:"
    printf '%s\n' "${missing_vars[@]}"
    exit 1
fi

echo "All required environment variables are set!"

Testing Different Configurations

# Test with no-auth configuration
docker-compose --env-file config-noauth.env up

# Test with production configuration
docker-compose --env-file .env.production up

# Test with custom configuration
export $(cat .env.custom | xargs) && docker-compose up

Troubleshooting

Common Issues

Variable not loaded:
- Check file permissions
- Verify file encoding (UTF-8)
- Look for syntax errors
Wrong variable precedence:
- System environment variables override file variables
- Later files override earlier files
- Command-line variables have highest precedence

Variable interpolation issues:

# Correct
DATABASE_URL="postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}"

# Incorrect (won't interpolate)
DATABASE_URL='postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}'

Next Steps

Learn about Database Setup
Configure Storage
Set up AI Providers
Deploy with Docker or Kubernetes

Environment Variables

On this page