Configuration Reference

VoiceAssist V2 - Complete Configuration Guide

This document provides comprehensive documentation for all configuration options available in VoiceAssist V2.

Table of Contents

• Environment Variables
• Configuration Validation
• Security Best Practices
• Configuration Examples

Environment Variables

Environment Settings

Usage:

ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=INFO

Validation Rules:

• ENVIRONMENT must be one of: development, staging, production
• DEBUG should be false in production
• LOG_LEVEL should be WARNING or higher in production

Database Configuration

Usage:

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=voiceassist
POSTGRES_PASSWORD=secure_complex_password_min_16_chars
POSTGRES_DB=voiceassist
DATABASE_URL=postgresql://voiceassist:secure_password@postgres:5432/voiceassist

Validation Rules:

• Password must be at least 16 characters
• Password should contain uppercase, lowercase, numbers, special chars
• Use PostgreSQL 16+ with pgvector extension
• Connection string format: postgresql://user:password@host:port/database

Production Recommendations:

• Use connection pooling: Add ?pool_size=20&max_overflow=40 to DATABASE_URL
• Enable SSL: Add ?sslmode=require for production
• Use managed PostgreSQL service (AWS RDS, Google Cloud SQL, etc.)

Redis Configuration

Usage:

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=secure_redis_password_min_16_chars
REDIS_URL=redis://:secure_password@redis:6379/0

Validation Rules:

• Redis 7+ recommended
• Password must be set in production
• Connection string format: redis://[:password@]host:port[/db]

Production Recommendations:

• Use Redis Cluster for high availability
• Enable persistence (AOF + RDB)
• Set maxmemory policy: allkeys-lru
• Use managed Redis (AWS ElastiCache, Redis Cloud, etc.)

Qdrant Vector Database

Usage:

QDRANT_HOST=qdrant
QDRANT_PORT=6333
QDRANT_URL=http://qdrant:6333
QDRANT_COLLECTION=medical_knowledge

Validation Rules:

• Qdrant v1.7+ required
• Collection name must match [a-zA-Z0-9_]+
• Use HTTPS URL in production

Production Recommendations:

• Use Qdrant Cloud for managed service
• Enable authentication with API key
• Configure quantization for cost savings
• Set up replication for high availability

Nextcloud Integration

Usage:

NEXTCLOUD_URL=https://nextcloud.example.com
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=secure_admin_password
NEXTCLOUD_DB_PASSWORD=secure_db_password

Validation Rules:

• Nextcloud 29+ recommended
• Use HTTPS in production
• Admin password should be strong

Production Recommendations:

• Deploy Nextcloud on separate infrastructure
• Use managed database for Nextcloud
• Enable 2FA for admin account
• Configure email for notifications

OpenAI API

Usage:

OPENAI_API_KEY=sk-your-real-api-key-here
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_MAX_TOKENS=512
OPENAI_TEMPERATURE=0.1

Validation Rules:

• API key must start with sk- or sk-proj-
• Model must be available in your OpenAI account
• Temperature must be between 0.0 and 2.0

Cost Management:

• Use gpt-4-turbo-preview for lower costs
• Use text-embedding-3-small (1536 dimensions) instead of large (3072)
• Set reasonable OPENAI_MAX_TOKENS to control costs
• Monitor usage at https://platform.openai.com/usage

Security Configuration

Usage:

SECRET_KEY=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=7
PASSWORD_MIN_LENGTH=12

Generation Commands:

# Generate SECRET_KEY
openssl rand -hex 32

# Generate JWT_SECRET
openssl rand -hex 32

Validation Rules:

• Both secrets must be exactly 64 hex characters (32 bytes)
• Secrets must be different from each other
• Never commit secrets to version control
• Rotate secrets every 90 days in production

HIPAA Compliance:

• Use strong secrets (32+ bytes)
• Rotate tokens regularly
• Log all authentication events
• Implement automatic logout after inactivity

Observability Configuration (Phase 8)

Usage:

ENABLE_METRICS=true
ENABLE_TRACING=true
JAEGER_HOST=jaeger
JAEGER_PORT=6831
LOG_RETENTION_DAYS=90
GRAFANA_ADMIN_PASSWORD=secure_grafana_password

Validation Rules:

• LOG_RETENTION_DAYS must be 30-90 for HIPAA compliance
• Grafana password should be strong

Production Recommendations:

• Keep metrics and tracing enabled
• Use external OTLP collector in production
• Set up Grafana dashboards for monitoring
• Configure AlertManager for critical alerts

Application Settings

Usage:

MAX_UPLOAD_SIZE=104857600  # 100MB
ENABLE_CORS=true
ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
RATE_LIMIT_PER_MINUTE=100

Validation Rules:

• MAX_UPLOAD_SIZE in bytes (100MB = 104857600)
• ALLOWED_ORIGINS should not be * in production
• Rate limit should be tuned based on usage patterns

Configuration Validation

Startup Validation

VoiceAssist validates all configuration on startup. The validation includes:

1. Required Variables: Ensures all required env vars are present
2. Format Validation: Validates formats (URLs, emails, hex strings)
3. Connectivity Tests: Tests connections to PostgreSQL, Redis, Qdrant
4. Secret Strength: Validates secret key strength and uniqueness
5. HIPAA Compliance: Checks retention policies and security settings

Validation Errors

If validation fails, the application will:

• Log detailed error messages
• Exit with non-zero status code
• Provide guidance on how to fix the issue

Example validation error:

ConfigValidationError: JWT_SECRET must be exactly 64 hex characters (got 32)
Fix: Generate a new secret with: openssl rand -hex 32

Security Best Practices

Secret Management

1. Never commit secrets to Git

   # Add to .gitignore
   echo ".env" >> .gitignore

2. Use environment-specific secrets

   • Development: .env.development
   • Staging: .env.staging
   • Production: Use secret manager (AWS Secrets Manager, HashiCorp Vault)

3. Rotate secrets regularly

   • JWT secrets: Every 90 days
   • API keys: When team members leave
   • Database passwords: Every 180 days

4. Use external secret managers in production

   # AWS Secrets Manager example
   aws secretsmanager get-secret-value --secret-id voiceassist/prod/jwt-secret

HIPAA Compliance Checklist

• LOG_RETENTION_DAYS set to 30-90 days
• Strong passwords (16+ characters) for all services
• PHI redaction enabled in logs (automatic in Phase 8)
• TLS/SSL enabled for all external connections
• Access logs enabled and monitored
• Automatic session timeout configured
• Audit logging enabled
• Backup encryption enabled

Configuration Examples

Development Environment

# .env.development
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=DEBUG

# Use Docker Compose hostnames
POSTGRES_HOST=postgres
REDIS_HOST=redis
QDRANT_HOST=qdrant
NEXTCLOUD_URL=http://nextcloud

# Simple passwords for development
POSTGRES_PASSWORD=devpass123
REDIS_PASSWORD=devpass123
JWT_SECRET=$(openssl rand -hex 32)

# Observability
ENABLE_METRICS=true
ENABLE_TRACING=true

Production Environment

# .env.production
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=WARNING

# Production hostnames
POSTGRES_HOST=prod-db.rds.amazonaws.com
POSTGRES_PORT=5432
REDIS_HOST=prod-redis.elasticache.amazonaws.com
REDIS_PORT=6379
QDRANT_URL=https://prod-cluster.qdrant.tech

# Strong secrets from secret manager
SECRET_KEY=${AWS_SECRET_MANAGER:voiceassist/prod/secret-key}
JWT_SECRET=${AWS_SECRET_MANAGER:voiceassist/prod/jwt-secret}
POSTGRES_PASSWORD=${AWS_SECRET_MANAGER:voiceassist/prod/db-password}

# Production URLs
NEXTCLOUD_URL=https://files.example.com
ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com

# HIPAA compliance
LOG_RETENTION_DAYS=90
ACCESS_TOKEN_EXPIRE_MINUTES=15

# Observability
ENABLE_METRICS=true
ENABLE_TRACING=true
JAEGER_HOST=prod-jaeger.example.com

Docker Compose Override

For local development with custom settings:

# docker-compose.override.yml
version: "3.8"

services:
  voiceassist-server:
    environment:
      - DEBUG=true
      - LOG_LEVEL=DEBUG
      - OPENAI_API_KEY=${OPENAI_API_KEY} # From host environment

Troubleshooting

Common Configuration Issues

Issue: "Database connection failed"

Solution:
1. Check POSTGRES_HOST is accessible
2. Verify POSTGRES_PASSWORD is correct
3. Ensure PostgreSQL is running: docker compose ps postgres
4. Check network connectivity: docker compose exec voiceassist-server ping postgres

Issue: "OpenAI API authentication failed"

Solution:
1. Verify OPENAI_API_KEY format (starts with sk-)
2. Check API key is active at https://platform.openai.com/api-keys
3. Ensure sufficient API credits
4. Check for typos in .env file

Issue: "Jaeger trace export failed"

Solution:
1. Check JAEGER_HOST is accessible
2. Verify JAEGER_PORT (default 6831)
3. Ensure Jaeger is running: docker compose ps jaeger
4. Check ENABLE_TRACING=true

Configuration Testing

Validate Configuration

# Check environment variables are set
docker compose exec voiceassist-server env | grep -E "(POSTGRES|REDIS|OPENAI)"

# Test database connection
docker compose exec voiceassist-server python -c "from app.core.database import engine; engine.connect()"

# Test Redis connection
docker compose exec voiceassist-server python -c "from app.core.redis import redis_client; redis_client.ping()"

# Verify secrets are strong
[ ${#JWT_SECRET} -eq 64 ] && echo "JWT_SECRET length OK" || echo "ERROR: JWT_SECRET must be 64 chars"

Health Checks

# Check API health
curl http://localhost:8000/health

# Check readiness (all dependencies)
curl http://localhost:8000/ready

# Check metrics endpoint
curl http://localhost:8000/metrics | grep voiceassist_up

Configuration Schema (JSON Schema)

For programmatic validation, use this JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "VoiceAssist Configuration",
  "type": "object",
  "required": [
    "POSTGRES_HOST",
    "REDIS_HOST",
    "QDRANT_HOST",
    "NEXTCLOUD_URL",
    "OPENAI_API_KEY",
    "SECRET_KEY",
    "JWT_SECRET"
  ],
  "properties": {
    "ENVIRONMENT": {
      "type": "string",
      "enum": ["development", "staging", "production"]
    },
    "DEBUG": {
      "type": "boolean"
    },
    "POSTGRES_HOST": {
      "type": "string",
      "minLength": 1
    },
    "POSTGRES_PORT": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "default": 5432
    },
    "JWT_SECRET": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "LOG_RETENTION_DAYS": {
      "type": "integer",
      "minimum": 30,
      "maximum": 365,
      "default": 90
    }
  }
}

Additional Resources

• Environment Setup Guide: docs/DEVELOPMENT_SETUP.md
• Security Guidelines: docs/SECURITY_COMPLIANCE.md
• Deployment Guide: docs/DEPLOYMENT.md
• Troubleshooting: docs/TROUBLESHOOTING.md

Document Version: 1.0 Last Updated: 2025-11-21 Maintainer: VoiceAssist Team