Railway Deployment Guide

Overview

Complete guide for deploying Dr. Sophia AI to Railway with environment-aware builds, proper dist/ compilation, and backend auto-deployment. This skill covers the critical differences between frontend and backend deployment workflows.

Keywords: Railway deployment, build process, environment configuration, dist folder, production deployment, frontend build, backend deploy, npm run build

When to Use This Skill

• Deploying frontend to Railway
• Deploying backend to Railway
• Building dist/ folder for production
• Debugging deployment failures
• Setting up environment variables
• Troubleshooting Railway issues

Critical Deployment Fact

🚨 FRONTEND: Railway deploys the pre-built dist/ folder, NOT source files!

• Changing /frontend/src/*.jsx alone = ❌ NO DEPLOYMENT
• Must run npm run build + commit dist/ = ✅ DEPLOYMENT

✅ BACKEND: Railway deploys directly from source (NO build step needed)

Frontend Deployment Process

Step 1: Make Changes

# Edit frontend source files
nano frontend/src/ModernApp.jsx

Step 2: Build (MANDATORY!)

cd frontend
npm run build  # Auto-detects branch, builds for correct environment

What This Does:

• Detects current git branch (dev/main/prototype)
• Sets correct backend URL automatically
• Creates optimized dist/ folder (~55KB)
• Includes password protection
• Injects API keys from .env

Step 3: Verify Build

ls -lh dist/assets/*.css  # Must be ~60KB (not 9KB!)
ls -lh dist/assets/*.js   # Must be ~450KB

Step 4: Commit & Deploy

git add -A                  # Includes BOTH src/ and dist/
git commit -m "feat: your changes"
git push origin dev         # Railway auto-deploys from dist/

Backend Deployment Process

Step 1: Make Changes

# Edit backend files
nano backend/backend-proxy-enhanced-current.js

Step 2: Commit & Deploy (That's It!)

git add backend/
git commit -m "fix: backend improvement"
git push origin dev         # Railway auto-deploys from source

No build step required - Backend runs directly from source.

Environment Detection

Build script automatically detects branch and configures backend URL:

Override if needed:

BUILD_ENV=production npm run build  # Force specific environment

Deployment Checklist

Frontend Deployment

• Run npm run build from frontend/ directory
• Verify CSS is ~60KB (not 9KB = Tailwind not working)
• Verify JS is ~450KB
• git add -A (include dist/ folder!)
• Commit with descriptive message
• Push to Railway (auto-deploys)
• Wait 2-3 minutes for build/deploy
• Verify deployment at Railway URL

Backend Deployment

• Edit backend files
• git add backend/
• Commit changes
• Push to Railway (auto-deploys)
• Railway rebuilds automatically
• No build step needed

Common Deployment Failures

Detailed Documentation

For environment configuration, build troubleshooting, and Railway setup, see:

• Environment Config: references/environment-config.md
• Build Troubleshooting: references/build-troubleshooting.md
• Railway Configuration: references/railway-config.md

Verification Script

Run post-deployment verification:

.claude/skills/deployment-guide/scripts/verify-deployment.sh dev

Expected output:

✅ Backend health check passed
✅ Version matches: v13.2.7
✅ API keys configured

Quick Reference

Frontend Build Commands

cd frontend
npm run build          # Environment-aware (recommended)
BUILD_ENV=dev npm run build     # Force dev environment
BUILD_ENV=production npm run build  # Force production

Backend Version Check

# Check deployed version
curl https://backend-dev-d231.up.railway.app/health | jq .version

# Should match local version
grep "BACKEND_VERSION" backend/backend-proxy-enhanced-current.js

Railway Dashboard

• Dev Frontend: https://railway.app/project/frontend-dev-8670
• Dev Backend: https://railway.app/project/backend-dev-d231
• Prod Frontend: https://railway.app/project/botaniqal-medtech-frontend
• Prod Backend: https://railway.app/project/backend-production-5c38

Build System: Environment-aware (auto-detects branch) Deployment: Git push triggers Railway auto-deploy Last Updated: September 21, 2025