RAILWAY.md

🚂 Railway Deployment Guide for Open Notebook

Prerequisites

• A Railway account
• At least one AI API key (OpenAI, Anthropic, etc.)

Quick Deploy

Option 1: Deploy from GitHub (Recommended)

1. Fork this repository to your GitHub account

2. Create a new Railway project:

   • Go to Railway
   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose your forked repository

3. Configure Environment Variables:

   Go to your Railway service → Variables tab and add:

   # Required Variables
   SURREAL_URL=ws://127.0.0.1:8000/rpc
   SURREAL_USER=root
   SURREAL_PASSWORD=root
   SURREAL_NAMESPACE=open_notebook
   SURREAL_DATABASE=production
   INTERNAL_API_URL=http://127.0.0.1:5055
   
   # Add your AI API key (at least one required)
   OPENAI_API_KEY=sk-your-key-here
   

4. After first deployment, set the API_URL:

   Once Railway generates your public URL (e.g., https://your-app.up.railway.app):

   API_URL=https://your-app.up.railway.app
   

5. Configure Railway Settings:

   • Go to Settings → Networking
   • Make sure port 8080 is exposed (Railway should auto-detect this)
   • Health check path: /api/health

6. Redeploy after adding the API_URL

Option 2: Deploy with Railway CLI

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

# Login to Railway
railway login

# Link to project (or create new)
railway link

# Set environment variables
railway variables set SURREAL_URL=ws://127.0.0.1:8000/rpc
railway variables set SURREAL_USER=root
railway variables set SURREAL_PASSWORD=root
railway variables set SURREAL_NAMESPACE=open_notebook
railway variables set SURREAL_DATABASE=production
railway variables set INTERNAL_API_URL=http://127.0.0.1:5055
railway variables set OPENAI_API_KEY=sk-your-key-here

# Deploy
railway up

# Get your app URL
railway domain

# Set API_URL with your domain
railway variables set API_URL=https://your-app.up.railway.app

Architecture

This deployment uses the single-container architecture:

• ✅ SurrealDB (embedded database)
• ✅ FastAPI backend (port 5055)
• ✅ Background worker
• ✅ Next.js frontend (port 8080)

All services run in one container managed by Supervisord.

Troubleshooting

Build Fails

Issue: Build timeout or memory issues

Solution:

• Increase Railway instance size temporarily during build
• Or use pre-built Docker image:

  FROM lfnovo/open_notebook:v1-latest-single
  

Service Won't Start

Issue: Container restarts continuously

Solution: Check logs for:

1. Missing environment variables (especially SURREAL_URL)
2. Database connection errors
3. Frontend build issues

Can't Access the App

Issue: Railway shows running but can't access

Solution:

1. Verify API_URL is set to your Railway domain
2. Check that port 8080 is exposed in Railway settings
3. Wait 2-3 minutes after deployment for all services to start

Database Migration Errors

Issue: Migration fails on startup

Solution:

• Ensure all required migrations files exist (1-17)
• Check database connection settings
• View logs: railway logs or in Railway dashboard

Environment Variables Reference

Variable	Required	Default	Description
SURREAL_URL	Yes	-	Database WebSocket URL
SURREAL_USER	Yes	-	Database username
SURREAL_PASSWORD	Yes	-	Database password
SURREAL_NAMESPACE	Yes	-	Database namespace
SURREAL_DATABASE	Yes	-	Database name
INTERNAL_API_URL	Yes	-	Internal API endpoint
API_URL	Yes	-	Public API URL (your Railway domain)
OPENAI_API_KEY	Yes*	-	OpenAI API key (*or another AI provider)
ANTHROPIC_API_KEY	No	-	Anthropic API key
GOOGLE_API_KEY	No	-	Google AI API key
OPEN_NOTEBOOK_PASSWORD	No	-	Optional app password protection

Persistent Data

Railway provides ephemeral storage, meaning:

• ⚠️ Database data will be lost on redeploys
• ⚠️ Uploaded files will be lost on redeploys

For production use, consider:

1. Using Railway's Volume feature for /mydata (database)
2. Using external storage (S3, Cloudinary) for uploads
3. Or deploying to a platform with persistent storage

Performance Tips

1. Start with Hobby plan ($5/month) for testing
2. Upgrade if needed based on usage
3. Monitor memory usage - increase if services crash
4. Use CDN for faster frontend loading (Railway Pro)

Cost Estimation

• Hobby Plan: ~$5-10/month (includes some usage)
• Pro Plan: ~$20-30/month (higher limits)
• Plus: AI API costs (pay per use)

Railway charges for:

• CPU time
• Memory usage
• Bandwidth

The single-container deployment is optimized to minimize costs.

Support

• 📖 Full Documentation
• 💬 Discord Community
• 🐛 GitHub Issues
• 🚂 Railway Docs

Alternative Deployment Options

If Railway doesn't work for you, consider:

• Docker - Self-hosted on any VPS (DigitalOcean, Linode, etc.)
• AWS ECS/Fargate - Managed containers
• Google Cloud Run - Serverless containers
• Azure Container Instances - Pay-per-use containers
• Fly.io - Similar to Railway

See the main Deployment Guide for more options.