Configuration Guide - Vantrexia Documentation

Vantrexia is configured through environment variables stored in .env files. This guide provides a complete reference for every configurable setting across the backend, frontend, security layer, task queue, and production overrides.

HIPAA Compliance Reminder

Environment files contain sensitive credentials including database passwords, API keys, and encryption keys. Never commit .env files to version control. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, or GitHub Actions secrets) for production deployments. All PHI-related settings must comply with your organization's BAA requirements.

Backend Environment Variables

All backend configuration lives in the root .env file. The Django application reads these at startup via os.environ and dj-database-url.

Django Core Settings

Variable	Description	Default	Required
`SECRET_KEY`	Cryptographic secret for session signing, CSRF tokens, and password hashing. Must be unique per environment.	none	Yes
`DEBUG`	Enable debug mode. Set to `False` in production to disable stack traces and debug toolbar.	`False`	No
`ALLOWED_HOSTS`	Comma-separated list of allowed hostnames. Include your domain and any load balancer addresses.	`localhost,127.0.0.1`	Yes
`FIELD_ENCRYPTION_KEY`	Encryption key for PHI fields at rest via django-encrypted-model-fields. Auto-generated in dev/test if empty.	empty	Yes (prod)
`CORS_ALLOWED_ORIGINS`	Comma-separated list of origins allowed to make cross-origin requests.	`http://localhost:3000,http://127.0.0.1:3000`	No

backend/.env — Django Core

# Generate a secure key: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
SECRET_KEY=your-unique-secret-key-minimum-50-characters
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
FIELD_ENCRYPTION_KEY=
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

Database Configuration

Variable	Description	Default
`DATABASE_URL`	Full PostgreSQL connection URI. Format: `postgresql://USER:PASS@HOST:PORT/DBNAME`	`sqlite:///db.sqlite3`
`DB_CONN_MAX_AGE`	Database connection lifetime in seconds. Set to `0` to close after each request.	`60`
`DB_CONN_HEALTH_CHECKS`	Enable connection health checks before reuse.	`True`

backend/.env — Database

# Docker Compose (uses service name as host)
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/vantrexia_prod

# Native development (local PostgreSQL)
# DATABASE_URL=postgresql://postgres:your_password@localhost:5432/vantrexia_prod

DB_CONN_MAX_AGE=60
DB_CONN_HEALTH_CHECKS=True

Redis Configuration

Variable	Description	Default
`REDIS_URL`	Redis connection URI for Django caching.	`redis://redis:6379/0`
`CELERY_BROKER_URL`	Redis URI for Celery task broker. Defaults to `REDIS_URL` in production (hipaa.py).	REDIS_URL
`CELERY_RESULT_BACKEND`	Redis URI for storing Celery task results. Defaults to `REDIS_URL` in production.	REDIS_URL

backend/.env — Redis & Celery

REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

eClinicalWorks (eCW) Integration

Vantrexia integrates with eClinicalWorks via the FHIR R4 API. These credentials are provided by your eCW account representative after completing the developer onboarding process.

Variable	Description	Required
`ECW_FHIR_BASE_URL`	eClinicalWorks FHIR R4 base endpoint URL. Auto-generated from `ECW_ENVIRONMENT` and `ECW_PRACTICE_CODE` if not set.	No
`ECW_CLIENT_ID`	OAuth 2.0 client ID issued by eCW.	Yes (if using eCW)
`ECW_CLIENT_SECRET`	OAuth 2.0 client secret issued by eCW.	Yes (if using eCW)
`ECW_ENVIRONMENT`	eCW environment: `production` or `staging`. Controls auto-generated FHIR/token URLs.	No (default: `production`)
`ECW_PRACTICE_CODE`	Your eCW practice code.	No (default: `FFHEDD`)
`ECW_APP_TYPE`	Application type: `backend` or `standalone`. Controls auth flow and grant type.	No (default: `backend`)
`ECW_SCOPE`	OAuth scopes requested.	No
`ECW_TIMEOUT`	HTTP request timeout for eCW calls in seconds.	No (default: `30`)

backend/.env — eClinicalWorks

ECW_ENVIRONMENT=production
ECW_PRACTICE_CODE=FFHEDD
ECW_APP_TYPE=backend
ECW_CLIENT_ID=your-ecw-client-id
ECW_CLIENT_SECRET=your-ecw-client-secret
ECW_SCOPE=
ECW_TIMEOUT=30

eCW Onboarding

For detailed integration setup including FHIR resource mapping and webhook configuration, see the eClinicalWorks Integration Guide.

Email & Notifications

Variable	Description	Default
`EMAIL_USE_TLS`	Use TLS for SMTP connections.	`True`
`EMAIL_HOST`	SMTP server hostname.	`smtp.gmail.com`
`EMAIL_PORT`	SMTP server port.	`587`
`EMAIL_HOST_USER`	SMTP authentication username.	none
`EMAIL_HOST_PASSWORD`	SMTP authentication password or app-specific password.	none
`DEFAULT_FROM_EMAIL`	Default sender address for system emails.	`noreply@vantrexia.com`

Frontend Environment Variables

Frontend configuration lives in frontend/.env.local. Vite exposes only variables prefixed with VITE_ to the browser bundle.

Variable	Description	Default
`VITE_API_BASE_URL`	Base URL for the backend REST API.	`http://localhost:8000`
`VITE_GEMINI_API_KEY`	Google Gemini AI API key for smart billing features.	empty
`VITE_SENTRY_DSN`	Sentry error tracking DSN. Leave empty to disable.	empty

frontend/.env.local

VITE_API_BASE_URL=http://localhost:8000
VITE_GEMINI_API_KEY=
VITE_SENTRY_DSN=

Feature Flags

Feature flags like VITE_GEMINI_API_KEY enable AI billing features. The backend APIs remain available regardless. The only required frontend variable is VITE_API_BASE_URL.

Security Configuration

Vantrexia uses JWT-based authentication with configurable token lifetimes, CORS policies, and CSRF protection. These settings are critical for HIPAA compliance.

JWT Token Settings

Variable	Description	Default
`JWT_ACCESS_TOKEN_LIFETIME`	Access token validity period in minutes. Short lifetimes reduce risk from token theft.	`15`
`JWT_REFRESH_TOKEN_LIFETIME`	Refresh token validity period in days. Users must re-authenticate after this expires.	`1`
`JWT_ROTATE_REFRESH_TOKENS`	Issue a new refresh token with each refresh request. Prevents refresh token reuse attacks.	`True`
`JWT_BLACKLIST_AFTER_ROTATION`	Blacklist old refresh tokens after rotation. Requires `rest_framework_simplejwt.token_blacklist` in INSTALLED_APPS.	`True`
`JWT_SIGNING_KEY`	Key used to sign JWT tokens. Defaults to `SECRET_KEY` if not set separately.	SECRET_KEY
`JWT_ALGORITHM`	Signing algorithm. Use `HS256` for symmetric or `RS256` for asymmetric.	`HS256`

backend/.env — JWT Security

JWT_ACCESS_TOKEN_LIFETIME=15
JWT_REFRESH_TOKEN_LIFETIME=1
JWT_ROTATE_REFRESH_TOKENS=True
JWT_BLACKLIST_AFTER_ROTATION=True
JWT_ALGORITHM=HS256

CORS & CSRF Settings

Variable	Description	Default
`CORS_ALLOWED_ORIGINS`	Comma-separated list of origins allowed to make cross-origin requests.	`http://localhost:3000,http://127.0.0.1:3000`
`CORS_ALLOW_CREDENTIALS`	Allow cookies and Authorization headers in cross-origin requests.	`True`
`CSRF_TRUSTED_ORIGINS`	Comma-separated list of origins trusted for CSRF. Must include the full scheme and domain.	`http://localhost:3000,http://127.0.0.1:3000`
`CSRF_COOKIE_SECURE`	Restrict CSRF cookie to HTTPS. Must be `True` in production.	`False` (dev) / `True` (prod)
`SESSION_COOKIE_SECURE`	Restrict session cookie to HTTPS. Must be `True` in production.	`False` (dev) / `True` (prod)

backend/.env — CORS & CSRF

# Development
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
CORS_ALLOW_CREDENTIALS=True
CSRF_TRUSTED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

# Production (update to your actual domains)
# CORS_ALLOWED_ORIGINS=https://app.vantrexia.com
# CSRF_TRUSTED_ORIGINS=https://app.vantrexia.com,https://api.vantrexia.com
# CSRF_COOKIE_SECURE=True
# SESSION_COOKIE_SECURE=True

Encryption & Data Protection

Variable	Description	Default
`FIELD_ENCRYPTION_KEY`	Fernet encryption key for encrypting PHI fields at rest (names, DOB, MRN, phone, etc.) via django-encrypted-model-fields.	none
`SECURE_SSL_REDIRECT`	Redirect all HTTP requests to HTTPS. Must be `True` in production.	`False`
`SECURE_HSTS_SECONDS`	HTTP Strict Transport Security header duration in seconds.	`0` (dev) / `31536000` (prod)

Celery & Task Queue Configuration

Celery handles asynchronous tasks such as FHIR data synchronization, billing calculations, notification delivery, and audit log processing.

Variable	Description	Default
`CELERY_BROKER_URL`	Redis URI for task message broker.	`REDIS_URL`
`CELERY_RESULT_BACKEND`	Redis URI for storing task results and status.	`REDIS_URL`
`CELERY_TASK_ALWAYS_EAGER`	Execute tasks synchronously (for testing). Never use in production.	`False`
`CELERY_WORKER_CONCURRENCY`	Number of concurrent worker processes. Set based on CPU cores.	`4`
`CELERY_TASK_TIME_LIMIT`	Hard time limit for tasks in seconds. Tasks exceeding this are terminated.	`300`
`CELERY_TASK_SOFT_TIME_LIMIT`	Soft time limit in seconds. Raises `SoftTimeLimitExceeded` for graceful cleanup.	`240`

backend/.env — Celery

CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0
CELERY_TASK_ALWAYS_EAGER=False
CELERY_WORKER_CONCURRENCY=4
CELERY_TASK_TIME_LIMIT=300
CELERY_TASK_SOFT_TIME_LIMIT=240

Periodic Tasks (Celery Beat)

The following scheduled tasks are registered with Celery Beat and run automatically:

Task	Schedule	Description
`sync_ecw_patients`	Every 15 min	Sync patient demographics from eClinicalWorks via FHIR
`calculate_billing_minutes`	Hourly	Calculate RPM time tracking for CPT 99457/99458 codes
`process_triage_alerts`	Every 5 min	Evaluate vital signs against triage rules and generate alerts
`cleanup_expired_tokens`	Daily at 2:00 AM	Remove expired JWT tokens from the blacklist table
`generate_compliance_report`	Weekly (Sunday)	Generate HIPAA compliance audit report
`rotate_audit_logs`	Monthly	Archive old audit logs and compress for long-term storage

Production vs Development Settings

Key differences between development and production configurations:

Setting	Development	Production
`DEBUG`	`True`	`False`
`DATABASE_SSL_MODE`	`disable`	`verify-full`
`SECURE_SSL_REDIRECT`	`False`	`True`
`CSRF_COOKIE_SECURE`	`False`	`True`
`SESSION_COOKIE_SECURE`	`False`	`True`
`SECURE_HSTS_SECONDS`	`0`	`31536000`
`EMAIL_BACKEND`	`console`	`smtp`
`CELERY_WORKER_CONCURRENCY`	`2`	`4–8` (based on CPU)
`DJANGO_LOG_LEVEL`	`DEBUG`	`WARNING`
Docker Compose file	`docker-compose.yml`	`docker-compose.prod.yml`

Production Docker Compose

For production deployments, use the production compose override which adds Nginx, SSL termination, and HIPAA-hardened settings:

Terminal

# Production uses docker-compose.prod.yml directly
docker compose -f docker-compose.prod.yml up -d

Production Checklist

Before deploying to production, ensure you have completed the Production Deployment Checklist which covers SSL certificates, secrets management, database backups, monitoring, and HIPAA compliance verification.

Complete Production Environment File

Below is a reference template for a complete production backend/.env file. Replace all placeholder values with your actual credentials:

backend/.env (Production Template)

# ============================================================
# VANTREXIA PRODUCTION CONFIGURATION
# ============================================================
# WARNING: This file contains sensitive credentials.
# Never commit to version control.
# ============================================================

# --- Django Core ---
SECRET_KEY=<generate-a-unique-50-char-minimum-secret-key>
DEBUG=False
ALLOWED_HOSTS=app.vantrexia.com
DJANGO_SETTINGS_MODULE=config.settings.hipaa

# --- Database (AWS RDS PostgreSQL 18) ---
DATABASE_URL=postgresql://postgres:<rds-password>@<rds-endpoint>:5432/vantrexia_prod
DB_CONN_MAX_AGE=60

# --- Redis ---
REDIS_URL=redis://:<redis-password>@redis:6379/0

# --- eClinicalWorks ---
ECW_ENVIRONMENT=production
ECW_PRACTICE_CODE=FFHEDD
ECW_APP_TYPE=backend
ECW_CLIENT_ID=<your-ecw-client-id>
ECW_CLIENT_SECRET=<your-ecw-client-secret>

# --- Security ---
CORS_ALLOWED_ORIGINS=https://app.vantrexia.com
CSRF_TRUSTED_ORIGINS=https://app.vantrexia.com
CSRF_COOKIE_SECURE=true
SESSION_COOKIE_SECURE=true
SECURE_SSL_REDIRECT=true
FIELD_ENCRYPTION_KEY=<generate-encryption-key>

# --- Email ---
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=<your-email>
EMAIL_HOST_PASSWORD=<app-password>
DEFAULT_FROM_EMAIL=noreply@vantrexia.com

# --- Push Notifications ---
FCM_ENABLED=True
APNS_BUNDLE_ID=com.vantrexia.app

# --- AWS Secrets (production loads secrets from AWS) ---
USE_AWS_SECRETS=true
AWS_SECRETS_REGION=us-east-1
AWS_SECRETS_PREFIX=vantrexia/prod

Previous Installation Guide Next Features Overview