query-orchestration/deployment_env_variables.md

Deployment Environment Variables Configuration Guide

Overview

This guide provides rules for configuring environment variables when deploying all runners and the queryAPI service across different environments (dev, stage, prod).

Variable Categories

1. Service-Specific Variables (UNIQUE per service)

These variables MUST be different for each runner service:

Variable	Description	Unique To
QUEUE_URL	Input queue the service reads from	Each runner (different value per runner)

2. Pipeline Queue URLs (SHARED across all services in same environment)

These variables should be IDENTICAL for all services within the same environment:

Variable	Example Value (dev)	Purpose
DOCUMENT_INIT_URL	https://sqs.us-east-2.amazonaws.com/476114113988/document_init	Queue for document initialization
DOCUMENT_SYNC_URL	https://sqs.us-east-2.amazonaws.com/476114113988/document_sync	Queue for document sync
DOCUMENT_CLEAN_URL	https://sqs.us-east-2.amazonaws.com/476114113988/document_clean	Queue for document cleaning
DOCUMENT_TEXT_URL	https://sqs.us-east-2.amazonaws.com/476114113988/document_text	Queue for text extraction
CLIENT_SYNC_URL	https://sqs.us-east-2.amazonaws.com/476114113988/client_sync	Queue for client sync

3. AWS Configuration (SHARED across all services)

These should be IDENTICAL for all services:

Variable	Example Value	Notes
AWS_ACCESS_KEY_ID	AKIAXXXXXXXXXXXXXXXX	AWS credentials override - should be blank
AWS_SECRET_ACCESS_KEY	secret_key_here	AWS credentials - override - should be blank
AWS_SESSION_TOKEN	token_if_using_temporary_creds	Optional, for temporary credentials - should be blank
AWS_REGION	us-east-2	AWS region for all services

⚠️ Important for AWS deployment:

• DO NOT SET AWS_ENDPOINT_URL (only for LocalStack)
• DO NOT SET AWS_S3_USE_PATH_STYLE (only for LocalStack)

4. Database Configuration (SHARED across all services)

These should be IDENTICAL for all services:

Variable	Example Value	Notes
PGHOST	database-hostname.rds.amazonaws.com	Database hostname
PGPORT	5432	Database port
PGDATABASE	queryorchestration_dev	Database name
PGUSER	dbuser	Database username (whatever we use)
PGPASSWORD	db_password_here	Database password (keep secure)
DB_NOSSL	false	Set to false for AWS RDS (should be blank for now)

5. Authentication Configuration (SHARED across all services)

These should be IDENTICAL for all services:

Variable	Example Value	Notes
DISABLE_AUTH	false	Set to false for production/staging true for dev
COGNITO_USER_POOL_ID	us-east-2_XXXXXXXXX	AWS Cognito User Pool ID
COGNITO_CLIENT_ID	client_id_here	AWS Cognito Client ID
COGNITO_CLIENT_SECRET	client_secret_here	AWS Cognito Client Secret
COGNITO_DOMAIN	your-domain.auth.us-east-2.amazoncognito.com	AWS Cognito Domain
COGNITO_ENVIRONMENT_ID	acmehealth	Optional. Scopes server to a specific environment within a shared Cognito user pool. Lowercase alphanumeric + underscores, max 50 chars. Leave empty/unset for unscoped mode.

6. Application Configuration (SHARED across all services)

Variable	Example Value	Notes
LOG_LEVEL	INFO or DEBUG	Use INFO for prod, DEBUG for dev
BUCKET	s3-bucket-name-dev	S3 bucket name (only needed by some services)

7. Service-Specific Optional Variables

Service	Variable	Purpose
docCleanRunner	BUCKET	S3 bucket for document processing
docTextRunner	BUCKET	S3 bucket for document processing
queryAPI	BUCKET	S3 bucket for document uploads
queryAPI	DEBUG	Set to true for debugging

Per-Service Configuration Matrix

storeEventRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/store_event

Also Needs:

• DOCUMENT_INIT_URL
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

docInitRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/document_init

Also Needs:

• DOCUMENT_SYNC_URL
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

docSyncRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/document_sync

Also Needs:

• DOCUMENT_CLEAN_URL
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

docCleanRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/document_clean

Also Needs:

• DOCUMENT_TEXT_URL
• BUCKET (S3 bucket name)
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

docTextRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/document_text

Also Needs:

• BUCKET (S3 bucket name)
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

clientSyncRunner

Unique Variables:

• QUEUE_URL = https://sqs.us-east-2.amazonaws.com/476114113988/client_sync

Also Needs:

• DOCUMENT_SYNC_URL
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

queryAPI (REST API Service)

Does NOT need QUEUE_URL

Needs:

• CLIENT_SYNC_URL
• BUCKET (S3 bucket name)
• DEBUG (optional, set to true for development)
• COGNITO_ENVIRONMENT_ID (optional, scopes user operations to a specific environment)
• AWS config (shared)
• Database config (shared)
• Auth config (shared)

Deployment Strategy

Option 1: Shared Base Configuration + Service Overrides

1. Create a base environment configuration with all shared variables (database, AWS, auth, all queue URLs)
2. For each service, add only the unique QUEUE_URL value

Example:

# base-dev.env (shared by all services)
AWS_REGION=us-east-2
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=secret_here
PGHOST=db-dev.example.com
PGDATABASE=queryorchestration_dev
# ... all queue URLs ...
DOCUMENT_INIT_URL=https://sqs.us-east-2.amazonaws.com/476114113988/document_init
DOCUMENT_SYNC_URL=https://sqs.us-east-2.amazonaws.com/476114113988/document_sync
# ... etc

# storeEventRunner-override.env
QUEUE_URL=https://sqs.us-east-2.amazonaws.com/476114113988/store_event

# docInitRunner-override.env
QUEUE_URL=https://sqs.us-east-2.amazonaws.com/476114113988/document_init

Option 2: Complete Configuration Per Service

Copy the full environment configuration to each service and only change QUEUE_URL.

Quick Checklist for New Environment

When deploying to a new environment (e.g., moving from dev to stage):

• Update AWS account ID in all queue URLs (e.g., 476114113988 → 123456789012)
• Update environment suffix in queue names if using suffixes (e.g., store_event-dev → store_event-stage)
• Update database connection (PGHOST, PGDATABASE, PGUSER, PGPASSWORD)
• Update AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• Update Cognito configuration (if different per environment)
• Update S3 bucket name (BUCKET)
• Set LOG_LEVEL appropriately (DEBUG for dev, INFO for prod)
• Set DISABLE_AUTH appropriately (true for dev, false for prod)
• Ensure QUEUE_URL is unique for each runner service
• Set COGNITO_ENVIRONMENT_ID for queryAPI if using shared Cognito user pool (e.g., acmehealth)
• Remove AWS_ENDPOINT_URL and AWS_S3_USE_PATH_STYLE (LocalStack only)

Common Mistakes to Avoid

❌ Setting a global QUEUE_URL - Each runner needs its own specific input queue ❌ Using different queue URLs across services - All services in same environment should see same queue URLs (except their own QUEUE_URL) ❌ Forgetting to remove LocalStack variables - AWS_ENDPOINT_URL and AWS_S3_USE_PATH_STYLE should not be set for AWS ❌ Using empty string instead of unsetting - Variables like AWS_S3_USE_PATH_STYLE should be completely absent, not empty ❌ Mixing environment credentials - Don't use dev database with prod queues

Validation

Before deploying, verify:

1. Each runner has a unique QUEUE_URL matching its input queue
2. All queue URLs within an environment are consistent across all services
3. Database credentials are correct for the environment
4. AWS credentials have appropriate permissions for SQS, S3, and Textract
5. Cognito configuration matches the environment
6. LocalStack-specific variables are removed for AWS deployments