release: v0.5.0 - Authentication, API Keys & Advanced Features
Complete v0.5.0 implementation: Database (@db-engineer): - 3 migrations: users, api_keys, report_schedules tables - Foreign keys, indexes, constraints, enums Backend (@backend-dev): - JWT authentication service with bcrypt (cost=12) - Auth endpoints: /register, /login, /refresh, /me - API Keys service with hash storage and prefix validation - API Keys endpoints: CRUD + rotate - Security module with JWT HS256 Frontend (@frontend-dev): - Login/Register pages with validation - AuthContext with localStorage persistence - Protected routes implementation - API Keys management UI (create, revoke, rotate) - Header with user dropdown DevOps (@devops-engineer): - .env.example and .env.production.example - docker-compose.scheduler.yml - scripts/setup-secrets.sh - INFRASTRUCTURE_SETUP.md QA (@qa-engineer): - 85 E2E tests: auth.spec.ts, apikeys.spec.ts, scenarios.spec.ts, regression-v050.spec.ts - auth-helpers.ts with 20+ utility functions - Test plans and documentation Architecture (@spec-architect): - SECURITY.md with best practices - SECURITY-CHECKLIST.md pre-deployment - Updated architecture.md with auth flows - Updated README.md with v0.5.0 features Documentation: - Updated todo.md with v0.5.0 status - Added docs/README.md index - Complete setup instructions Dependencies added: - bcrypt, python-jose, passlib, email-validator Tested: JWT auth flow, API keys CRUD, protected routes, 85 E2E tests ready Closes: v0.5.0 milestone
This commit is contained in:
Luca Sacchi Ricciardi
330
docs/INFRASTRUCTURE_SETUP.md
Normal file
330
docs/INFRASTRUCTURE_SETUP.md
Normal file
@@ -0,0 +1,330 @@
|
||||
# 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/)
|
||||
Reference in New Issue
Block a user