Comprehensive guide to deploying the Tara meditation platform to staging and production environments.
Table of Contents#
- Deployment Architecture
- Environment Overview
- Web Deployment (Vercel)
- API Deployment (AWS ECS)
- Mobile Deployment (App Stores)
- Database Migrations
- Environment Variables
- CI/CD Pipelines
- Monitoring & Observability
- Rollback Procedures
- Security Considerations
Deployment Architecture#
┌─────────────────────────────────────────────────────────────────────────────┐
│ Tara Deployment Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Client Layer │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │ Web App │ │ iOS App │ │ Android App │ │ │
│ │ │ (Vercel) │ │ (App Store) │ │ (Play Store) │ │ │
│ │ └──────┬───────┘ └──────┬───────┘ └────────────┬─────────────┘ │ │
│ │ │ │ │ │ │
│ └─────────┼─────────────────┼────────────────────────┼────────────────┘ │
│ │ │ │ │
│ └─────────────────┼────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CDN / Edge Layer │ │
│ ├─────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌────────────────────────────────┐ │ │
│ │ │ Vercel Edge │ │ CloudFront (API) │ │ │
│ │ │ (Web + Assets) │ │ (API Gateway) │ │ │
│ │ └──────────┬──────────┘ └───────────────┬────────────────┘ │ │
│ │ │ │ │ │
│ └─────────────┼───────────────────────────────────┼───────────────────┘ │
│ │ │ │
│ │ ▼ │
│ ┌─────────────┼─────────────────────────────────────────────────────────┐ │
│ │ │ Application Layer │ │
│ ├─────────────┼─────────────────────────────────────────────────────────┤ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ AWS ECS (Fargate) │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ Tara API Service │ │ │ │
│ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │
│ │ │ │ │ Task 1 │ │ Task 2 │ │ Task 3 │ │ Task N │ │ │ │ │
│ │ │ │ │ (API) │ │ (API) │ │ (API) │ │ (API) │ │ │ │ │
│ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ Application Load Balancer │ │ │
│ │ └────────────────────────────┼────────────────────────────────────┘ │ │
│ │ │ │ │
│ └───────────────────────────────┼────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────┼────────────────────────────────────────┐ │
│ │ ▼ Data Layer │ │
│ ├────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │ │
│ │ │ RDS │ │ ElastiCache │ │ S3 │ │ Secrets │ │ │
│ │ │ PostgreSQL │ │ Redis │ │ (Media) │ │ Manager │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ └───────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Environment Overview#
Environments#
| Environment | Purpose | URL | Auto-Deploy |
|---|---|---|---|
| Development | Local development | localhost:* |
N/A |
| Preview | PR previews | pr-*.vercel.app |
On PR |
| Staging | Pre-production testing | api.staging.tara.app |
On main |
| Production | Live application | api.tara.app, tara.app |
On release |
Deployment Triggers#
| Component | Staging Trigger | Production Trigger |
|---|---|---|
| Web | Push to main |
Release published |
| API | Push to main |
Release published |
| Mobile | Manual via EAS | App Store submission |
Web Deployment (Vercel)#
Overview#
The Tara web application is deployed to Vercel with:
- Automatic preview deployments for PRs
- Staging deployments on
mainbranch - Production deployments on releases
Configuration#
Vercel Project Settings:
# Project name
tara-web
# Framework preset
Next.js
# Build command
pnpm nx build @tara/web
# Output directory
apps/tara/web/.next
# Install command
pnpm install --frozen-lockfile
# Root directory
apps/tara/web
Preview Deployments#
Every PR automatically creates a preview deployment:
- PR opened/updated against
mainordevelop - CI workflow detects Tara web changes
- Vercel builds and deploys preview
- PR comment updated with preview URL
- Preview cleaned up when PR closes
Preview URL format: tara-web-{hash}.vercel.app
Staging Deployment#
Triggered automatically on push to main:
# .github/workflows/tara-web-deploy.yml
on:
push:
branches: [main]
paths:
- 'apps/tara/web/**'
- 'libs/tara/**'
Staging URL: https://staging.tara.app
Production Deployment#
Triggered on GitHub release:
on:
release:
types: [published]
Production URL: https://tara.app
Manual Deployment#
# Install Vercel CLI
npm i -g vercel
# Login
vercel login
# Deploy to preview
cd apps/tara/web
vercel
# Deploy to production
vercel --prod
Environment Variables#
Configure in Vercel dashboard or via CLI:
# Set staging variable
vercel env add NEXT_PUBLIC_API_BASE_URL staging
# Set production variable
vercel env add NEXT_PUBLIC_API_BASE_URL production
# Pull environment to local
vercel env pull .env.local
Required Variables:
| Variable | Staging | Production |
|---|---|---|
NEXT_PUBLIC_API_BASE_URL |
https://api.staging.tara.app |
https://api.tara.app |
NEXT_PUBLIC_WS_URL |
wss://api.staging.tara.app |
wss://api.tara.app |
NEXT_PUBLIC_CDN_URL |
https://cdn.staging.tara.app |
https://cdn.tara.app |
NEXT_PUBLIC_ENVIRONMENT |
staging |
production |
NEXT_PUBLIC_SENTRY_DSN |
Sentry DSN | Sentry DSN |
API Deployment (AWS ECS)#
Overview#
The Tara API is deployed to AWS ECS (Fargate) with:
- Multi-stage Docker builds
- Blue-green deployments
- Auto-scaling based on CPU/memory
- Health checks and circuit breakers
Infrastructure Components#
| Component | Purpose | Service |
|---|---|---|
| Container Registry | Docker image storage | ECR |
| Container Orchestration | Service management | ECS Fargate |
| Load Balancer | Traffic distribution | ALB |
| Database | PostgreSQL | RDS |
| Cache | Redis | ElastiCache |
| Object Storage | Media files | S3 |
| Secrets | Sensitive configuration | Secrets Manager |
| DNS | Domain management | Route 53 |
| CDN | API caching (optional) | CloudFront |
Docker Build#
The API uses a multi-stage Dockerfile:
# Build stages:
# 1. base - Node.js with system dependencies
# 2. deps - Install all dependencies
# 3. builder - Build the application
# 4. prod-deps - Production dependencies only
# 5. runner - Final production image
Build locally:
# Build image
docker build -t tara-api:latest -f apps/tara/api/Dockerfile .
# Run locally
docker run -p 3000:3000 \
-e DATABASE_URL=postgresql://... \
-e REDIS_URL=redis://... \
tara-api:latest
ECS Task Definition#
{
"family": "tara-api",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "512",
"memory": "1024",
"containerDefinitions": [
{
"name": "tara-api",
"image": "123456789.dkr.ecr.us-east-1.amazonaws.com/tara-api:latest",
"portMappings": [
{
"containerPort": 3000,
"protocol": "tcp"
}
],
"healthCheck": {
"command": [
"CMD-SHELL",
"curl -f http://localhost:3000/health || exit 1"
],
"interval": 30,
"timeout": 10,
"retries": 3,
"startPeriod": 40
},
"environment": [
{ "name": "NODE_ENV", "value": "production" },
{ "name": "PORT", "value": "3000" }
],
"secrets": [
{ "name": "DATABASE_URL", "valueFrom": "arn:aws:secretsmanager:..." },
{ "name": "JWT_SECRET", "valueFrom": "arn:aws:secretsmanager:..." }
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/tara-api",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
}
}
]
}
Deployment Process#
-
Build & Test
- Run unit tests
- Run integration tests (optional)
- Build Docker image
-
Push to ECR
- Tag image with commit SHA
- Push to ECR repository
-
Database Migration
- Run migration task before deployment
- Verify migration success
-
Deploy to ECS
- Update service with new task definition
- Blue-green deployment with circuit breaker
- Wait for service stability
-
Health Verification
- Check health endpoint
- Verify API responses
- Monitor error rates
Manual Deployment#
# Authenticate with ECR
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
# Build and tag
docker build -t tara-api:latest -f apps/tara/api/Dockerfile .
docker tag tara-api:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/tara-api:latest
# Push to ECR
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/tara-api:latest
# Update ECS service
aws ecs update-service \
--cluster tara-production \
--service tara-api \
--force-new-deployment
# Wait for stability
aws ecs wait services-stable \
--cluster tara-production \
--services tara-api
Scaling Configuration#
# Auto-scaling policy
scaling:
min_capacity: 2
max_capacity: 10
target_tracking:
- metric: ECSServiceAverageCPUUtilization
target: 70
- metric: ECSServiceAverageMemoryUtilization
target: 80
- metric: ALBRequestCountPerTarget
target: 1000
Mobile Deployment (App Stores)#
Overview#
Mobile apps are built and submitted via Expo Application Services (EAS).
EAS Configuration#
eas.json:
{
"cli": {
"version": ">= 5.0.0"
},
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
},
"preview": {
"distribution": "internal"
},
"production": {
"autoIncrement": true
}
},
"submit": {
"production": {
"ios": {
"appleId": "developer@tara.app",
"ascAppId": "1234567890",
"appleTeamId": "ABCDE12345"
},
"android": {
"serviceAccountKeyPath": "./google-play-key.json",
"track": "production"
}
}
}
}
Build Commands#
cd apps/tara/mobile
# Development build (with dev client)
eas build --profile development --platform all
# Preview build (internal distribution)
eas build --profile preview --platform all
# Production build
eas build --profile production --platform all
Submit to Stores#
# Submit iOS to App Store
eas submit --platform ios --latest
# Submit Android to Play Store
eas submit --platform android --latest
# Submit both
eas submit --platform all --latest
Version Management#
// app.json
{
"expo": {
"version": "1.0.0",
"ios": {
"buildNumber": "1"
},
"android": {
"versionCode": 1
}
}
}
Increment versions:
# Patch version (1.0.0 -> 1.0.1)
npm version patch
# Minor version (1.0.0 -> 1.1.0)
npm version minor
# Major version (1.0.0 -> 2.0.0)
npm version major
Release Checklist#
iOS (App Store):
- Update version and build number
- Build production profile
- Test on physical devices
- Capture screenshots
- Update App Store listing
- Submit for review
- Monitor review status
Android (Play Store):
- Update version and versionCode
- Build production profile
- Test on physical devices
- Capture screenshots
- Update Play Store listing
- Submit to internal testing
- Promote to production
Database Migrations#
Migration Strategy#
- Forward-only migrations - Never delete or modify data destructively
- Zero-downtime - Migrations must be backward compatible
- Separate from deployment - Run migrations before service update
Running Migrations#
Staging:
# Via CI/CD (automatic)
# Migrations run as ECS task before deployment
# Manual
aws ecs run-task \
--cluster tara-staging \
--task-definition tara-api-migrate \
--launch-type FARGATE \
--network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx],assignPublicIp=ENABLED}"
Production:
# Via CI/CD (requires approval)
# Manual migration for critical changes
# SSH tunnel to RDS
aws ssm start-session \
--target i-xxxxx \
--document-name AWS-StartPortForwardingSessionToRemoteHost \
--parameters '{"host":["tara-prod.xxxxx.us-east-1.rds.amazonaws.com"],"portNumber":["5432"],"localPortNumber":["5432"]}'
# Run migrations
DATABASE_URL=postgresql://... pnpm db:migrate
Rollback Strategy#
- Schema changes - Create reverse migration
- Data changes - Restore from backup
- Emergency - Point-in-time recovery (RDS)
# Restore RDS to point in time
aws rds restore-db-instance-to-point-in-time \
--source-db-instance-identifier tara-production \
--target-db-instance-identifier tara-production-restored \
--restore-time 2024-01-15T10:00:00Z
Environment Variables#
GitHub Secrets#
Required for all deployments:
| Secret | Description |
|---|---|
VERCEL_TOKEN |
Vercel API token |
VERCEL_ORG_ID |
Vercel organization ID |
TARA_WEB_VERCEL_PROJECT_ID |
Vercel project ID |
AWS_REGION |
AWS region (us-east-1) |
AWS_STAGING_ROLE_ARN |
IAM role for staging |
AWS_PRODUCTION_ROLE_ARN |
IAM role for production |
CODECOV_TOKEN |
Codecov upload token |
Staging Environment:
| Secret | Description |
|---|---|
AWS_STAGING_SUBNETS |
VPC subnet IDs |
AWS_STAGING_SG |
Security group ID |
TARA_STAGING_API_URL |
Staging API URL |
TARA_STAGING_WS_URL |
Staging WebSocket URL |
TARA_STAGING_CDN_URL |
Staging CDN URL |
Production Environment:
| Secret | Description |
|---|---|
AWS_PRODUCTION_SUBNETS |
VPC subnet IDs |
AWS_PRODUCTION_SG |
Security group ID |
TARA_PROD_API_URL |
Production API URL |
TARA_PROD_WS_URL |
Production WebSocket URL |
TARA_PROD_CDN_URL |
Production CDN URL |
Monitoring & Notifications:
| Secret | Description |
|---|---|
TARA_SENTRY_DSN |
Sentry error tracking DSN |
TARA_SLACK_WEBHOOK_URL |
Slack deployment notifications |
E2E Testing:
| Secret | Description |
|---|---|
TARA_E2E_USER_EMAIL |
E2E test user email |
TARA_E2E_USER_PASSWORD |
E2E test user password |
AWS Secrets Manager#
API Secrets (stored in Secrets Manager):
{
"DATABASE_URL": "postgresql://user:pass@host:5432/tara",
"REDIS_URL": "redis://host:6379",
"JWT_SECRET": "xxx",
"JWT_REFRESH_SECRET": "xxx",
"SESSION_SECRET": "xxx",
"STRIPE_SECRET_KEY": "sk_live_xxx",
"APPLE_SHARED_SECRET": "xxx",
"REVENECAT_API_KEY": "xxx"
}
CI/CD Pipelines#
Overview#
┌─────────────────────────────────────────────────────────────────────────┐
│ CI/CD Pipeline Flow │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Push │───►│ Lint │───►│ Build │───►│ Test │ │
│ │ / PR │ │ Type │ │ │ │ Unit/Integration │ │
│ └──────────┘ └──────────┘ └──────────┘ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Deploy Staging │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Web: Vercel │ API: ECS │ DB: Migrate │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ E2E Tests │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Playwright (Web) │ Maestro (Mobile) │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ (Release only) │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Deploy Production │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Web: Vercel │ API: ECS │ DB: Migrate │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Workflow Files#
| Workflow | Trigger | Purpose |
|---|---|---|
tara-ci.yml |
Push, PR | Quality, build, test |
tara-web-deploy.yml |
Push (main), Release | Web deployment |
tara-web-preview.yml |
PR | Preview deployments |
tara-api-deploy.yml |
Push (main), Release | API deployment |
Running CI Locally#
# Lint
pnpm nx run-many -t lint -p @tara/api,@tara/web,@tara/mobile
# Type check
pnpm nx run-many -t type-check -p @tara/api,@tara/web,@tara/mobile
# Build
pnpm nx run-many -t build -p @tara/api,@tara/web
# Test
pnpm nx run-many -t test -p @tara/api,@tara/web
# E2E (requires services running)
pnpm nx e2e @tara/web
Monitoring & Observability#
Health Checks#
API Health Endpoint:
# Basic health
curl https://api.tara.app/health
# Detailed readiness
curl https://api.tara.app/ready
Response format:
{
"status": "healthy",
"checks": {
"database": "ok",
"redis": "ok",
"storage": "ok"
},
"timestamp": "2024-01-15T10:30:00.000Z",
"version": "1.0.0"
}
Logging#
Log destinations:
- API: CloudWatch Logs (
/ecs/tara-api) - Web: Vercel Logs
- Mobile: Sentry
Log format (structured JSON):
{
"level": "info",
"message": "Request completed",
"requestId": "xxx",
"method": "GET",
"path": "/api/v1/meditations",
"statusCode": 200,
"duration": 45,
"timestamp": "2024-01-15T10:30:00.000Z"
}
Error Tracking (Sentry)#
// Initialize in API
import * as Sentry from '@sentry/node';
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.NODE_ENV,
release: process.env.VERSION,
tracesSampleRate: 0.1,
});
// Initialize in Web
import * as Sentry from '@sentry/nextjs';
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
});
Metrics#
CloudWatch Metrics:
- ECS CPU/Memory utilization
- ALB request count
- RDS connections
- ElastiCache hit rate
Custom Metrics:
- API response times
- Authentication success/failure
- Session completions
- Subscription events
Alerting#
CloudWatch Alarms:
| Alarm | Threshold | Action |
|---|---|---|
| API Error Rate | > 5% for 5 minutes | Slack, PagerDuty |
| API Latency P95 | > 1000ms for 5 minutes | Slack |
| Database Connections | > 80% for 10 minutes | Slack |
| ECS Task Failures | > 2 in 5 minutes | Slack, PagerDuty |
Rollback Procedures#
Web (Vercel)#
# List deployments
vercel ls
# Rollback to previous
vercel rollback <deployment-url>
# Or via dashboard
# Vercel Dashboard → Deployments → "..." → Promote to Production
API (ECS)#
# List task definition revisions
aws ecs list-task-definitions --family-prefix tara-api
# Update service to previous revision
aws ecs update-service \
--cluster tara-production \
--service tara-api \
--task-definition tara-api:42 # Previous revision
# Wait for stability
aws ecs wait services-stable \
--cluster tara-production \
--services tara-api
Database#
# Point-in-time recovery
aws rds restore-db-instance-to-point-in-time \
--source-db-instance-identifier tara-production \
--target-db-instance-identifier tara-production-restored \
--restore-time 2024-01-15T10:00:00Z
# Snapshot restore
aws rds restore-db-instance-from-db-snapshot \
--db-instance-identifier tara-production-restored \
--db-snapshot-identifier tara-production-backup-20240115
Emergency Procedures#
-
Service degradation detected
- Check CloudWatch alarms
- Review recent deployments
- Rollback if recent change
-
Complete outage
- Check AWS Health Dashboard
- Verify all ECS tasks running
- Check RDS/ElastiCache status
- Review security group changes
-
Data corruption
- Stop writes immediately
- Assess scope of corruption
- Restore from backup/PITR
- Notify affected users
Security Considerations#
Secrets Management#
- All secrets stored in AWS Secrets Manager
- GitHub secrets for CI/CD only
- No secrets in code or environment files
- Regular secret rotation
Network Security#
- VPC with private subnets for data layer
- Security groups restrict access
- WAF on CloudFront/ALB
- TLS 1.3 everywhere
Access Control#
- IAM roles with least privilege
- MFA required for production access
- Audit logging enabled
- Regular access reviews
Compliance#
- GDPR-compliant data handling
- SOC 2 Type II (in progress)
- Regular security audits
- Penetration testing annually