Deploy to Railway

Deploy Consuelo to Railway with managed PostgreSQL and Redis.

Railway is the recommended platform for Consuelo deployments due to built-in database and Redis support.

Why Railway?

Feature	Benefit
Managed PostgreSQL	No database server management
Managed Redis	Built-in caching and queues
Easy scaling	Add resources with one click
GitHub integration	Auto-deploy on push
Free tier	For development and testing

Prerequisites

• Railway account (railway.app)
• GitHub repository with your Consuelo project
• Twilio credentials
• AI provider API key (Groq or OpenAI)

Create Railway Project

Via CLI

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Create project
railway init

Via Dashboard

1. Go to railway.app/dashboard
2. Click New Project
3. Select Deploy from GitHub repo
4. Choose your repository

Add Services

Railway needs three services:

PostgreSQL

railway add --service postgres

Or via dashboard:

1. Click Add Service
2. Select Database
3. Choose PostgreSQL

Redis

railway add --service redis

Or via dashboard:

1. Click Add Service
2. Select Database
3. Choose Redis

Application

Your main application is added automatically when you connect the repo.

Configure Environment Variables

Required Variables

Add these in the Railway dashboard (Variables tab):

TWILIO_ACCOUNT_SID=ACxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=[phone]
GROQ_API_KEY=gsk_xxxxxx

Or via CLI:

railway variables set TWILIO_ACCOUNT_SID=ACxxxxxx
railway variables set TWILIO_AUTH_TOKEN=your_auth_token
railway variables set TWILIO_PHONE_NUMBER=[phone]
railway variables set GROQ_API_KEY=gsk_xxxxxx

Database URLs

Railway automatically provides:

• DATABASE_URL — PostgreSQL connection (auto-set)
• REDIS_URL — Redis connection (auto-set)

You don’t need to configure these manually.

Deploy

First Deploy

railway up

Or use the Consuelo CLI:

consuelo deploy --platform railway

Monitor Deployment

Watch the build logs:

railway logs

Or in the dashboard: Deployments → Click on deployment → Logs

Worker Service

Consuelo uses a background worker for queues and jobs.

Add Worker Service

railway add --service worker

Configure Worker

Set the start command in Railway dashboard:

1. Go to Worker service → Settings
2. Set Start Command to:
   node dist/queue-worker/queue-worker
   

Or via CLI:

railway variables set RAILWAY_DOCKERFILE_PATH=packages/twenty-docker/twenty/Dockerfile --service worker

The worker uses the same Dockerfile as the main service but with a different start command.

Custom Domain

Add Domain

1. Go to Settings → Domains
2. Click Custom Domain
3. Enter your domain (e.g., consuelo.yourcompany.com)
4. Add the displayed DNS records to your domain

Update CORS

Add your domain to allowed origins:

railway variables set CORS_ORIGIN=https://consuelo.yourcompany.com

Environment-Specific Deployments

Staging

Create a separate environment:

railway environment create staging
railway up --environment staging

Production

railway up --environment production

Troubleshooting

Build Fails

Check build logs:

railway logs --build

Common issues:

• Missing package.json — Ensure repo root has package.json
• Wrong Node version — Add engines to package.json
• Dependency errors — Run yarn install locally first

Database Connection Fails

Verify DATABASE_URL is set:

railway variables

Should show DATABASE_URL=postgresql://...

Worker Not Starting

Check worker logs:

railway logs --service worker

Ensure start command is correct and the build completed.

Redis Connection Fails

Verify Redis is running:

railway status

Should show Redis service as ACTIVE.

Monitoring

View Logs

# All services
railway logs

# Specific service
railway logs --service api
railway logs --service worker

Metrics

In the Railway dashboard:

1. Go to your service
2. Click Metrics tab
3. View CPU, memory, and request metrics

Costs

Railway pricing (as of 2024):

Tier	Cost	Usage
Free	$0	500 hours/month, 1GB disk
Hobby	$5/month	More resources
Pro	$20/month	Production workloads

Consuelo typically uses ~1GB memory and ~1GB disk for small deployments. Monitor usage in the dashboard.

Next Steps

• Configuration — Set up environment variables
• Deployment — Other deployment options
• CLI FAQ — Common deployment questions