Environment Configuration

Overview

Configuration is environment variables (see 12-factor app ); different files and hosts supply values per environment.

Environment Variables Reference

For a complete list of all environment variables, their requirements, and descriptions, see the Environment Variables.

Environment Files

The application supports multiple environment files:

• .env: Default environment file for local development
• .env.docker: Environment configuration for Docker deployment
• .env.test: Environment configuration for testing (not committed to version control)

Loading Environment Variables

Environment variables are loaded using the python-dotenv library:

from dotenv import load_dotenv

load_dotenv()  # Loads variables from .env file

Environment-Specific Configuration

The application can load different configuration based on the environment:

import os

# Determine environment (ENVIRONMENT is preferred; ENV is supported for backward compatibility)
ENVIRONMENT = os.getenv("ENVIRONMENT") or os.getenv("ENV", "development")

# Load environment-specific settings
if ENVIRONMENT == "production":
    # Production settings
    DEBUG = False
    LOG_LEVEL = "INFO"
elif ENVIRONMENT == "testing":
    # Testing settings
    DEBUG = True
    LOG_LEVEL = "DEBUG"
    # Use in-memory database
    SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"
else:
    # Development settings
    DEBUG = True
    LOG_LEVEL = "DEBUG"

Configuration Validation

The application validates critical configuration at startup:

def validate_config():
    """Validate that all required configuration is present."""
    required_vars = [
        "SQLALCHEMY_DATABASE_URL",
        "JWT_SECRET_KEY",
    ]

    missing = [var for var in required_vars if not os.getenv(var)]

    if missing:
        raise ValueError(f"Missing required environment variables: {', '.join(missing)}")

Docker Environment

When running in Docker, environment variables can be passed in several ways:

1. Through the environment section in docker-compose.yml
2. Using the --env-file flag with docker run
3. Setting individual variables with -e flags

Example Docker Compose configuration:

services:
backend:
    build: ./apps/backend
    env_file:
      - ./apps/backend/.env.docker
    environment:
      - SQLALCHEMY_DB_HOST=postgres
      - LOG_LEVEL=INFO

Cloud Deployment

For cloud deployments, environment variables should be set using the cloud provider’s secrets or environment configuration:

• Google Cloud: Secret Manager and environment variables in Cloud Run
• AWS: Parameter Store/Secrets Manager and environment variables in ECS/Lambda
• Azure: Key Vault and App Configuration

Security Best Practices

Never commit secrets. Use distinct keys per environment, store them in a secret manager, rotate periodically, and keep production config separate from dev.

Sensitive Information

Sensitive information such as API keys and passwords should never be committed to version control. Instead:

1. Use placeholder values in .env.example
2. Document the required variables in the Environment Setup Guide
3. Use secrets management in production environments