Environment Variables Reference¶

This document provides a complete reference for all environment variables used by CertifyClouds.

Quick Reference¶

Required for Production¶

Variable	Description	Example
`DB_PASSWORD`	PostgreSQL password	`openssl rand -hex 16`
`SECRET_KEY`	Application secret key	`openssl rand -hex 32`
`CERTIFYCLOUDS_LICENSE_KEY`	License key	`CC-XXXX-XXXX-XXXX`
`CORS_ALLOWED_ORIGINS`	Allowed CORS origins	`https://yourdomain.com`

Required for Azure¶

At least one authentication method:

Method	Variables
Managed Identity	`AZURE_USE_MANAGED_IDENTITY=true`
Service Principal	`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`

Database Configuration¶

Variable	Description	Default	Required
`DATABASE_URL`	PostgreSQL connection string	`sqlite:///./certifyclouds.db`	Yes (production)
`DB_PASSWORD`	Database password (used in docker-compose)	-	Yes (production)
`DATABASE_POOL_SIZE`	Connection pool size	`20`	No
`DATABASE_MAX_OVERFLOW`	Max overflow connections for burst	`10`	No
`DATABASE_POOL_RECYCLE`	Pool recycle time (seconds)	`1800`	No
`DATABASE_POOL_TIMEOUT`	Pool timeout (seconds)	`60`	No

Example:

DB_PASSWORD=<YOUR_SECURE_PASSWORD>
DATABASE_URL=postgresql://certifyclouds:${DB_PASSWORD}@<YOUR_DB_HOST>:5432/certifyclouds

Security Configuration¶

Variable	Description	Default	Required
`SECRET_KEY`	Application secret for sessions/JWT	-	Yes (production)
`JWT_SECRET`	JWT signing secret	Uses `SECRET_KEY`	No
`JWT_ALGORITHM`	JWT algorithm	`HS256`	No
`JWT_EXPIRATION_HOURS`	JWT token expiration	`8`	No
`RATE_LIMIT_PER_MINUTE`	API rate limit per minute	`60`	No
`RATE_LIMIT_PER_HOUR`	API rate limit per hour	`1000`	No
`COOKIE_SECURE`	Require HTTPS for auth cookies	`true`	No
`COOKIE_SAMESITE`	SameSite cookie policy	`strict`	No

Generating SECRET_KEY:

openssl rand -hex 32

Authentication Security Hardening¶

Variable	Description	Default	Range
`ACCOUNT_LOCKOUT_ATTEMPTS`	Failed login attempts before lockout	`5`	3-10
`ACCOUNT_LOCKOUT_DURATION_MINUTES`	Lockout duration in minutes	`15`	5-60
`SESSION_IDLE_TIMEOUT_MINUTES`	Session idle timeout (0 to disable)	`60`	5-480
`LOGIN_RATE_LIMIT_PER_MINUTE`	Max login attempts per minute per IP	`10`	3-30
`ENABLE_IP_BINDING`	Bind sessions to IP address	`false`	-
`IP_BINDING_MODE`	IP binding enforcement mode	`warn`	warn, block

IP Binding

IP binding may cause issues for users on VPN or mobile networks where IP addresses change frequently. Use warn mode to log IP changes without blocking, or block to enforce strict IP binding.

Initial Admin Account¶

On first startup, if no users exist, CertifyClouds creates an initial admin account:

Variable	Description	Default	Required
`INITIAL_ADMIN_USERNAME`	Initial admin username	`admin`	No
`INITIAL_ADMIN_PASSWORD`	Initial admin password	-	Yes (first startup)

Example:

INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=<YOUR_SECURE_PASSWORD>

Important

Change this password after first login via Settings > User Management.

CORS Configuration¶

Variable	Description	Default	Required
`CORS_ALLOWED_ORIGINS`	Comma-separated allowed origins	`http://localhost:3000,...`	Yes (production)

Examples:

# Development
CORS_ALLOWED_ORIGINS=http://localhost:8080,http://localhost:3000

# Production (single domain)
CORS_ALLOWED_ORIGINS=https://certifyclouds.mycompany.com

# Production (multiple domains)
CORS_ALLOWED_ORIGINS=https://certifyclouds.mycompany.com,https://vault-dashboard.mycompany.com

Azure Authentication¶

Priority Order: When multiple auth methods are configured, CertifyClouds uses this order:

AZURE_LOCAL_AUTH=true (always wins if set)
Service Principal (if all 3 vars set)
Managed Identity (if MSI endpoint detected)
Fallback to Azure CLI

Option 1: Local Development (Azure CLI)¶

Variable	Description	Default
`AZURE_LOCAL_AUTH`	Use Azure CLI from host	`false`

Usage:

# Run az login first, then:
./start.sh --local
# Or set manually:
AZURE_LOCAL_AUTH=true

Best for: Local development, testing

Option 2: Service Principal¶

Variable	Description	Required
`AZURE_TENANT_ID`	Azure AD tenant ID	Yes
`AZURE_CLIENT_ID`	Service principal client ID	Yes
`AZURE_CLIENT_SECRET`	Service principal secret	Yes

Usage:

AZURE_TENANT_ID=<YOUR_TENANT_ID>
AZURE_CLIENT_ID=<YOUR_CLIENT_ID>
AZURE_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

Best for: On-premises deployments, non-Azure cloud

Option 3: Managed Identity (Recommended for Production)¶

Variable	Description	Default
`AZURE_USE_MANAGED_IDENTITY`	Enable managed identity auth	`false`

Usage:

AZURE_USE_MANAGED_IDENTITY=true

Best for: Azure VMs, Azure Container Instances, Azure Kubernetes Service

Azure Subscription Filtering¶

Variable	Description	Default
`DISCOVERY_TARGET_SUBSCRIPTION`	Scan only this subscription	All accessible
`DISCOVERY_ALLOWED_SUBSCRIPTIONS`	Comma-separated allowed subscription IDs	All accessible

Examples:

# Scan single subscription
DISCOVERY_TARGET_SUBSCRIPTION=<YOUR_SUBSCRIPTION_ID>

# Scan specific subscriptions
DISCOVERY_ALLOWED_SUBSCRIPTIONS=<SUB_ID_1>,<SUB_ID_2>,<SUB_ID_3>

License Configuration¶

Variable	Description	Default	Required
`CERTIFYCLOUDS_LICENSE_KEY`	License key (CC-XXXX-XXXX-XXXX)	-	Yes
`CERTIFYCLOUDS_LICENSE_SERVER`	License validation server	`https://license.certifyclouds.com/api/validate`	No
`CERTIFYCLOUDS_LICENSE_GRACE_DAYS`	Days to use cached license if server unreachable	`7`	No

Example:

CERTIFYCLOUDS_LICENSE_KEY=CC-XXXX-XXXX-XXXX
CERTIFYCLOUDS_LICENSE_GRACE_DAYS=7

Email Notifications¶

Option 1: SMTP¶

Variable	Description	Default	Required
`SMTP_HOST`	SMTP server hostname	-	Yes (if using SMTP)
`SMTP_PORT`	SMTP server port	`2525`	No
`SMTP_USE_TLS`	Use TLS for SMTP connection	`true`	No
`SMTP_USERNAME`	SMTP username	-	Yes (if using SMTP)
`SMTP_PASSWORD`	SMTP password	-	Yes (if using SMTP)
`SMTP_FROM_EMAIL`	From email address	`alerts@certifyclouds.com`	No
`SMTP_FROM_NAME`	From display name	`CertifyClouds Alerts`	No

Example:

SMTP_HOST=mail.smtp2go.com
SMTP_PORT=2525
SMTP_USERNAME=<YOUR_SMTP_USERNAME>
SMTP_PASSWORD=<YOUR_SMTP_PASSWORD>
SMTP_FROM_EMAIL=alerts@mycompany.com
SMTP_FROM_NAME=CertifyClouds Alerts

Option 2: SendGrid¶

Variable	Description	Default	Required
`SENDGRID_API_KEY`	SendGrid API key	-	Yes (if using SendGrid)
`SENDGRID_FROM_EMAIL`	From email address	`alerts@certifyclouds.com`	No
`SENDGRID_FROM_NAME`	From display name	`CertifyClouds Alerts`	No

Example:

SENDGRID_API_KEY=<YOUR_SENDGRID_API_KEY>
SENDGRID_FROM_EMAIL=alerts@yourcompany.com
SENDGRID_FROM_NAME=CertifyClouds Alerts

Logging Configuration¶

Variable	Description	Default	Options
`LOG_LEVEL`	Logging level	`INFO`	DEBUG, INFO, WARNING, ERROR, CRITICAL
`LOG_FILE`	Log file path (optional)	-	Any valid path
`LOG_MAX_BYTES`	Max log file size	`10485760` (10MB)	Any integer
`LOG_BACKUP_COUNT`	Number of backup log files	`5`	0-10

Performance Tuning¶

UI Configuration

Most performance settings are UI-configurable via Settings > Advanced tab. The priority is: Database (UI) > Environment Variable > Default. Use environment variables to enforce settings that users cannot override.

Discovery Scanning¶

Variable	Description	Default	Range
`DISCOVERY_MAX_WORKERS`	Concurrent scan workers	`5`	1-20
`DISCOVERY_SCAN_TIMEOUT`	Scan timeout (seconds)	`300`	60-600
`DISCOVERY_MAX_RETRIES`	Max retry attempts	`1`	0-5
`DISCOVERY_RETRY_WAIT_MIN`	Min retry wait (seconds)	`1`	0-10
`DISCOVERY_RETRY_WAIT_MAX`	Max retry wait (seconds)	`2`	1-30

Rotation (PRO)¶

Variable	Description	Default	Range
`ROTATION_MAX_WORKERS`	Concurrent workers for hint prefetching	`25`	1-50
`ROTATION_CACHE_TTL_MINUTES`	Cache TTL (minutes)	`5`	1-60
`ROTATION_WORKER_TIMEOUT`	Worker timeout (seconds)	`5`	1+
`ROTATION_CHECK_INTERVAL_SECONDS`	Rotation check interval	`3600`	60+
`ROTATION_MAX_CONCURRENT_JOBS`	Max concurrent rotation jobs	`5`	1-20
`ROTATION_BATCH_SIZE`	Rotation batch size	`10`	1+

Feature Flags¶

UI Configuration

Feature flags are UI-configurable via Settings > Advanced tab.

Variable	Description	Default
`ENABLE_HINT_CACHING`	Enable hint caching	`true`
`ENABLE_NOTIFICATIONS`	Enable email/webhook alert notifications	`true`
`ENABLE_SUBSCRIPTION_MATCHING`	Enable subscription matching	`true`
`ENABLE_COMPLIANCE_SCANNING`	Enable compliance scanning	`true`

Environment Mode¶

Variable	Description	Default	Options
`ENVIRONMENT`	Environment name	`development`	development, staging, production

Production mode enforces:

SECRET_KEY must not be default
AZURE_TENANT_ID is required
Additional security validations

Docker/Deployment Variables¶

Variable	Description	Default
`PORT`	Application port	`8080`
`APP_PORT`	Host port mapping	`8080`
`APP_VERSION`	Semantic version (shown in UI footer)	`1.0.0`
`CERTIFYCLOUDS_VERSION`	Docker image tag	`latest`
`PYTHONUNBUFFERED`	Python output buffering	`1` (disabled)

Example .env Files¶

Development¶

# Development .env
ENVIRONMENT=development
DATABASE_URL=postgresql://certifyclouds:<YOUR_SECURE_PASSWORD>@db-host:5432/certifyclouds
CERTIFYCLOUDS_LICENSE_KEY=<YOUR_LICENSE_KEY>
AZURE_LOCAL_AUTH=true
LOG_LEVEL=DEBUG
CORS_ALLOWED_ORIGINS=http://localhost:8080,http://localhost:3000

Production¶

# Production .env
ENVIRONMENT=production
DB_PASSWORD=<YOUR_SECURE_PASSWORD>
DATABASE_URL=postgresql://certifyclouds:${DB_PASSWORD}@<YOUR_DB_HOST>:5432/certifyclouds
SECRET_KEY=<YOUR_SECRET_KEY>
CERTIFYCLOUDS_LICENSE_KEY=<YOUR_LICENSE_KEY>

# Azure (choose one)
AZURE_USE_MANAGED_IDENTITY=true
# OR
AZURE_TENANT_ID=<YOUR_TENANT_ID>
AZURE_CLIENT_ID=<YOUR_CLIENT_ID>
AZURE_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

# CORS
CORS_ALLOWED_ORIGINS=https://certifyclouds.mycompany.com

# Notifications (optional)
SENDGRID_API_KEY=<YOUR_SENDGRID_API_KEY>
SENDGRID_FROM_EMAIL=alerts@mycompany.com

# Logging
LOG_LEVEL=INFO

Validation¶

CertifyClouds validates configuration on startup. In production mode:

SECRET_KEY must be changed from default
AZURE_TENANT_ID is required
All database connection parameters must be valid

Check configuration:

curl http://localhost:8080/health | jq .config