Skip to main content

Deployment

This section covers everything related to deploying and releasing BookWish across all platforms.

  • Release Process - How to create and publish new releases
  • CI/CD Pipeline - Continuous integration and deployment automation
  • Environments - Development, staging, and production configurations
  • Monitoring - Application monitoring, logging, and error tracking

Deployment Targets​

BookWish is deployed across multiple platforms:

Mobile Apps​

PlatformDistributionDeployment Method
iOSApp Store + TestFlightGitHub Actions → TestFlight → App Store
AndroidGoogle Play StoreGitHub Actions → Play Console

App Details:

  • App Name: BookWish
  • Version: 3.1.0 (Flutter rewrite)
  • iOS Bundle ID: Willow-Tree-Creative.bw-app
  • Android Package: com.willowtreecreative.bookwish
  • Apple ID: 6748889200

Web Application​

ComponentHostURLDeployment
Flutter WebVercelapp.bookwish.ioAuto-deploy from main
Store WebsitesVercelbookwish.shop/[store-slug]Auto-deploy from main

Backend Services​

ServiceHostURLDeployment
APIRailwayapi.bookwish.ioAuto-deploy from main
DatabaseSupabase(managed)Migrations via Prisma
RedisRailway(internal)Managed service

Quick Deploy Steps​

1. Release a New Version​

For a complete release to all platforms:

# From project root
npm run release

# The script will:
# 1. Prompt for version number (e.g., 3.2.0)
# 2. Update all version files
# 3. Create git commit and tag
# 4. Push to GitHub
# 5. Trigger automated builds

This triggers deployments to:

  • TestFlight (iOS) - ~15-30 minutes
  • Play Store Internal Track (Android) - ~5-10 minutes
  • Vercel (Web) - ~3-5 minutes
  • GitHub Release with changelog

See Release Process for detailed instructions.

2. Deploy Backend Only​

Backend deploys automatically on push to main:

# Push to main branch
git push origin main

# Railway automatically deploys the backend
# Vercel automatically deploys web apps

3. Deploy to Staging​

Staging deploys automatically when merging PRs:

# Merge PR to main
git checkout main
git pull

# Staging deployment happens automatically
# Available at: staging.bookwish.io

See Environments for environment details.

Deployment Architecture​

┌─────────────────┐
│   Git Push      │
│   (main/tag)    │
└────────┬────────┘
         │
         ▼
┌──────────────────────────────┐
│   GitHub Actions Triggered   │
└────────┬─────────────────────┘
         │
    ┌────┴────┬──────────┬─────────────┐
    ▼         ▼          ▼             ▼
┌──────┐ ┌──────┐ ┌──────────┐ ┌──────────────┐
│ iOS  │ │ And- │ │   Web    │ │   Backend    │
│Build │ │roid  │ │  Build   │ │   Deploy     │
│      │ │Build │ │          │ │              │
└───┬──┘ └───┬──┘ └─────┬────┘ └──────┬───────┘
    │        │          │             │
    ▼        ▼          ▼             ▼
┌─────────┐ ┌────────┐ ┌──────┐ ┌──────────┐
│TestFlight│Play Store│Vercel │ │ Railway  │
└─────────┘ └────────┘ └──────┘ └──────────┘

Deployment Workflows​

Automated Deployments​

On Pull Request:

  • Linting (ESLint, Flutter analyze)
  • Type checking
  • Unit tests
  • Integration tests
  • Build validation
  • Preview deployment (web only)

On Merge to Main:

  • All PR checks
  • Deploy to staging
  • Smoke tests
  • Backend deployment (Railway)
  • Web deployment (Vercel)

On Version Tag (v*):

  • Build iOS app → TestFlight
  • Build Android app → Play Store
  • Build web app → Production Vercel
  • Create GitHub release
  • Generate changelog

Manual Deployments​

For emergency fixes or special cases:

# Backend only
cd backend
railway up

# Web only
cd app
vercel --prod

# iOS (local build)
cd app/ios
bundle exec fastlane release

# Android (local build)
cd app/android
bundle exec fastlane release

Environment Overview​

EnvironmentPurposeURLUpdates
DevelopmentLocal developmentlocalhostManual
StagingTesting & QAstaging.bookwish.ioAuto on merge
ProductionLive usersbookwish.ioManual release

See Environments for complete configuration details.

CI/CD Pipeline​

BookWish uses GitHub Actions for all automation:

Key Workflows​

  1. Pull Request Checks (.github/workflows/ci.yml)

    • Runs on every PR
    • Linting, testing, building
    • Must pass before merge

  2. Release Workflow (.github/workflows/release.yml)

    • Triggers on version tags
    • Builds all platforms
    • Deploys to production

  3. Documentation (.github/workflows/docs.yml)

    • Deploys documentation site
    • Updates on docs changes

See CI/CD Pipeline for workflow details.

Pre-Deployment Checklist​

Before releasing to production:

Code Quality​

  • All tests pass locally
  • Linting passes with no errors
  • Type checking passes
  • Build succeeds on all platforms
  • No console.log or print statements
  • No TODO comments in production code

Testing​

  • Manual testing on all platforms
  • Integration tests pass
  • Performance is acceptable
  • No known critical bugs
  • Security vulnerabilities addressed

Database​

  • Migrations are tested in staging
  • Migrations are reversible if needed
  • Backup created before migration
  • Data integrity verified

Documentation​

  • CHANGELOG.md updated
  • API documentation current
  • Breaking changes documented
  • User-facing docs updated

External Dependencies​

  • API keys are current
  • Third-party services tested
  • SSL certificates valid
  • DNS records correct

Post-Deployment Verification​

After deploying to production:

Immediate Checks (0-15 min)​

  • App builds deployed successfully
  • Backend health check passes
  • Database migrations completed
  • Key user flows work
  • No critical errors in logs

Short-term Monitoring (1-24 hrs)​

  • Error rates normal
  • Performance metrics stable
  • User feedback positive
  • No increase in support tickets
  • Analytics tracking correctly

Long-term Monitoring​

  • Monitor error tracking dashboard
  • Check app store reviews
  • Review performance metrics
  • Track user engagement

See Monitoring for monitoring setup.

Deployment Environments​

Development​

  • Purpose: Local development and testing
  • Database: Local PostgreSQL
  • API: localhost:3000
  • Features: Hot reload, debug logging, test data

Staging​

  • Purpose: Pre-production testing and QA
  • Database: Staging database (separate from production)
  • API: staging-api.bookwish.io
  • Features: Auto-deploy from main, test payment keys, weekly data reset

Production​

  • Purpose: Live application for real users
  • Database: Production database (managed, backed up)
  • API: api.bookwish.io
  • Features: Manual releases only, live payment processing, monitoring

Rollback Procedures​

If a deployment causes issues:

Backend Rollback​

# Via Railway CLI
railway rollback [deployment-id]

# Or via Railway dashboard
# → Deployments → Click previous version → Rollback

Database Rollback​

# Revert last migration
npx prisma migrate resolve --rolled-back migration_name

# Or restore from backup
# Via Supabase dashboard → Backups → Restore

Mobile App Rollback​

  • iOS: Remove build from TestFlight/App Store
  • Android: Halt rollout in Play Console
  • Critical: Submit emergency update

Web Rollback​

# Via Vercel
vercel rollback [deployment-url]

# Or in Vercel dashboard
# → Deployments → Previous version → Promote

Common Deployment Issues​

Build Failures​

Issue: Tests fail in CI but pass locally

  • Check environment variables
  • Verify database is seeded
  • Check for race conditions in tests

Issue: Build timeout

  • Increase timeout in workflow
  • Optimize build steps
  • Add dependency caching

Deployment Failures​

Issue: Database migration fails

  • Test migration in staging first
  • Check for conflicting migrations
  • Verify database connectivity

Issue: App not updating

  • Clear CDN cache
  • Verify deployment completed
  • Check app version numbers

Monitoring & Alerts​

Track deployment health with:

Application Monitoring​

  • Railway Dashboard - Backend metrics, logs, deployments
  • Vercel Dashboard - Web app performance, analytics
  • App Store Connect - iOS builds, crash reports
  • Play Console - Android releases, ANR reports

Error Tracking​

  • Check logs for unexpected errors
  • Monitor error rates
  • Track user-reported issues
  • Review crash reports

Performance​

  • API response times
  • Database query performance
  • Page load times
  • App startup time

See Monitoring for complete monitoring setup.

Security Considerations​

Deployment Security​

  • All secrets stored in GitHub Secrets
  • Environment variables never committed
  • Different credentials per environment
  • Regular security audits

Production Security​

  • HTTPS/TLS enforced
  • Rate limiting enabled
  • DDoS protection active
  • Database encryption enabled
  • Regular dependency updates

Getting Help​

Resources​

Troubleshooting​

  • Check GitHub Actions logs
  • Review platform-specific dashboards
  • Verify environment variables
  • Check recent changes in git history

Next Steps​

  1. First-time deployment? Start with Release Process
  2. Setting up CI/CD? Read CI/CD Pipeline
  3. Configure environments? See Environments
  4. Set up monitoring? Check Monitoring