Configuration

ChemAudit is configured through environment variables and deployment profiles that control batch limits, worker counts, and resource allocation.

Environment Variables

Configuration is managed through a .env file in the project root. Copy .env.example to get started:

cp .env.example .env

Required Variables

These variables must be set before starting ChemAudit:

Variable	Description	Example
POSTGRES_PASSWORD	Database password	Generated with openssl rand -base64 32
SECRET_KEY	Application secret key	Generated with openssl rand -base64 32
API_KEY_ADMIN_SECRET	Admin secret for API key management	Generated with openssl rand -base64 32
CSRF_SECRET_KEY	CSRF protection secret	Generated with openssl rand -base64 32

Never Commit Secrets

Never commit your .env file to version control. Keep secrets secure and rotate them periodically.

Optional Variables

Variable	Description	Default
POSTGRES_USER	Database username	chemaudit
POSTGRES_DB	Database name	chemaudit
DATABASE_URL	Full database connection string	Auto-generated from above
REDIS_PASSWORD	Redis authentication password	changeme_redis
REDIS_URL	Redis connection string	redis://:${REDIS_PASSWORD}@redis:6379/0
DEBUG	Enable debug mode	false
CORS_ORIGINS_STR	Allowed CORS origins (comma-separated)	http://localhost:3002
GRAFANA_PASSWORD	Grafana admin password	admin

Redis Authentication

Redis authentication is enforced in both development and production. The REDIS_URL must include the password. If you see Authentication required errors, ensure REDIS_PASSWORD is set in your .env file and REDIS_URL includes it.

Development vs Production

Development Mode

In development (using docker-compose.yml), services are exposed on individual ports. The frontend runs on 3002, backend on 8001.

Production Mode

In production (using docker-compose.prod.yml), all services run behind Nginx on port 80/443.

Startup Secret Validation

When DEBUG=false, ChemAudit validates that SECRET_KEY, API_KEY_ADMIN_SECRET, and CSRF_SECRET_KEY do not contain placeholder values (CHANGE_ME). The application will refuse to start until secure values are set. Use openssl rand -hex 64 to generate secrets, or run deploy.sh which auto-generates them.

Deployment Profiles

ChemAudit includes pre-configured deployment profiles that set batch limits, worker counts, and memory allocation based on your workload.

Available Profiles

Profile	Max Batch	Max File Size	Celery Workers	Use Case
small	1,000	100 MB	2	Development, testing
medium	10,000	500 MB	4	Standard production
large	50,000	500 MB	8	High-throughput labs
xl	100,000	1 GB	12	Enterprise scale
coconut	1,000,000	1 GB	16	Full COCONUT database

Profile Configuration Files

Profiles are defined in YAML files under config/:

# config/medium.yml
MAX_BATCH_SIZE: 10000
MAX_FILE_SIZE_MB: 500
CELERY_WORKERS: 4
GUNICORN_WORKERS: 4
REDIS_MAXMEMORY: 512mb
BACKEND_MEMORY_LIMIT: 2g
CELERY_MEMORY_LIMIT: 2g

Using Deployment Profiles

The deploy.sh script makes it easy to deploy with a specific profile:

# Interactive mode - shows menu of profiles
./deploy.sh

# Direct profile selection
./deploy.sh large

The script automatically:

1. Parses the selected profile from config/{profile}.yml
2. Exports environment variables for Docker Compose
3. Updates .env with profile settings
4. Launches docker-compose.prod.yml

Custom Profiles

Create a custom profile by copying an existing one:

# Copy and edit
cp config/medium.yml config/custom.yml

# Edit config/custom.yml with your settings
# Then deploy
./deploy.sh custom

Notification & Integration Variables

Variable	Description	Default
NOTIFICATION_EMAIL	Global email for batch completion notifications	None
SMTP_HOST	SMTP server hostname	None
SMTP_PORT	SMTP server port	587
SMTP_USER	SMTP authentication username	None
SMTP_PASS	SMTP authentication password	None
WEBHOOK_URL	Webhook endpoint URL for batch completion callbacks	None
WEBHOOK_SECRET	HMAC-SHA256 signing secret for webhook payloads	None
OPSIN_JAR_PATH	Path to OPSIN JAR for IUPAC name conversion	Auto-provisioned in Docker
BASE_URL	Public URL for report links in emails and webhooks	http://localhost:3002

Dynamic Limit Discovery

The frontend automatically discovers deployment limits from the backend API:

curl http://localhost:8001/api/v1/config

Response:

{
  "app_name": "ChemAudit",
  "app_version": "1.0.0",
  "deployment_profile": "medium",
  "limits": {
    "max_batch_size": 10000,
    "max_file_size_mb": 500,
    "max_file_size_bytes": 524288000
  }
}

This ensures the UI always displays accurate limits for your deployment.

CORS Configuration

For development, CORS origins are configured in .env:

# Comma-separated string (not JSON array)
CORS_ORIGINS_STR=http://localhost:3002,http://127.0.0.1:3002

For production behind Nginx, CORS is handled by the proxy configuration.

CORS Security

Only add trusted origins to CORS_ORIGINS_STR. In production, use your actual domain names.

Next Steps

With configuration complete:

1. Run your first validation - Test your setup
2. Explore deployment options - Production deployment guide
3. Monitor your deployment - Set up Prometheus and Grafana