Skip to main content
Deploy your KAIU Natural Living platform to Railway with managed PostgreSQL and Redis instances for a complete, production-ready infrastructure.

​
Overview

Railway is an excellent choice for deploying KAIU Natural Living because it can host:
  • Your Node.js application (backend + frontend)
  • PostgreSQL database with pgvector extension
  • Redis instance for BullMQ queues
  • All in one platform with unified billing and management

​
Prerequisites

Before deploying to Railway, ensure you have:
  • A Railway account (sign up here)
  • Your GitHub repository
  • WhatsApp Cloud API credentials from Meta
  • Anthropic API key for Claude 3 Haiku

​
Deployment Steps

1

Create a New Project

  1. Log in to Railway Dashboard
  2. Click “New Project”
  3. Select “Deploy from GitHub repo”
  4. Choose your KAIU Natural Living repository
2

Add PostgreSQL Database

  1. In your Railway project, click “New”
  2. Select “Database” → “PostgreSQL”
  3. Railway will create a managed PostgreSQL instance
  4. Note the connection string for environment variables
Railway’s PostgreSQL includes the pgvector extension, which is required for the RAG functionality.
3

Add Redis Instance

  1. In your Railway project, click “New”
  2. Select “Database” → “Redis”
  3. Railway will create a managed Redis instance
  4. Note the connection details for environment variables
4

Configure Environment Variables

Set up environment variables for your application:
  1. Click on your application service
  2. Go to the “Variables” tab
  3. Add all required variables (see Environment Setup)
Railway auto-provides these database variables:
  • DATABASE_URL (from PostgreSQL service)
  • REDIS_URL (from Redis service)
You’ll need to add:
  • WHATSAPP_PHONE_NUMBER_ID
  • WHATSAPP_ACCESS_TOKEN
  • WHATSAPP_VERIFY_TOKEN
  • ANTHROPIC_API_KEY
  • And other required variables
Keep all API keys and tokens secure. Never commit them to your repository.
5

Configure Build Settings

Railway usually auto-detects the configuration, but verify:
  1. Build Command: npm run build
  2. Start Command: npm run api
  3. Install Command: npm install
You can customize these in the “Settings” tab under “Build & Deploy”.
6

Set Up Custom Domain (Optional)

  1. Go to “Settings” → “Networking”
  2. Click “Generate Domain” for a Railway subdomain
  3. Or add your custom domain
  4. Railway handles SSL certificates automatically
7

Deploy Application

Railway will automatically deploy when you push to your repository.To trigger a manual deployment:
  1. Go to “Deployments” tab
  2. Click “Deploy” on the latest commit
Monitor the build logs to ensure successful deployment.
8

Initialize Database

After the first deployment, initialize your database:
  1. Install Railway CLI:
npm install -g @railway/cli
  1. Login and link to your project:
railway login
railway link
  1. Run database migrations:
railway run npx prisma db push
  1. (Optional) Seed initial data:
railway run npm run seed
9

Enable pgvector Extension

Enable the required pgvector extension:
  1. Access your database through Railway CLI:
railway connect PostgreSQL
  1. Run this SQL command:
CREATE EXTENSION IF NOT EXISTS vector;
  1. Verify installation:
SELECT * FROM pg_extension WHERE extname = 'vector';
10

Verify Deployment

Test your deployment:
  1. Visit your Railway deployment URL
  2. Check the frontend loads correctly
  3. Test API endpoints
  4. Verify database connectivity
  5. Test Redis connection and BullMQ queues
  6. Verify WhatsApp webhook functionality
  7. Test AI orchestrator with sample conversations

​
Service Configuration

​
Application Service

  • Start Command: npm run api (runs node server.mjs)
  • Port: Railway automatically assigns PORT environment variable
  • Health Check: Configure at /api/health endpoint

​
PostgreSQL Service

  • Version: PostgreSQL 14+ (with pgvector)
  • Backup: Enable automatic backups in Railway settings
  • Connection Pooling: Enabled by default

​
Redis Service

  • Version: Redis 7+
  • Persistence: Enabled by default
  • Max Memory: Configure based on your plan

​
Continuous Deployment

Railway automatically deploys when you:
  • Push to your connected branch (usually main or master)
  • Create a new release
  • Manually trigger from the dashboard
You can configure deployment triggers in the service settings.

​
Monitoring and Logs

Railway provides built-in monitoring:
  1. Logs: Real-time application logs in the dashboard
  2. Metrics: CPU, memory, and network usage
  3. Database Metrics: Connection count, query performance
  4. Alerts: Configure webhooks for deployment events
Production Considerations
  • Scaling: Railway supports vertical scaling; upgrade your plan as traffic grows
  • Database Backups: Enable and test automatic backups regularly
  • Redis Persistence: Ensure Redis persistence is enabled for queue durability
  • Connection Limits: Monitor database connection counts, especially with BullMQ workers
  • Resource Limits: Watch CPU and memory usage; adjust instance sizes as needed
  • Rate Limiting: Implement rate limiting for WhatsApp webhooks and API endpoints
  • Monitoring: Set up external monitoring (e.g., Uptime Robot, Better Uptime)

​
Troubleshooting

​
Build Failures

  1. Check build logs in Railway dashboard
  2. Verify package.json scripts are correct
  3. Ensure Node.js version is v20+
  4. Check for missing dependencies

​
Database Connection Issues

  1. Verify DATABASE_URL is set correctly
  2. Check PostgreSQL service is running
  3. Ensure pgvector extension is installed
  4. Review connection pooling settings

​
Redis Connection Issues

  1. Verify Redis service is running
  2. Check REDIS_HOST and REDIS_PORT variables
  3. Test connection using Railway CLI
  4. Review Redis logs for errors

​
Application Crashes

  1. Review application logs in Railway dashboard
  2. Check for unhandled promise rejections
  3. Verify all environment variables are set
  4. Monitor memory usage (adjust if needed)

​
Cost Optimization

  • Hobby Plan: $5/month for basic usage
  • Resource Optimization: Monitor and right-size your services
  • Database: Use connection pooling to reduce overhead
  • Redis: Configure appropriate max memory settings
  • Scheduled Tasks: Use BullMQ’s scheduled jobs instead of always-running workers

​
Next Steps

Environment Setup

Complete guide to environment variables

Vercel Deployment

Alternative deployment option

Build docs developers (and LLMs) love

Get started for freeTalk to us