TradingAgents/backend/DEPLOYMENT_GUIDE.md

TradingAgents API Deployment Guide

🍎 App Store Deployment Strategy

This guide provides deployment instructions for publishing the TradingAgents iOS app to the Apple App Store.

Phase 1: Railway Deployment (App Store Submission)

Railway provides the quickest path to production with automatic HTTPS - perfect for App Store submission.

🚀 Quick Start (5 minutes)

Step 1: Prepare Repository

1. Ensure all files are committed to GitHub:

   git add .
   git commit -m "Prepare for Railway deployment"
   git push origin main
   

Step 2: Deploy to Railway

1. Go to Railway.app
2. Sign up/Login with your GitHub account
3. Click "New Project" → "Deploy from GitHub repo"
4. Select your TradingAgents repository
5. Railway will auto-detect the Python app and start building

Note: The repository includes special configuration files (nixpacks.toml, runtime.txt) to help Railway detect the Python app in the backend/ directory.

Step 3: Configure Environment Variables

In the Railway dashboard:

1. Go to your project → Variables tab

2. Add these required variables:

   OPENAI_API_KEY=your_actual_openai_key
   FINNHUB_API_KEY=your_actual_finnhub_key
   SERPAPI_API_KEY=your_actual_serpapi_key (optional but recommended)
   

3. Optional variables for better performance:

   DEEP_THINK_MODEL=gpt-4o
   QUICK_THINK_MODEL=gpt-4o-mini
   MAX_DEBATE_ROUNDS=3
   MAX_RISK_DISCUSS_ROUNDS=2
   

Step 4: Get Your Production URL

1. In Railway dashboard, go to Settings → Domains
2. Copy the railway.app URL (e.g., https://tradingagents-production.up.railway.app)
3. Optional: Add a custom domain later

Step 5: Test Your Deployed API

# Test the health endpoint
curl https://your-app.railway.app/health

# Test analysis endpoint
curl -X POST https://your-app.railway.app/analyze \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL"}'

🔧 Troubleshooting Railway Deployment

Build Detection Issues

If Railway says "Nixpacks was unable to generate a build plan":

1. Check root directory files: Ensure these files exist in your root directory:

   • nixpacks.toml ✅ (helps Railway detect Python app)
   • runtime.txt ✅ (specifies Python version)
   • requirements.txt ✅ (copied from backend/)

2. Force redeploy: In Railway dashboard, click "Redeploy"

3. Check logs: Look at build logs for specific error messages

Build Failures

If the build fails:

• Check that all dependencies in requirements.txt are valid
• Ensure Python version compatibility (we use Python 3.11)
• Check Railway build logs for specific error messages

Runtime Errors

If the app builds but doesn't start:

• Verify environment variables are set correctly
• Check Railway deployment logs
• Ensure the start command is correct: cd backend && uvicorn api:app --host 0.0.0.0 --port $PORT

📱 Update iOS App for Production

Step 1: Update API Configuration

In your iOS project, update the TradingAgentsService.swift:

// Replace localhost URL with your Railway URL
private let baseURL = "https://your-app.railway.app"

Step 2: Configure for App Store

1. Update app version in Xcode
2. Test with production API thoroughly
3. Ensure all network calls use HTTPS
4. Update app privacy settings if needed

🔒 Production Security Setup

Step 1: Configure CORS (Optional)

To restrict API access to your app only:

1. In Railway dashboard, add variable:

   CORS_ORIGINS=https://your-custom-domain.com
   

Step 2: Monitor Usage

1. Check Railway dashboard for usage metrics
2. Monitor API response times
3. Set up alerts for downtime

📊 Performance Optimization

Railway Configuration

Railway automatically handles:

• ✅ HTTPS/SSL certificates
• ✅ Auto-scaling based on usage
• ✅ Health checks and restarts
• ✅ CDN for faster global access

Expected Performance

• Startup time: ~30-60 seconds (cold start)
• Analysis time: 2-8 minutes per request
• Concurrent users: Railway free tier handles 10-20 concurrent users

🔧 Troubleshooting

Common Issues

1. Build failures:

   • Check requirements.txt is valid
   • Ensure Python version compatibility
   • Look for missing root-level configuration files

2. Runtime errors:

   • Verify all environment variables are set
   • Check Railway logs for detailed errors

3. API timeouts:

   • Railway has 100-second request timeout
   • Consider implementing streaming for long analyses

Monitoring Commands

# Check Railway logs
railway logs

# Check service status
railway status

# Restart service
railway redeploy

📈 Scaling for App Store Success

Free Tier Limits

• Execution time: 500 hours/month
• Memory: 512MB
• Storage: 1GB

When to Upgrade

• > 100 daily users: Consider Pro plan ($5/month)
• > 1000 daily users: Plan migration to VPS

Migration Path

When your app grows, migrate to:

1. Railway Pro (simple upgrade)
2. Docker + VPS (full control)
3. AWS/GCP (enterprise scale)

✅ Pre-App Store Checklist

• API deployed and accessible via HTTPS
• All endpoints return expected responses
• iOS app updated with production URL
• App tested with production API
• Error handling tested (network issues, API timeouts)
• App Store privacy policy updated
• Terms of service mention third-party APIs

🆘 Support

• Railway Documentation: docs.railway.app
• Railway Discord: Join for community support
• GitHub Issues: Report bugs in your repository

---

🎉 Congratulations! Your TradingAgents API is now ready for App Store submission with a production-grade backend hosted on Railway.