Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danny-avila/librechat/llms.txt

Use this file to discover all available pages before exploring further.

​
Railway Deployment

Deploy LibreChat on Railway with automatic builds, managed databases, and easy scaling.

​
Quick Deploy

Deploy to Railway

Click to deploy LibreChat with pre-configured MongoDB and environment

​
What Gets Deployed

The Railway template includes:
  • LibreChat Application - Main web service
  • MongoDB - Database (Railway’s MongoDB plugin)
  • Meilisearch - Search engine (optional)
  • Automatic SSL - HTTPS with custom domains
  • Environment Variables - Pre-configured settings

​
Manual Deployment

If you prefer to deploy manually:
1

Create Railway Account

  1. Go to railway.com
  2. Sign up with GitHub account
  3. Verify your email
2

Create New Project

  1. Click “New Project”
  2. Select “Deploy from GitHub repo”
  3. Connect your GitHub account
  4. Select danny-avila/LibreChat or your fork
3

Add MongoDB

  1. Click ”+ New” in your project
  2. Select “Database” > “Add MongoDB”
  3. Railway will automatically provision a MongoDB instance
  4. Note the connection string from the “Connect” tab
4

Configure Environment Variables

In your LibreChat service settings, add these variables:
# Automatically set by Railway
PORT=3080

# MongoDB (use Railway's ${{MongoDB.MONGO_URL}} reference)
MONGO_URI=${{MongoDB.MONGO_URL}}

# Domain (use your Railway domain)
DOMAIN_CLIENT=https://your-app.up.railway.app
DOMAIN_SERVER=https://your-app.up.railway.app

# Security - Generate these!
CREDS_KEY=<generate-with-openssl-rand-hex-32>
CREDS_IV=<generate-with-openssl-rand-hex-16>
JWT_SECRET=<generate-with-openssl-rand-hex-32>
JWT_REFRESH_SECRET=<generate-with-openssl-rand-hex-32>

# AI Provider Keys
OPENAI_API_KEY=user_provided
ANTHROPIC_API_KEY=user_provided
GOOGLE_KEY=user_provided

# Search (if adding Meilisearch)
SEARCH=true
MEILI_HOST=${{Meilisearch.RAILWAY_PRIVATE_DOMAIN}}
MEILI_MASTER_KEY=<generate-secure-key>

# Session
SESSION_EXPIRY=900000
REFRESH_TOKEN_EXPIRY=604800000

# Registration
ALLOW_EMAIL_LOGIN=true
ALLOW_REGISTRATION=true
ALLOW_SOCIAL_LOGIN=false
Generate secrets locally:
openssl rand -hex 32  # For keys
openssl rand -hex 16  # For IV
5

Configure Build Settings

Railway should auto-detect these, but verify:Build Command:
npm ci && npm run build
Start Command:
npm run backend
Dockerfile (Alternative): Railway can also build from Dockerfile:
# Uses the included Dockerfile automatically
6

Deploy

  1. Click “Deploy”
  2. Wait for build to complete (5-10 minutes)
  3. Access your app at the generated Railway URL

​
Configuration

​
Custom Domain

1

Add Domain in Railway

  1. Go to your LibreChat service
  2. Click “Settings” > “Domains”
  3. Click “Custom Domain”
  4. Enter your domain (e.g., chat.yourdomain.com)
2

Configure DNS

Add a CNAME record in your DNS provider:
Type: CNAME
Name: chat (or your subdomain)
Value: your-app.up.railway.app
3

Update Environment Variables

Update domains in Railway:
DOMAIN_CLIENT=https://chat.yourdomain.com
DOMAIN_SERVER=https://chat.yourdomain.com

​
Adding Meilisearch

1

Create Meilisearch Service

  1. Click ”+ New” > “Empty Service”
  2. Name it “Meilisearch”
  3. Go to “Settings” > “Deploy”
2

Configure Meilisearch

Source:
Image: getmeili/meilisearch:v1.35.1
Environment Variables:
MEILI_MASTER_KEY=your_secure_master_key
MEILI_NO_ANALYTICS=true
MEILI_ENV=production
3

Update LibreChat Config

Add to LibreChat service variables:
SEARCH=true
MEILI_HOST=http://${{Meilisearch.RAILWAY_PRIVATE_DOMAIN}}:7700
MEILI_MASTER_KEY=your_secure_master_key

​
Volume Persistence

Railway provides ephemeral storage by default. For persistent storage:
1

Add Volume

  1. Go to your service settings
  2. Click “Volumes”
  3. Click ”+ New Volume”
  4. Set mount path: /app/uploads
2

Add More Volumes

Recommended volumes:
/app/uploads  - User file uploads
/app/logs     - Application logs
/app/images   - User images

​
Environment Variables Reference

​
Required Variables

VariableDescriptionExample
MONGO_URIMongoDB connection string${{MongoDB.MONGO_URL}}
CREDS_KEYEncryption key (hex 32)9e95d9894d...
CREDS_IVEncryption IV (hex 16)ac028c86b...
JWT_SECRETJWT signing key16f8c0ef4...
JWT_REFRESH_SECRETRefresh token keyeaa5191f2...

​
Optional Variables

VariableDescriptionDefault
OPENAI_API_KEYOpenAI API keyuser_provided
ANTHROPIC_API_KEYAnthropic API keyuser_provided
GOOGLE_KEYGoogle API keyuser_provided
ALLOW_REGISTRATIONAllow new signupstrue
ALLOW_EMAIL_LOGINEmail/password logintrue
SEARCHEnable searchfalse
DEBUG_LOGGINGEnable debug logsfalse

​
Railway-Specific Variables

Railway provides these automatically: 
RAILWAY_ENVIRONMENT=production
RAILWAY_PROJECT_NAME=librechat
RAILWAY_SERVICE_NAME=librechat
RAILWAY_STATIC_URL=your-app.up.railway.app

​
Monitoring & Logs

​
View Logs

  1. Go to your service
  2. Click “Deployments”
  3. Select active deployment
  4. View real-time logs

​
Metrics

Railway provides:
  • CPU usage
  • Memory usage
  • Network traffic
  • Deployment history

​
Health Checks

LibreChat exposes a health endpoint: 
GET https://your-app.up.railway.app/health

​
Scaling

​
Vertical Scaling

  1. Go to service “Settings”
  2. Adjust resources:
    • Starter: 512 MB RAM, 1 vCPU
    • Developer: 8 GB RAM, 8 vCPU
    • Team: 32 GB RAM, 32 vCPU

​
Horizontal Scaling

Horizontal scaling requires Redis for session sharing:
# Add Redis service
USE_REDIS=true
REDIS_URI=${{Redis.REDIS_URL}}
Then enable replicas in service settings.

​
Cost Optimization

​
Free Tier

Railway offers:
  • $5 free credit/month
  • Pay only for usage
  • No credit card required to start

​
Estimated Costs

Usage LevelMonthly Cost
Light (< 100 users)$5-15
Medium (100-1000 users)$15-50
Heavy (1000+ users)$50+

​
Reduce Costs

  1. Optimize Memory: Adjust NODE_MAX_OLD_SPACE_SIZE
  2. Use Sleep Mode: Enable for development projects
  3. Optimize Queries: Add database indexes
  4. CDN for Assets: Use external CDN for images

​
Troubleshooting

​
Build Failures

Issue: Build timeout or out of memory 
# Increase build memory in railway.json
{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "NODE_OPTIONS='--max-old-space-size=8192' npm ci && npm run build"
  }
}

​
Database Connection Issues

Issue: Cannot connect to MongoDB
  1. Check MONGO_URI uses ${{MongoDB.MONGO_URL}}
  2. Verify MongoDB service is running
  3. Check MongoDB logs for errors

​
Domain Not Working

Issue: Custom domain shows error
  1. Verify CNAME record is correct
  2. Wait for DNS propagation (up to 48 hours)
  3. Check SSL certificate is issued
  4. Update DOMAIN_CLIENT and DOMAIN_SERVER

​
High Memory Usage

Issue: Service crashes with OOM errors 
# Add to environment variables
NODE_OPTIONS=--max-old-space-size=4096

# Or adjust in Dockerfile build args
NODE_MAX_OLD_SPACE_SIZE=4096

​
Migration from Other Platforms

​
From Docker

  1. Export MongoDB data: 
    mongodump --uri="mongodb://localhost:27017/LibreChat" --out=./backup
  2. Import to Railway MongoDB: 
    mongorestore --uri="$RAILWAY_MONGO_URI" ./backup
  3. Deploy LibreChat on Railway

​
From Other Hosts

  1. Copy .env variables to Railway
  2. Migrate database to Railway MongoDB
  3. Update domain settings
  4. Test thoroughly before DNS cutover

​
Best Practices

  • Use strong, unique secrets for all keys
  • Enable automatic deployments from GitHub
  • Set up custom domain with SSL
  • Configure volumes for persistent storage
  • Monitor logs and metrics regularly
  • Set up health check alerts
  • Keep dependencies updated
  • Use environment-specific variables
  • Test deployments in staging first
  • Document your configuration

​
Support

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us