mockupAWS/docs/INFRASTRUCTURE_SETUP.md

MockupAWS v0.5.0 Infrastructure Setup Guide

This document provides setup instructions for the infrastructure components introduced in v0.5.0.

Table of Contents

1. Secrets Management
2. Email Configuration
3. Cron Job Deployment

---

Secrets Management

Quick Start

Generate secure secrets automatically:

# Make the script executable
chmod +x scripts/setup-secrets.sh

# Run the setup script
./scripts/setup-secrets.sh

# Or specify a custom output file
./scripts/setup-secrets.sh /path/to/.env.production

Manual Secret Generation

If you prefer to generate secrets manually:

# Generate JWT Secret (256 bits)
openssl rand -hex 32

# Generate API Key Encryption Key
openssl rand -hex 16

# Generate secure random password
date +%s | sha256sum | base64 | head -c 32 ; echo

Required Secrets

Variable	Purpose	Generation
JWT_SECRET_KEY	Sign JWT tokens	openssl rand -hex 32
DATABASE_URL	PostgreSQL connection	Update password manually
SENDGRID_API_KEY	Email delivery	From SendGrid dashboard
AWS_ACCESS_KEY_ID	AWS SES (optional)	From AWS IAM
AWS_SECRET_ACCESS_KEY	AWS SES (optional)	From AWS IAM

Security Best Practices

1. Never commit .env files to git

   # Ensure .env is in .gitignore
   echo ".env" >> .gitignore
   

2. Use different secrets for each environment

   • Development: .env
   • Staging: .env.staging
   • Production: Use secrets manager (AWS Secrets Manager, HashiCorp Vault)

3. Rotate secrets regularly

   • JWT secrets: Every 90 days
   • API keys: Every 30 days
   • Database passwords: Every 90 days

4. Production Recommendations

   • Use AWS Secrets Manager or HashiCorp Vault
   • Enable encryption at rest
   • Use IAM roles instead of hardcoded AWS credentials when possible

---

Email Configuration

Option 1: SendGrid (Recommended for v0.5.0)

Free Tier: 100 emails/day

Setup Steps

1. Create SendGrid Account

   https://signup.sendgrid.com/
   

2. Generate API Key

   • Go to: https://app.sendgrid.com/settings/api_keys
   • Click "Create API Key"
   • Name: mockupAWS-production
   • Permissions: Full Access (or restrict to "Mail Send")
   • Copy the key (starts with SG.)

3. Verify Sender Domain

   • Go to: https://app.sendgrid.com/settings/sender_auth
   • Choose "Domain Authentication"
   • Follow DNS configuration steps
   • Wait for verification (usually instant, up to 24 hours)

4. Configure Environment Variables

   EMAIL_PROVIDER=sendgrid
   SENDGRID_API_KEY=SG.your_actual_api_key_here
   EMAIL_FROM=noreply@yourdomain.com
   

Testing SendGrid

# Run the email test script (to be created by backend team)
python -m src.scripts.test_email --to your@email.com

Option 2: AWS SES (Amazon Simple Email Service)

Free Tier: 62,000 emails/month (when sending from EC2)

Setup Steps

1. Configure SES in AWS Console

   https://console.aws.amazon.com/ses/
   

2. Verify Email or Domain

   • For testing: Verify individual email address
   • For production: Verify entire domain

3. Get AWS Credentials

   • Create IAM user with ses:SendEmail and ses:SendRawEmail permissions
   • Generate Access Key ID and Secret Access Key

4. Move Out of Sandbox (required for production)

   • Open a support case to increase sending limits
   • Provide use case and estimated volume

5. Configure Environment Variables

   EMAIL_PROVIDER=ses
   AWS_ACCESS_KEY_ID=AKIA...
   AWS_SECRET_ACCESS_KEY=...
   AWS_REGION=us-east-1
   EMAIL_FROM=noreply@yourdomain.com
   

Email Testing Guide

Development Testing

# 1. Start the backend
uv run uvicorn src.main:app --reload

# 2. Send test email via API
curl -X POST http://localhost:8000/api/v1/test/email \
  -H "Content-Type: application/json" \
  -d '{"to": "your@email.com", "subject": "Test", "body": "Hello"}'

Email Templates

The following email templates are available in v0.5.0:

Template	Trigger	Variables
welcome	User registration	{{name}}, {{login_url}}
report_ready	Report generation complete	{{report_name}}, {{download_url}}
scheduled_report	Scheduled report delivery	{{scenario_name}}, {{attachment}}
password_reset	Password reset request	{{reset_url}}, {{expires_in}}

---

Cron Job Deployment

Overview

Three deployment options are available for report scheduling:

Option	Pros	Cons	Best For
1. APScheduler (in-process)	Simple, no extra services	Runs in API container	Small deployments
2. APScheduler (standalone)	Separate scaling, resilient	Requires extra container	Medium deployments
3. Celery + Redis	Distributed, scalable, robust	More complex setup	Large deployments

Option 1: APScheduler In-Process (Simplest)

No additional configuration needed. The scheduler runs within the main backend process.

Pros:

• Zero additional setup
• Works immediately

Cons:

• API restarts interrupt scheduled jobs
• Cannot scale independently

Enable:

SCHEDULER_ENABLED=true
SCHEDULER_INTERVAL_MINUTES=5

Option 2: Standalone Scheduler Service (Recommended for v0.5.0)

Runs the scheduler in a separate Docker container.

Deployment:

# Start with main services
docker-compose -f docker-compose.yml -f docker-compose.scheduler.yml up -d

# View logs
docker-compose -f docker-compose.scheduler.yml logs -f scheduler

Pros:

• Independent scaling
• Resilient to API restarts
• Clear separation of concerns

Cons:

• Requires additional container

Option 3: Celery + Redis (Production-Scale)

For high-volume or mission-critical scheduling.

Prerequisites:

# Add to requirements.txt
celery[redis]>=5.0.0
redis>=4.0.0

Deployment:

# Uncomment celery services in docker-compose.scheduler.yml
docker-compose -f docker-compose.yml -f docker-compose.scheduler.yml up -d

# Scale workers if needed
docker-compose -f docker-compose.scheduler.yml up -d --scale celery-worker=3

Scheduler Configuration

Variable	Default	Description
SCHEDULER_ENABLED	true	Enable/disable scheduler
SCHEDULER_INTERVAL_MINUTES	5	Check interval for due jobs
REDIS_URL	redis://localhost:6379/0	Redis connection (Celery)

Monitoring Scheduled Jobs

# View scheduler logs
docker-compose logs -f scheduler

# Check Redis queue (if using Celery)
docker-compose exec redis redis-cli llen celery

# Monitor Celery workers
docker-compose exec celery-worker celery -A src.jobs.celery_app inspect active

Production Deployment Checklist

• Secrets generated and secured
• Email provider configured and tested
• Database migrations applied
• Redis running (if using Celery)
• Scheduler container started
• Logs being collected
• Health checks configured
• Monitoring alerts set up

---

Troubleshooting

Email Not Sending

# Check email configuration
echo $EMAIL_PROVIDER
echo $SENDGRID_API_KEY

# Test SendGrid API directly
curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personalizations":[{"to":[{"email":"test@example.com"}]}],"from":{"email":"noreply@mockupaws.com"},"subject":"Test","content":[{"type":"text/plain","value":"Hello"}]}'

Scheduler Not Running

# Check if scheduler container is running
docker-compose ps

# View scheduler logs
docker-compose logs scheduler

# Restart scheduler
docker-compose restart scheduler

JWT Errors

# Verify JWT secret length (should be 32+ chars)
echo -n $JWT_SECRET_KEY | wc -c

# Regenerate if needed
openssl rand -hex 32

---

Additional Resources

• SendGrid Documentation
• AWS SES Documentation
• APScheduler Documentation
• Celery Documentation