Environment Variables Reference¶

Complete reference for configuring the New Hires Reporting system via environment variables.

Overview¶

The system is configured through a .env file placed in the project root directory alongside docker-compose.prod.yml. This file contains all configuration for AWS credentials, database settings, and worker tuning.

Security

Never commit the .env file to version control. It contains sensitive AWS credentials and database passwords.

Quick Setup¶

# Copy the example file
cp .env.example .env

# Edit with your values
nano .env

# Set secure permissions
chmod 600 .env

# Start services
docker-compose -f docker-compose.prod.yml up -d

Required Variables¶

These variables must be set for the system to function.

Docker Image Configuration¶

`IMAGE_TAG`¶

Required: Yes

Description: Version tag for Docker images pulled from ECR

Format: sha- followed by 7-character git commit hash

Example:

IMAGE_TAG=sha-a85b396

How to Get: Your development team will provide the IMAGE_TAG for each release

AWS Bedrock Configuration¶

`AWS_ACCESS_KEY_ID`¶

Required: Yes

Description: AWS access key ID for Bedrock API authentication

Format: Starts with AKIA followed by 16 alphanumeric characters

Example:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

How to Get: See AWS Bedrock Setup Guide

Security: Rotate every 90 days

`AWS_SECRET_ACCESS_KEY`¶

Required: Yes

Description: AWS secret access key for Bedrock API authentication

Format: 40-character alphanumeric string

Example:

AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

How to Get: See AWS Bedrock Setup Guide

Security: Never share or commit to version control

`AWS_REGION`¶

Required: Yes

Default: us-east-1

Description: AWS region where Bedrock service is accessed

Supported Values: - us-east-1 (N. Virginia) - Recommended, has all models - us-west-2 (Oregon) - Check AWS Bedrock regions

Example:

AWS_REGION=us-east-1

Important

The application is configured for us-east-1. Using other regions may require different model IDs.

Database Configuration¶

`POSTGRES_DB`¶

Required: No (has default)

Default: newhires

Description: PostgreSQL database name

Example:

POSTGRES_DB=newhires

`POSTGRES_USER`¶

Required: No (has default)

Default: newhires

Description: PostgreSQL username

Example:

POSTGRES_USER=newhires

`POSTGRES_PASSWORD`¶

Required: No (has default)

Default: changeme

Description: PostgreSQL password

Security Recommendation: Change this in production!

Example:

POSTGRES_PASSWORD=MyS3cur3P@ssw0rd!2024

Password Requirements: - Minimum 12 characters - Mix of letters, numbers, and symbols - Not a dictionary word - Unique to this deployment

Optional Variables¶

These variables have sensible defaults but can be tuned for your workload.

AI Model Configuration¶

`BEDROCK_MODEL_ID`¶

Required: No (has default)

Default: us.anthropic.claude-sonnet-4-5-20250929-v1:0

Description: AWS Bedrock model ID to use for corrections

Supported Models:

Model ID	Provider	Speed	Accuracy	Cost	Notes
`us.anthropic.claude-sonnet-4-5-20250929-v1:0`	Anthropic	Fast	Excellent	Medium	Recommended
`us.meta.llama4-scout-17b-instruct-v1:0`	Meta	Very Fast	Good	Low	Budget option

Example:

BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-5-20250929-v1:0

Cost Comparison (approximate): - Claude Sonnet 4.5: ~$0.045 per correction job - Llama 4 Scout: ~$0.015 per correction job

Model Selection

Use Claude Sonnet 4.5 for best accuracy
Use Llama 4 Scout to reduce costs
Ensure model access is enabled in AWS Bedrock console

Worker Configuration¶

`POLL_INTERVAL`¶

Required: No (has default)

Default: 5

Description: How often (in seconds) the worker checks for new jobs

Range: 1-60 seconds

Example:

POLL_INTERVAL=5

Tuning Guide: - Lower (1-3): Faster job pickup, more database queries - Default (5): Good balance for most workloads - Higher (10-30): Reduced database load, slower response

`MAX_CONCURRENT_BEDROCK_CALLS`¶

Required: No (has default)

Default: 2

Description: Maximum number of simultaneous Bedrock API calls per worker

Range: 1-10

Example:

MAX_CONCURRENT_BEDROCK_CALLS=2

Tuning Guide: - 1: Sequential processing, lowest cost, slowest throughput - 2-3: Recommended for most deployments - 4-6: High throughput, monitor costs closely - 7+: Very high throughput, significant cost increase

Cost Impact: - 2 concurrent calls = ~120 jobs/hour - 5 concurrent calls = ~300 jobs/hour - Higher concurrency = proportionally higher AWS bills

Bedrock Rate Limits

AWS Bedrock has per-model rate limits. Exceeding them causes throttling errors. Start with default and increase gradually.

`MAX_AI_ATTEMPTS`¶

Required: No (has default)

Default: 5

Description: Maximum number of times to retry AI correction for a failed job

Range: 1-10

Example:

MAX_AI_ATTEMPTS=5

Tuning Guide: - 1-2: Fast failure, may leave more jobs unfixed - 5: Default, good balance of retries vs cost - 7-10: Maximum retry effort, higher costs

Cost Impact: Each retry incurs Bedrock API costs

Frontend Configuration¶

`VITE_API_URL`¶

Required: No (has default)

Default: http://localhost:8000/api/v1

Description: Backend API URL that the frontend connects to

Example:

# Same-host deployment (default)
VITE_API_URL=http://localhost:8000/api/v1

# Different host
VITE_API_URL=https://api.example.com/api/v1

# Behind reverse proxy
VITE_API_URL=https://newhires-api.example.com/api/v1

Note

If frontend and backend are on the same host, leave this at default. If using a reverse proxy or separate hosts, update accordingly.

Complete .env Template¶

Minimal Production Configuration¶

###############################
# Docker Image Configuration
###############################
IMAGE_TAG=sha-a85b396

###############################
# AWS Bedrock Configuration
###############################
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1

###############################
# Database Configuration
###############################
POSTGRES_PASSWORD=ChangeThisSecurePassword123!

Full Configuration with All Options¶

###############################
# Docker Image Configuration
###############################
IMAGE_TAG=sha-a85b396

###############################
# AWS Bedrock Configuration
###############################
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1

# Optional: Override default model
BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-5-20250929-v1:0

###############################
# Database Configuration
###############################
POSTGRES_DB=newhires
POSTGRES_USER=newhires
POSTGRES_PASSWORD=ChangeThisSecurePassword123!

###############################
# Worker Configuration
###############################
# Polling interval in seconds (default: 5)
POLL_INTERVAL=5

# Maximum concurrent Bedrock API calls (default: 2)
MAX_CONCURRENT_BEDROCK_CALLS=2

# Maximum retry attempts per job (default: 5)
MAX_AI_ATTEMPTS=5

###############################
# Frontend Configuration
###############################
# Backend API URL (default: http://localhost:8000/api/v1)
VITE_API_URL=http://localhost:8000/api/v1

Environment-Specific Configurations¶

Development Environment¶

IMAGE_TAG=sha-latest
AWS_ACCESS_KEY_ID=AKIA_DEV_KEY
AWS_SECRET_ACCESS_KEY=dev_secret_key
AWS_REGION=us-east-1
POSTGRES_PASSWORD=dev_password
MAX_CONCURRENT_BEDROCK_CALLS=1
POLL_INTERVAL=10

Staging Environment¶

IMAGE_TAG=sha-staging-version
AWS_ACCESS_KEY_ID=AKIA_STAGING_KEY
AWS_SECRET_ACCESS_KEY=staging_secret_key
AWS_REGION=us-east-1
POSTGRES_PASSWORD=staging_secure_password
MAX_CONCURRENT_BEDROCK_CALLS=2
POLL_INTERVAL=5

Production Environment¶

IMAGE_TAG=sha-a85b396
AWS_ACCESS_KEY_ID=AKIA_PRODUCTION_KEY
AWS_SECRET_ACCESS_KEY=production_secret_key_very_secure
AWS_REGION=us-east-1
POSTGRES_PASSWORD=ProductionSecureP@ssw0rd!2024
MAX_CONCURRENT_BEDROCK_CALLS=3
POLL_INTERVAL=5
MAX_AI_ATTEMPTS=5

Validation and Testing¶

Verify Configuration¶

# Check .env file exists
ls -la .env

# Check permissions (should be 600)
ls -l .env

# Verify required variables are set
grep -E "AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_REGION|IMAGE_TAG" .env

# Check for placeholder values
grep -E "EXAMPLE|changeme|your_" .env
# Should return nothing - all placeholders should be replaced!

Test AWS Credentials¶

# Export credentials
export AWS_ACCESS_KEY_ID="value_from_env"
export AWS_SECRET_ACCESS_KEY="value_from_env"
export AWS_REGION="us-east-1"

# Test Bedrock access
aws bedrock list-foundation-models --region us-east-1 --query 'modelSummaries[?contains(modelId, `claude`)].modelId'

# Should list available Claude models

Test in Containers¶

# Start services with .env
docker-compose -f docker-compose.prod.yml up -d

# Verify workers can access AWS
docker logs newhires-workers --tail=50

# Should see: "Worker polling for jobs" (not AWS errors)

# Check backend can connect to database
docker logs newhires-backend --tail=50

# Should see: "Application startup complete"

Troubleshooting¶

"Missing required environment variable"¶

Cause: Required variable not set in .env

Solution: Check all required variables are present and not empty

grep -E "AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_REGION|IMAGE_TAG" .env

"Invalid AWS credentials"¶

Cause: AWS credentials are incorrect or expired

Solution: 1. Verify credentials in AWS Console → IAM → Users → Security credentials 2. Create new access key if needed 3. Update .env with correct values 4. Restart services: docker-compose -f docker-compose.prod.yml restart

"Could not connect to the endpoint URL"¶

Cause: Wrong AWS region or network connectivity issue

Solution: 1. Verify AWS_REGION=us-east-1 in .env 2. Test network: curl https://bedrock-runtime.us-east-1.amazonaws.com 3. Check firewall allows HTTPS outbound to AWS

"Access denied to foundation model"¶

Cause: Bedrock model access not enabled

Solution: Enable model access in AWS Bedrock console (see AWS Setup)

Database connection errors¶

Cause: Wrong database credentials or database not running

Solution:

# Verify database is running
docker ps | grep newhires-db

# Check credentials match
grep POSTGRES .env

# Test connection
docker exec newhires-db psql -U newhires -d newhires -c "SELECT 1;"

Security Best Practices¶

File Permissions¶

# Secure the .env file
chmod 600 .env

# Verify ownership
chown your-user:your-user .env

# Check permissions
ls -l .env
# Should show: -rw------- (only owner can read/write)

Credential Rotation¶

AWS Credentials: 1. Create new access key in AWS IAM 2. Update .env with new credentials 3. Restart services 4. Verify services work with new credentials 5. Delete old access key in AWS IAM

Recommended Schedule: Every 90 days

Database Password: 1. Stop services: docker-compose -f docker-compose.prod.yml down 2. Update POSTGRES_PASSWORD in .env 3. Remove database volume: docker volume rm newhires-reporting_postgres-data 4. Start services: docker-compose -f docker-compose.prod.yml up -d 5. Run migrations: docker exec newhires-backend alembic upgrade head

Database Password Change

Changing database password requires recreating the database volume. Backup data first!

Do Not Commit¶

Add to .gitignore:

.env
.env.local
.env.production
.env.*.local

Secrets Management (Advanced)¶

For production deployments, consider using: - AWS Secrets Manager: Store credentials in AWS - HashiCorp Vault: Centralized secrets management - Docker Secrets: Swarm mode secret management - Kubernetes Secrets: For K8s deployments

Next Steps¶

Deploy with Docker Compose - Use your configured .env
AWS Bedrock Setup - Get AWS credentials
Health Monitoring - Monitor your deployment
Troubleshooting - Fix common issues

Environment Variables Reference¶

Overview¶

Quick Setup¶

Required Variables¶

Docker Image Configuration¶

IMAGE_TAG¶

AWS Bedrock Configuration¶

AWS_ACCESS_KEY_ID¶

AWS_SECRET_ACCESS_KEY¶

AWS_REGION¶

Database Configuration¶

POSTGRES_DB¶

POSTGRES_USER¶

POSTGRES_PASSWORD¶

Optional Variables¶

AI Model Configuration¶

BEDROCK_MODEL_ID¶

Worker Configuration¶

POLL_INTERVAL¶

MAX_CONCURRENT_BEDROCK_CALLS¶

MAX_AI_ATTEMPTS¶

Frontend Configuration¶

VITE_API_URL¶

Complete .env Template¶

Minimal Production Configuration¶

Full Configuration with All Options¶

Environment-Specific Configurations¶

Development Environment¶

Staging Environment¶

Production Environment¶

Validation and Testing¶

Verify Configuration¶

Test AWS Credentials¶

Test in Containers¶

Troubleshooting¶

"Missing required environment variable"¶

"Invalid AWS credentials"¶

"Could not connect to the endpoint URL"¶

"Access denied to foundation model"¶

Database connection errors¶

Security Best Practices¶

File Permissions¶

Credential Rotation¶

Do Not Commit¶

Secrets Management (Advanced)¶

Next Steps¶

`IMAGE_TAG`¶

`AWS_ACCESS_KEY_ID`¶

`AWS_SECRET_ACCESS_KEY`¶

`AWS_REGION`¶

`POSTGRES_DB`¶

`POSTGRES_USER`¶

`POSTGRES_PASSWORD`¶

`BEDROCK_MODEL_ID`¶

`POLL_INTERVAL`¶

`MAX_CONCURRENT_BEDROCK_CALLS`¶

`MAX_AI_ATTEMPTS`¶

`VITE_API_URL`¶