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:

python
from dotenv import load_dotenv

load_dotenv()  # Loads variables from .env file

Environment-Specific Configuration

The backend uses BACKEND_ENV as the canonical runtime environment label in Python settings and logging. Valid values are production, development, staging, local, and test.

settings.py
from rhesis.backend.app.config.settings import get_application_settings

settings = get_application_settings()

if settings.backend_env == "production":
    enable_local_debug = False
elif settings.backend_env == "test":
    enable_local_debug = True
else:
    enable_local_debug = settings.is_development

Shell entrypoints may still read ENVIRONMENT for deployment-script behavior, but application code should use BACKEND_ENV.

Database credentials

Database URLs are built from component environment variables. Runtime application sessions use APP_DB_USER / APP_DB_PASS; migrations and administrative jobs use ADMIN_DB_USER / ADMIN_DB_PASS when present and fall back to the app credentials for single-role local setups.

Variable	Required	Used for
`DB_DRIVER`	No, defaults to `postgresql`	SQLAlchemy driver
`DB_HOST`	Yes	Database host or Unix socket path
`DB_PORT`	No, defaults to `5432`	TCP port when `DB_HOST` is not a socket
`DB_NAME`	Yes	Database name
`APP_DB_USER`	Yes for runtime backend and workers	Least-privilege application database role
`APP_DB_PASS`	Yes when `APP_DB_USER` is set	Application role password
`ADMIN_DB_USER`	Optional	Migration or admin database role
`ADMIN_DB_PASS`	Required when `ADMIN_DB_USER` is set	Admin role password

Managed Postgres deployments should use a separate migration role through ADMIN_DB_* and a least-privilege runtime role through APP_DB_*. RLS-aware migrations do not require a PostgreSQL superuser.

Configuration Validation

The application validates critical configuration at startup:

python
def validate_config():
    """Validate that all required configuration is present."""
    required_vars = [
        "DB_HOST",
        "DB_NAME",
        "APP_DB_USER",
        "APP_DB_PASS",
        "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:

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

Example Docker Compose configuration:

docker-compose.yml
services:
backend:
    build: ./apps/backend
    env_file:
      - ./apps/backend/.env.docker
    environment:
      - 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:

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