Eve library

Tara Deployment Guide

Guide

Revision 1

On this page

Comprehensive guide to deploying the Tara meditation platform to staging and production environments.

Table of Contents#


Deployment Architecture#

text
┌─────────────────────────────────────────────────────────────────────────────┐
│                         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 main branch
  • Production deployments on releases

Configuration#

Vercel Project Settings:

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

  1. PR opened/updated against main or develop
  2. CI workflow detects Tara web changes
  3. Vercel builds and deploys preview
  4. PR comment updated with preview URL
  5. Preview cleaned up when PR closes

Preview URL format: tara-web-{hash}.vercel.app

Staging Deployment#

Triggered automatically on push to main:

yaml
# .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:

yaml
on:
  release:
    types: [published]

Production URL: https://tara.app

Manual Deployment#

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

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

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:

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

json
{
  "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#

  1. Build & Test

    • Run unit tests
    • Run integration tests (optional)
    • Build Docker image
  2. Push to ECR

    • Tag image with commit SHA
    • Push to ECR repository
  3. Database Migration

    • Run migration task before deployment
    • Verify migration success
  4. Deploy to ECS

    • Update service with new task definition
    • Blue-green deployment with circuit breaker
    • Wait for service stability
  5. Health Verification

    • Check health endpoint
    • Verify API responses
    • Monitor error rates

Manual Deployment#

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

yaml
# 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:

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#

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

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

json
// app.json
{
  "expo": {
    "version": "1.0.0",
    "ios": {
      "buildNumber": "1"
    },
    "android": {
      "versionCode": 1
    }
  }
}

Increment versions:

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

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

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

  1. Schema changes - Create reverse migration
  2. Data changes - Restore from backup
  3. Emergency - Point-in-time recovery (RDS)
bash
# 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):

json
{
  "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#

text
┌─────────────────────────────────────────────────────────────────────────┐
│                         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#

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

bash
# Basic health
curl https://api.tara.app/health

# Detailed readiness
curl https://api.tara.app/ready

Response format:

json
{
  "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):

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)#

typescript
// 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)#

bash
# List deployments
vercel ls

# Rollback to previous
vercel rollback <deployment-url>

# Or via dashboard
# Vercel Dashboard → Deployments → "..." → Promote to Production

API (ECS)#

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

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

  1. Service degradation detected

    • Check CloudWatch alarms
    • Review recent deployments
    • Rollback if recent change
  2. Complete outage

    • Check AWS Health Dashboard
    • Verify all ECS tasks running
    • Check RDS/ElastiCache status
    • Review security group changes
  3. 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

Additional Resources#