railway r2r step uy step

Deploy R2R on Railway - Step-by-Step Guide

This guide will help you deploy R2R on Railway with proper configuration.

Prerequisites

• Railway account (free tier works)
• OpenAI API key (for embeddings and LLM)

Step 1: Create PostgreSQL Database

1. Go to railway.app and create a New Project
2. Click ”+ New” → “Database” → “PostgreSQL”
3. Wait for it to deploy (takes ~30 seconds)
4. Click on the PostgreSQL service
5. Go to “Variables” tab and note these values:
   • PGHOST
   • PGPORT
   • PGDATABASE
   • PGUSER
   • PGPASSWORD

Install pgvector Extension

1. Still in PostgreSQL service, click “Connect”
2. Copy the connection string
3. Use a PostgreSQL client (like psql or TablePlus) to connect:

# Using psql (install via: brew install postgresql)
psql "postgresql://postgres:PASSWORD@HOST:PORT/railway"

# Run this command in psql:
CREATE EXTENSION IF NOT EXISTS vector;

# Verify it worked:
\dx vector

# Exit:
\q

OR use Railway’s built-in query computer:

1. In PostgreSQL service, go to “Query” tab
2. Run: CREATE EXTENSION IF NOT EXISTS vector;

Step 2: Deploy R2R Service

Option A: Using Docker Image (Recommended)

1. In your Railway project, click ”+ New” → “Empty Service”
2. Name it r2r
3. Click on the service → “Settings”
4. Under “Source”, select “Docker Image”
5. Enter: ragtoriches/r2r:latest
6. Click “Deploy”

Option B: Using GitHub Repository

1. Fork https://github.com/SciPhi-AI/R2R
2. In Railway, click ”+ New” → “GitHub Repo”
3. Connect your fork
4. Railway will auto-detect and deploy

Step 3: Configure Environment Variables

Click on your R2R service → “Variables” tab and add these:

Required Variables:

# PostgreSQL Connection (use values from Step 1)
POSTGRES_HOST=${{Postgres.PGHOST}}
POSTGRES_PORT=${{Postgres.PGPORT}}
POSTGRES_USER=${{Postgres.PGUSER}}
POSTGRES_PASSWORD=${{Postgres.PGPASSWORD}}
POSTGRES_DBNAME=${{Postgres.PGDATABASE}}

# Database URL (alternative format)
DATABASE_URL=postgresql://${{Postgres.PGUSER}}:${{Postgres.PGPASSWORD}}@${{Postgres.PGHOST}}:${{Postgres.PGPORT}}/${{Postgres.PGDATABASE}}

# R2R Configuration
R2R_PROJECT_NAME=supen
R2R_HOST=0.0.0.0
R2R_PORT=7272

# OpenAI API Key (REQUIRED for embeddings)
OPENAI_API_KEY=sk-your-openai-key-here

# Optional: Anthropic for better LLM
ANTHROPIC_API_KEY=your-anthropic-key

Railway-Specific Syntax:

Railway uses ${{ServiceName.VARIABLE}} to reference other services’ variables. This auto-wires your database connection!

Step 4: Expose R2R to Public Internet

1. In R2R service, go to “Settings”
2. Scroll to “Networking”
3. Click “Generate Domain”
4. Railway will give you a URL like: r2r-production.up.railway.app
5. Copy this URL - you’ll need it for Supen

Step 5: Verify Deployment

Check Logs:

1. Click on R2R service → “Deployments”
2. Click the latest deployment
3. Check logs for errors

Good signs:

Starting R2R server...
Uvicorn running on 0.0.0.0:7272
Database connection successful

Bad signs:

Connection refused
Missing environment variable
Failed to connect to database

Test Health Endpoint:

# Replace with your Railway URL
curl https://r2r-production.up.railway.app/v3/health

Should return:

{
  "status": "ok",
  "version": "3.x.x"
}

Step 6: Connect Supen to Railway R2R

In Railway - Supen Service:

Add these environment variables to your Supen service:

R2R_API_URL=https://r2r-production.up.railway.app
R2R_API_KEY=  # Leave empty unless you set up auth

Locally (for development):

Update app/.env.local:

R2R_API_URL=https://r2r-production.up.railway.app
R2R_API_KEY=

Step 7: Test the Integration

Test from your local machine:

# Start Supen
pnpm dev

# Test health endpoint
curl http://localhost:3333/api/knowledge/health

# Should return:
# {
#   "available": true,
#   "provider": "R2R",
#   "baseUrl": "https://r2r-production.up.railway.app"
# }

Upload a test document:

curl -X POST http://localhost:3333/api/knowledge/documents \
  -F "[email protected]" \
  -F "useHiResMode=false"

Troubleshooting

R2R crashes immediately:

Check logs for:

1. Missing OPENAI_API_KEY → Add it in Variables
2. Cannot connect to database → Verify PostgreSQL is running
3. vector extension not found → Install pgvector (Step 1)

Solution:

# Make sure these are set:
POSTGRES_HOST=${{Postgres.PGHOST}}
OPENAI_API_KEY=sk-...

R2R starts but crashes after 30s:

Railway’s health check might be failing.

1. Go to R2R service → “Settings”
2. Scroll to “Health Check”
3. Set:
   • Path: /v3/health
   • Timeout: 300 seconds (5 min)
   • Interval: 60 seconds

”Connection refused” from Supen:

Check:

1. R2R service has a public domain generated
2. R2R is actually running (check Deployments tab)
3. R2R_API_URL includes https://

Documents upload but queries fail:

OpenAI API key issue:

# Make sure this is set in R2R service:
OPENAI_API_KEY=sk-...

# Restart R2R after adding it

“Database does not exist” error:

PostgreSQL not initialized:

# Connect to PostgreSQL and run:
CREATE DATABASE railway;
CREATE EXTENSION IF NOT EXISTS vector;

Cost Estimation

Railway Hobby Plan ($5/month):

• PostgreSQL: ~$5/month
• R2R Service: ~$5-10/month (depends on usage)
• Total: ~$10-15/month

Free Tier:

• $5 credit/month (enough for testing)
• Limited to 500 hours/month total

Configuration Tips

Use Lighter Models (Save OpenAI Costs):

# In R2R service variables, add:
R2R_EMBEDDING_MODEL=text-embedding-3-small  # Cheaper than ada-002
R2R_COMPLETION_MODEL=gpt-4o-mini           # Cheaper than gpt-4

Enable Debug Logging:

R2R_LOG_LEVEL=DEBUG

Increase Memory (if crashes):

1. R2R service → “Settings”
2. Scroll to “Resources”
3. Upgrade to higher memory plan if needed

Alternative: Local Development Only

If Railway is too complex, use local R2R for now:

# In your supen directory:
docker compose up r2r r2r-postgres -d

# Use in .env.local:
R2R_API_URL=http://localhost:7272

This works great for development, deploy to Railway later when ready for production.

Next Steps

Once R2R is running:

1. ✅ Test document upload via Supen API
2. ✅ Test RAG queries
3. ✅ Build the knowledge UI
4. ✅ Integrate with Vibex agents

Need Help?

Common issues and solutions:

• R2R docs: https://github.com/SciPhi-AI/R2R
• Railway docs: https://docs.railway.app
• Supen issues: Check our docs/knowledge-quickstart.md