​
Deploy to Railway

Deploy WhatsApp Team Inbox to Railway in minutes with built-in PostgreSQL and automatic HTTPS.

​
TL;DR - Quick Deploy

1

Fork & Connect

Fork the repo → Railway → New Project → GitHub → Select repo
2

Add Services

Add PostgreSQL database, then deploy backend (/backend) and frontend (/web)
3

Set Variables

Add WhatsApp credentials, JWT secrets, and database URL to backend
4

Deploy

Railway auto-deploys with HTTPS URLs. Done! ✅
Total time: ~10 minutes | Cost: $5-20/month

​
Why Railway?

One-Click Deploy

Deploy from GitHub with zero configuration

Included Database

PostgreSQL database included in deployment

Auto HTTPS

Automatic SSL certificates and domains

Affordable

Starts at $5/month with free trial

​
Prerequisites

GitHub account
Railway account (sign up at railway.app)
WhatsApp Business API credentials
GitHub repository with your code

​
Quick Deploy

​
Option 1: Deploy Button (Fastest)

Click the button below to deploy instantly: Deploy on Railway This will:
  • Create a new project
  • Set up PostgreSQL database
  • Deploy backend and frontend
  • Generate automatic HTTPS URLs

​
Option 2: Manual Deployment

1

Fork the Repository

  1. Go to the WhatsApp Team Inbox repository
  2. Click Fork in the top right
  3. Create a fork in your account
2

Create Railway Project

  1. Log in to Railway
  2. Click New Project
  3. Select Deploy from GitHub repo
  4. Authorize Railway to access your GitHub
  5. Select your forked repository
3

Add PostgreSQL Database

  1. Click + New in your project
  2. Select Database → PostgreSQL
  3. Railway will provision a database automatically
4

Configure Backend Service

  1. Click + New → GitHub Repo
  2. Select your repository
  3. Set Root Directory: backend
  4. Railway will detect Dockerfile automatically
5

Configure Frontend Service

  1. Click + New → GitHub Repo
  2. Select your repository again
  3. Set Root Directory: web
  4. Railway will detect Next.js automatically

​
Environment Variables

After deployment, configure environment variables for each service.

​
Backend Environment Variables

In Railway dashboard, go to Backend service → Variables tab: 
# Railway automatically provides:
DATABASE_URL=${{Postgres.DATABASE_URL}}

WHATSAPP_API_URL=https://graph.facebook.com/v21.0
WHATSAPP_ACCESS_TOKEN=your_permanent_access_token
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_BUSINESS_ACCOUNT_ID=123456789012345
WHATSAPP_WEBHOOK_VERIFY_TOKEN=generate_random_token
Get these from Meta Business Suite
JWT_SECRET=generate_with_openssl_rand_hex_32
JWT_REFRESH_SECRET=generate_different_secret
JWT_EXPIRES_IN=7d
JWT_REFRESH_EXPIRES_IN=30d
Generate secrets:
openssl rand -hex 32

ADMIN_EMAIL=admin@yourcompany.com
ADMIN_PASSWORD=strong_password_here
ADMIN_FIRST_NAME=System
ADMIN_LAST_NAME=Administrator

# Use Railway's automatic URLs
CORS_ORIGIN=${{Frontend.RAILWAY_PUBLIC_DOMAIN}}
NODE_ENV=production
PORT=4000
WS_PORT=4001

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=your_sendgrid_api_key
SMTP_FROM=noreply@yourdomain.com

# Generate with: npx web-push generate-vapid-keys
VAPID_PUBLIC_KEY=your_public_key
VAPID_PRIVATE_KEY=your_private_key
VAPID_SUBJECT=mailto:admin@yourdomain.com

​
Frontend Environment Variables

In Railway dashboard, go to Frontend service → Variables tab: 
# Backend API URL (use Railway's service reference)
NEXT_PUBLIC_API_BASE_URL=https://${{Backend.RAILWAY_PUBLIC_DOMAIN}}
NEXT_PUBLIC_WS_URL=wss://${{Backend.RAILWAY_PUBLIC_DOMAIN}}
Railway automatically replaces ${{ServiceName.VARIABLE}} with actual values

​
Custom Domain (Optional)

​
Add Custom Domain

1

Access Settings

Click on your service → Settings tab
2

Add Domain

Under Domains, click + Generate Domain for a Railway subdomain, or + Custom Domain for your own domain
3

Configure DNS

For custom domains, add DNS records:A Record:
Type: CNAME
Name: app (or @ for root domain)
Value: <your-railway-domain>.up.railway.app
4

Update Environment Variables

Update CORS and frontend URLs to use your custom domain:
# Backend
CORS_ORIGIN=https://your-domain.com

# Frontend
NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com

​
Database Management

​
Access Database

1

Get Database URL

Click on PostgreSQL service → Connect tab → Copy DATABASE_URL
2

Connect via CLI

# Install PostgreSQL client
brew install postgresql  # macOS
sudo apt install postgresql-client  # Ubuntu

# Connect to database
psql "your-database-url-here"
3

Run Migrations

# In backend service terminal
railway run npm run migrate:deploy

​
Database Backups

Railway automatically creates daily backups. To restore:
  1. Go to PostgreSQL service → Backups tab
  2. Select a backup
  3. Click Restore

​
Webhook Configuration

After deployment, configure WhatsApp webhook:
1

Get Backend URL

Copy your backend service URL from Railway dashboard
2

Configure in Meta Business Suite

Set webhook URL to:
https://your-backend-url.railway.app/api/webhook
Use WHATSAPP_WEBHOOK_VERIFY_TOKEN from your environment variables
3

Test Webhook

Send a test message to your WhatsApp number and check backend logs:
# In Railway dashboard
Backend service → Logs tab

​
Monitoring & Logs

​
View Logs

1

Access Service Logs

Click on any service → Deployments tab → Click latest deployment
2

Real-time Logs

Logs auto-refresh in real-time. Filter by:
  • Error level
  • Timestamp
  • Search terms
3

Download Logs

Click Download to save logs for analysis

​
Metrics & Usage

Railway provides built-in metrics:
  • CPU Usage - Monitor backend processing
  • Memory - Track memory consumption
  • Network - Monitor incoming/outgoing traffic
  • Database Size - Track PostgreSQL storage
Access in: Service → Metrics tab

​
Scaling

​
Vertical Scaling

Railway automatically scales resources based on usage:

Starter Plan

  • $5/month
  • 512MB RAM
  • Shared CPU
  • 1GB database

Pro Plan

  • $20/month
  • 8GB RAM
  • Dedicated CPU
  • 10GB database

​
Horizontal Scaling

For high traffic:
  1. Go to service → Settings
  2. Enable High Availability
  3. Set number of replicas
  4. Railway will load balance automatically

​
Deployment Triggers

​
Auto-Deploy on Push

Railway automatically deploys when you push to your GitHub repository: 
git add .
git commit -m "Update feature"
git push origin main
# Railway detects push and deploys automatically

​
Manual Deployment

Trigger manual deployment:
  1. Go to service → Deployments
  2. Click Deploy
  3. Select branch to deploy

​
Deploy Specific Branch

  1. Service → Settings
  2. Under Source, change Deploy Branch
  3. Select branch (main, develop, staging, etc.)

​
Cost Optimization

​
Minimize Costs

Set resource limits to prevent unexpected costs:Service → Settings → Resources
  • CPU limit: 1 vCPU
  • Memory limit: 512MB
For development environments:Service → Settings → Enable Sleep on IdleServices sleep after 1 hour of inactivity
  • Regular vacuum operations
  • Remove unused indexes
  • Archive old conversations
  • Monitor storage growth
Free $5 credit monthly for hobby projectsUpgrade to Developer plan only when needed

​
Troubleshooting

Common causes:
  • Missing dependencies in package.json
  • Build errors in code
  • Node version mismatch
Solutions:
  1. Check build logs in Deployments tab
  2. Verify package.json scripts
  3. Set Node version in Settings → Environment
Causes:
  • DATABASE_URL not set correctly
  • Database service not running
Solutions:
  1. Verify DATABASE_URL in Variables tab
  2. Check PostgreSQL service status
  3. Restart backend service
Causes:
  • NEXT_PUBLIC_API_BASE_URL incorrect
  • CORS not configured
Solutions:
  1. Verify NEXT_PUBLIC_API_BASE_URL uses HTTPS
  2. Check CORS_ORIGIN in backend includes frontend URL
  3. Review backend logs for CORS errors
Causes:
  • Webhook URL not accessible
  • Verify token mismatch
Solutions:
  1. Test webhook URL: curl https://your-backend/api/webhook
  2. Verify WHATSAPP_WEBHOOK_VERIFY_TOKEN matches Meta
  3. Check backend logs for incoming webhook requests

​
Production Checklist

Before going live:
All environment variables configured
Database migrations applied
Admin user created
WhatsApp webhook configured and tested
Custom domain configured (optional)
HTTPS enabled
Email service configured
Push notifications set up
Backups enabled
Monitoring alerts configured

​
Railway CLI (Advanced)

For advanced users, use Railway CLI:

​
Install CLI

# macOS/Linux
curl -fsSL https://railway.app/install.sh | sh

# Windows
powershell -c "irm railway.app/install.ps1 | iex"

​
Deploy from CLI

# Login
railway login

# Link project
railway link

# Deploy
railway up

# View logs
railway logs

# Run migrations
railway run npm run migrate:deploy

​
Migration from Other Platforms

​
From Heroku

1

Export Heroku Config

heroku config -a your-app-name > .env
2

Import to Railway

Copy environment variables from .env to Railway Variables tab
3

Migrate Database

# Dump Heroku database
heroku pg:backups:capture -a your-app-name
heroku pg:backups:download -a your-app-name

# Restore to Railway
railway run psql $DATABASE_URL < latest.dump

​
From DigitalOcean

1

Export Database

pg_dump your_db > backup.sql
2

Import to Railway

railway run psql $DATABASE_URL < backup.sql
3

Update Environment Variables

Copy all environment variables to Railway

​
Next Steps

WhatsApp Setup

Configure WhatsApp Business API

Environment Variables

Complete environment variable reference

Going Live

Production deployment checklist

Monitoring

Set up monitoring and alerts

​
Resources