RAILWAY_CHECKLIST.md

🚀 Railway Deployment Quick Checklist

Pre-Deployment

• Fork repository to your GitHub account
• Have at least one AI API key ready (OpenAI, Anthropic, etc.)
• Have Railway account created

Step 1: Push Code

git add .
git commit -m "Add Railway deployment fixes"
git push origin main

Step 2: Create Railway Project

• Go to https://railway.app/
• Click "New Project"
• Select "Deploy from GitHub repo"
• Choose your forked repository
• Railway will start building automatically

Step 3: Set Environment Variables (CRITICAL!)

Go to Railway → Your Service → Variables tab

Required Variables (Set BEFORE first successful deploy):

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
OPENAI_API_KEY=sk-your-actual-openai-key

• All required variables set
• Wait for build to complete
• Note your Railway domain (e.g., https://yourapp-production.up.railway.app)

Step 4: Set API_URL (AFTER getting domain)

API_URL=https://yourapp-production.up.railway.app

• API_URL variable added with YOUR actual Railway domain
• Redeploy triggered (automatic after adding variable)

Step 5: Configure Railway Settings

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

Step 6: Verify Deployment

Check These URLs:

• https://yourapp.up.railway.app/ → Should show Open Notebook UI
• https://yourapp.up.railway.app/api/health → Should return {"status":"ok"}
• https://yourapp.up.railway.app/api/docs → Should show API documentation

Check Railway Logs:

• All 4 services started: surrealdb, api, worker, frontend
• No error messages (warnings are OK)
• Migrations completed successfully
• Frontend shows "Ready in XXms"

Step 7: Test Functionality

• Create a new notebook
• Upload a test document
• Try chat functionality
• Generate a podcast (optional)

Common Issues & Quick Fixes

❌ Build Timeout

Solution: Upgrade to Railway Hobby plan ($5/month) for longer build times

❌ Services Keep Restarting

Solution: Check environment variables are set correctly, especially SURREAL_URL

❌ Frontend Can't Connect to API

Solution: Ensure API_URL is set to your actual Railway domain (with https://)

❌ Out of Memory

Solution: Upgrade Railway plan (single container needs ~2GB RAM)

❌ "Database Connection Failed"

Solution:

1. Check SURREAL_URL=ws://127.0.0.1:8000/rpc (note: 127.0.0.1, not localhost)
2. Verify SurrealDB service is running in logs

Environment Variables Checklist

Required (App Won't Work Without These):

• SURREAL_URL
• SURREAL_USER
• SURREAL_PASSWORD
• SURREAL_NAMESPACE
• SURREAL_DATABASE
• INTERNAL_API_URL
• API_URL (add after first deploy)
• At least one AI API key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

Optional (Add As Needed):

• ANTHROPIC_API_KEY - For Claude models
• GOOGLE_API_KEY - For Gemini models
• GROQ_API_KEY - For Groq models
• MISTRAL_API_KEY - For Mistral models
• OPEN_NOTEBOOK_PASSWORD - For password protection
• FIRECRAWL_API_KEY - For enhanced web scraping
• JINA_API_KEY - For advanced embeddings

Success Indicators

Your deployment is successful when you see in Railway logs:

✓ Ready in XXXms
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:5055
Migrations completed successfully. Database is now at version 17
All services entered RUNNING state

Cost Estimation

Railway Hobby Plan: ~$5-10/month

• Includes $5 usage credit
• Covers single container deployment
• Sufficient for testing and small-scale use

Plus AI API Costs: Pay-per-use

• OpenAI: ~$0.002-0.06 per 1K tokens
• Anthropic: Similar pricing
• Varies by model and usage

Support

Need help?

• 📖 Read RAILWAY.md for detailed guide
• 💬 Join Discord
• 🐛 Report GitHub Issues

---

After Successful Deployment

1. Bookmark your Railway app URL
2. Set up volume (in Railway) for /mydata to persist database
3. Monitor usage in Railway dashboard
4. Configure more AI providers as needed
5. Secure with password by setting OPEN_NOTEBOOK_PASSWORD

Development Workflow

To update your deployed app:

1. Make changes locally
2. Test with docker compose up or npm run dev
3. Commit and push to GitHub
4. Railway auto-deploys (if enabled)
5. Verify in Railway logs

---

Pro Tip: Copy this checklist and check off items as you complete them!