Railway.app es una plataforma moderna de despliegue que ofrece una alternativa más simple a Fly.io, con precios transparentes y una interfaz intuitiva basada en web.

Comparación: Railway vs Fly.io

Característica	Railway	Fly.io
Pricing	$5/mes por servicio	$0 gratis, pago por uso
Base de datos	Railway Postgres incluida	Requiere Neon externo
Interfaz	Dashboard web intuitivo	CLI principalmente
Despliegue	Git push automático	wasp deploy fly manual
Custom domains	Incluido	Incluido
SSL	Automático	Automático
Rollbacks	Un clic	CLI
Logs	Dashboard en tiempo real	CLI

Prerequisitos

Antes de comenzar, asegúrate de tener:

1. ✅ Cuenta en Railway.app (acepta GitHub OAuth)
2. ✅ Cuenta en Neon para PostgreSQL (gratuita)
3. ✅ Wasp CLI instalado: curl -sSL https://get.wasp-lang.dev/installer.sh | sh
4. ✅ Cuenta en Stripe configurada
5. ✅ Cuenta en SendGrid con API key
6. ✅ (Opcional) AWS S3 + CloudFront para videos

Fase 1: Configurar Base de Datos (Neon)

Railway puede proporcionar PostgreSQL, pero recomendamos Neon para mejor rendimiento y separación de servicios.

1.1. Crear Proyecto en Neon

1. Ir a console.neon.tech
2. Click en New Project
3. Configurar:
   • Project name: talentbricksai-prod
   • Postgres version: 16 (más reciente)
   • Region: US East (Ohio) o el más cercano a tus usuarios
4. Click Create Project

1.2. Obtener Connection String

1. En el dashboard del proyecto, click en Connection Details
2. Copiar el Connection string completo:

   postgresql://user:pass@ep-xxx-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

3. Guardar este valor - lo necesitarás para DATABASE_URL

1.3. Configurar Pooling (Recomendado)

Para mejor rendimiento bajo carga:

1. En Neon dashboard, ir a Connection pooling
2. Habilitar pooling
3. Copiar la Pooled connection string:

   postgresql://user:pass@ep-xxx-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require

Fase 2: Crear Proyecto en Railway

2.1. Nuevo Proyecto desde GitHub

1. Ir a railway.app/new
2. Click en Deploy from GitHub repo
3. Autorizar Railway a acceder a tus repositorios
4. Seleccionar tu repositorio: tu-usuario/talentbricksai
5. Railway detectará automáticamente el proyecto Wasp

2.2. Configurar Build Settings

Railway debería detectar automáticamente el proyecto, pero verifica:

1. En el proyecto, click en Settings
2. Sección Build:
   • Build Command: wasp build
   • Start Command: cd .wasp/build && npm start
   • Root Directory: / (raíz del proyecto)

2.3. Configurar Environment

1. En Settings → Environment
2. Seleccionar Production

Fase 3: Configurar Variables de Entorno

3.1. Variables Obligatorias

En Railway, ir a tu proyecto → Variables y agregar:

Base de Datos

DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

Autenticación

# Generar con: openssl rand -base64 32
JWT_SECRET=tu_secreto_generado_aqui

# URL de tu app (Railway te da un dominio temporal)
CLIENT_URL=https://talentbricksai-production.up.railway.app

Stripe (Producción)

# Obtener de: https://dashboard.stripe.com/apikeys
STRIPE_API_KEY=sk_live_...

# Obtener de: https://dashboard.stripe.com/webhooks
STRIPE_WEBHOOK_SECRET=whsec_...

# IDs de productos en modo LIVE
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID=price_live_mensual
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID=price_live_anual

Email (SendGrid)

# Obtener de: https://app.sendgrid.com/settings/api_keys
SENDGRID_API_KEY=SG.xxxxxxxxxxxxx

# Opcional - personalización
SENDGRID_FIELD_FROM_NAME=TalentBricks
SENDGRID_FIELD_FROM_EMAIL=noreply@talentbricks.ai

Administradores

# Emails separados por coma
ADMIN_EMAILS=admin@tuempresa.com,juan@tuempresa.com

3.2. Variables Condicionales (AWS S3 + CloudFront)

Solo si usas videos en S3 (en producción, recomendado):

# IAM credentials (crear en: https://console.aws.amazon.com/iam)
AWS_S3_IAM_ACCESS_KEY=AKIA...
AWS_S3_IAM_SECRET_KEY=wJalr...

# S3 bucket
AWS_S3_FILES_BUCKET=talentbricks-videos
AWS_S3_REGION=us-east-1

# CloudFront (URLs firmadas)
CLOUDFRONT_DOMAIN=d1234567890abc.cloudfront.net
CLOUDFRONT_KEY_PAIR_ID=K2JCJMDEHXQW5F
CLOUDFRONT_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKC....\n-----END RSA PRIVATE KEY-----

⚠️ Nota sobre CLOUDFRONT_PRIVATE_KEY: Railway acepta el valor en una sola línea con \n para los saltos de línea.

3.3. Variables Opcionales (OAuth Social)

Google OAuth

# Obtener de: https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

GitHub OAuth

# Obtener de: https://github.com/settings/developers
GITHUB_CLIENT_ID=Iv1.1234567890abcdef
GITHUB_CLIENT_SECRET=abcdef1234567890...

3.4. Variables Opcionales (Analytics)

# Plausible Analytics
PLAUSIBLE_API_KEY=tu_api_key

# Google Analytics 4
REACT_APP_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

# OpenAI (funciones AI)
OPENAI_API_KEY=sk-...

3.5. Usar Railway CLI (Alternativa)

Si prefieres configurar por línea de comandos:

# Instalar Railway CLI
npm i -g @railway/cli

# Login
railway login

# Vincular proyecto
railway link

# Configurar variables
railway variables set DATABASE_URL="postgresql://..."
railway variables set JWT_SECRET="tu_secreto"
railway variables set STRIPE_API_KEY="sk_live_..."
# ... etc

Fase 4: Desplegar

4.1. Primer Despliegue

Railway despliega automáticamente cuando detecta cambios en tu rama principal:

1. Hacer push a GitHub:

   git push origin main

2. Railway iniciará el build automáticamente

3. Monitorear el progreso:

   • En Railway dashboard → Deployments
   • Ver logs en tiempo real

4.2. Deploy Manual (CLI)

# Desplegar rama actual
railway up

# Ver logs en tiempo real
railway logs

# Ver servicio desplegado
railway open

4.3. Verificar Deployment

1. Abrir la URL temporal de Railway (ej: https://talentbricksai-production.up.railway.app)
2. Verificar que la app carga sin errores
3. Revisar logs:

   railway logs --tail

Fase 5: Ejecutar Migraciones

Después del primer despliegue, ejecutar migraciones de Prisma:

# Via Railway CLI
railway run npx prisma migrate deploy

O configurar un Deploy Hook en Railway:

1. Settings → Deploy
2. Post-deploy command: npx prisma migrate deploy

Fase 6: Configurar Webhooks de Stripe

Railway proporciona una URL permanente para tu app. Úsala para configurar webhooks:

6.1. Crear Webhook en Stripe

1. Ir a dashboard.stripe.com/webhooks

2. Click Add endpoint

3. Endpoint URL:

   https://talentbricksai-production.up.railway.app/stripe-webhook

4. Events to send: Seleccionar todos los eventos relacionados con:

   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed

5. Click Add endpoint

6. Copiar el Signing secret (empieza con whsec_)

7. Actualizar variable en Railway:

   railway variables set STRIPE_WEBHOOK_SECRET="whsec_..."

6.2. Verificar Webhooks

1. Hacer una compra de prueba en tu app
2. En Stripe Dashboard → Webhooks → tu endpoint
3. Ver Recent deliveries - debe aparecer 200 OK

Fase 7: Configurar Dominio Custom

7.1. Agregar Dominio en Railway

1. En tu proyecto Railway, ir a Settings → Domains
2. Click Add Custom Domain
3. Ingresar tu dominio: talentbricks.ai
4. Railway te mostrará los registros DNS necesarios

7.2. Configurar DNS

En tu proveedor de DNS (Cloudflare, Namecheap, etc.):

Opción A: CNAME (recomendado para www)

Type:  CNAME
Name:  www
Value: talentbricksai-production.up.railway.app
TTL:   Auto

Opción B: A Record (para dominio raíz)

Type:  A
Name:  @
Value: <IP proporcionada por Railway>
TTL:   Auto

7.3. SSL Automático

Railway configura SSL automáticamente vía Let’s Encrypt. Espera 5-10 minutos después de configurar DNS.

7.4. Actualizar Variables de Entorno

# Actualizar CLIENT_URL con tu dominio
railway variables set CLIENT_URL="https://talentbricks.ai"

# Actualizar callback URLs en OAuth providers
# Google: https://console.cloud.google.com/apis/credentials
#   - Authorized redirect URIs: https://talentbricks.ai/auth/google/callback
# GitHub: https://github.com/settings/developers
#   - Authorization callback URL: https://talentbricks.ai/auth/github/callback

Fase 8: Configurar Backups

8.1. Database Backups (Neon)

Neon hace backups automáticos:

• Point-in-time restore: últimos 7 días (plan gratuito)
• Restore desde: Console → Project → Restore

8.2. Application Backups (Git)

Railway despliega desde Git, así que tu código siempre está respaldado:

• Cada deployment está vinculado a un commit específico
• Rollback a cualquier deployment anterior en 1 click

Troubleshooting

Error: “Cannot find module ‘wasp’”

Railway no reconoció el proyecto como Wasp.

Solución:

# Settings → Build Command:
wasp build

# Settings → Start Command:
cd .wasp/build && npm start

Error: “Database connection failed”

Solución:

1. Verificar DATABASE_URL en Railway variables
2. Verificar que Neon database está activo
3. Probar conexión:

   railway run npx prisma db pull

Error: “Stripe webhook signature failed”

Solución:

1. Verificar STRIPE_WEBHOOK_SECRET en Railway
2. Verificar que el endpoint en Stripe es correcto:

   https://tu-dominio.up.railway.app/stripe-webhook

3. Regenerar webhook secret en Stripe si es necesario

Error: “S3 Access Denied”

Solución:

1. Verificar credenciales AWS en Railway variables
2. Verificar permisos IAM:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:PutObject", "s3:GetObject"],
         "Resource": "arn:aws:s3:::tu-bucket/*"
       }
     ]
   }

Videos muestran error 403

Solución:

1. Verificar CLOUDFRONT_DOMAIN apunta a tu distribución
2. Verificar CLOUDFRONT_PRIVATE_KEY está en formato correcto (una línea con \n)
3. Verificar que CloudFront está configurado con “Require signed URLs”

Build timeout

Railway tiene límite de 30 min para builds. Si Wasp tarda mucho:

Solución:

# Limpiar caché de Railway
railway run rm -rf .wasp/build

O habilitar Build Cache en Settings.

Ver logs en tiempo real

# Railway CLI
railway logs --tail

# O en dashboard
Project → Deployments → Latest → Logs

Rollback a versión anterior

1. En Railway dashboard → Deployments
2. Encontrar deployment funcional anterior
3. Click ••• → Redeploy

Costos Estimados

Railway (Hobby Plan)

• Servidor: $5/mes
• Egress: $0.10/GB después de 100GB
• Total mínimo: ~$5-10/mes

Neon (Free Tier)

• Database: $0/mes (hasta 0.5GB)
• Compute: $0/mes (hasta 191.9 horas/mes)
• Upgrade a Pro: $19/mes para más recursos

Stripe

• 2.9% + $0.30 por transacción exitosa

Total estimado: $5-30/mes

(dependiendo de tráfico y features habilitadas)

Comparación de Costos

Servicio	Costo Mensual Estimado
Railway + Neon	$5-10
Fly.io + Neon	$0-5 (depende de uso)
Vercel + Neon	$0-20
AWS ECS + RDS	$50-200

Recomendación: Railway es excelente para equipos pequeños que valoran simplicidad. Fly.io es mejor si quieres minimizar costos y no te importa usar CLI.

Próximos Pasos

✅ Despliegue completado en Railway

Ahora:

1. ✅ Revisar Checklist de Producción
2. ✅ Configurar Monitoreo y Logs
3. ✅ Planificar Estrategia de Backups
4. ✅ Configurar CI/CD con GitHub Actions

Recursos Adicionales

• Documentación oficial de Railway
• Railway CLI Reference
• Neon Documentation
• Guía de Despliegue en Fly.io (alternativa)
• Variables de Entorno (referencia completa)