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](#secrets-management)
2. [Email Configuration](#email-configuration)
3. [Cron Job Deployment](#cron-job-deployment)

---

## Secrets Management

### Quick Start

Generate secure secrets automatically:

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

```bash
# 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**
   ```bash
   # 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**
   ```bash
   EMAIL_PROVIDER=sendgrid
   SENDGRID_API_KEY=SG.your_actual_api_key_here
   EMAIL_FROM=noreply@yourdomain.com
   ```

#### Testing SendGrid

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

```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
# Add to requirements.txt
celery[redis]>=5.0.0
redis>=4.0.0
```

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

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

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

```bash
# Check if scheduler container is running
docker-compose ps

# View scheduler logs
docker-compose logs scheduler

# Restart scheduler
docker-compose restart scheduler
```

### JWT Errors

```bash
# 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](https://docs.sendgrid.com/)
- [AWS SES Documentation](https://docs.aws.amazon.com/ses/)
- [APScheduler Documentation](https://apscheduler.readthedocs.io/)
- [Celery Documentation](https://docs.celeryq.dev/)