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:**
```bash
# 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