RAILWAY_FIXES.md

Railway Deployment Fixes - Summary

Issues Identified

1. ⚠️ Next.js Standalone Configuration Conflict

Problem: The logs showed:

⚠ "next start" does not work with "output: standalone" configuration. 
Use "node .next/standalone/server.js" instead.

Root Cause: frontend/next.config.ts had output: "standalone" enabled, but the startup command used npm run start which calls next start.

Fix Applied:

• Disabled standalone mode in next.config.ts for Railway deployment
• This allows standard next start command to work properly

2. 📦 Missing Database Migrations (15, 16, 17)

Problem: Migration files 15-17 existed but weren't registered in the migration manager, causing potential schema inconsistencies.

Fix Applied:

• Updated open_notebook/database/async_migrate.py to include migrations 15, 16, and 17
• Added both up and down migration files

3. 🔧 Railway-Specific Configuration Missing

Problem: No Railway-specific configuration files, making deployment harder and less optimized.

Fix Applied:

• Created railway.json for Railway build configuration
• Created Dockerfile.railway optimized for Railway
• Created supervisord.railway.conf with proper PORT env variable handling
• Created .env.railway template with all required variables
• Created RAILWAY.md comprehensive deployment guide

4. 🌐 Port Configuration for Railway

Problem: Railway assigns dynamic PORT, but the config wasn't flexible enough.

Fix Applied:

• Updated supervisord to use %(ENV_PORT)s to read Railway's PORT variable
• Ensured frontend binds to the correct port (8080 by default, or Railway's PORT)

Files Created

1. railway.json - Railway deployment configuration
2. Dockerfile.railway - Railway-optimized Docker build
3. supervisord.railway.conf - Railway-specific supervisor config
4. .env.railway - Environment variable template for Railway
5. RAILWAY.md - Complete deployment guide for Railway users

Files Modified

1. frontend/next.config.ts - Disabled standalone output for Railway
2. open_notebook/database/async_migrate.py - Added migrations 15, 16, 17
3. supervisord.single.conf - Fixed frontend startup command

Deployment Success Indicators

From your logs, the deployment was actually mostly successful:

• ✅ SurrealDB started correctly
• ✅ API server started on port 5055
• ✅ Worker started successfully
• ✅ Frontend built and started on port 8080
• ✅ All migrations (1-14) ran successfully
• ✅ All services entered RUNNING state

The warning about standalone mode was not blocking deployment, but could cause issues in production.

What Was Actually Wrong?

Looking at your logs more carefully, there's NO ERROR - the deployment was successful!

The confusion might be:

1. The supervisor warning about running as root (not critical)
2. The Next.js standalone warning (now fixed)
3. Missing pytesseract module (optional OCR feature)

These are warnings, not errors. The app should be working.

How to Deploy to Railway Now

Step 1: Push Changes to GitHub

cd c:\sem6-real\studyrocket\notebookllm\open-notebook
git add .
git commit -m "Add Railway deployment configuration and fixes"
git push origin main

Step 2: Configure Railway Environment Variables

In Railway dashboard, add these variables:

Required:

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=your_actual_key_here

Step 3: Set API_URL After First Deploy

After Railway generates your domain (e.g., https://your-app-production-xxxx.up.railway.app):

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

Then redeploy.

Step 4: Verify Deployment

Check these endpoints:

• https://your-app.up.railway.app/ - Frontend UI
• https://your-app.up.railway.app/api/health - API health check
• https://your-app.up.railway.app/api/docs - API documentation

Troubleshooting

If Build Times Out

Railway free tier has build time limits. Solutions:

1. Upgrade to Hobby plan ($5/month)
2. Use pre-built image: FROM lfnovo/open_notebook:v1-latest-single

If App Crashes After Deploy

1. Check Railway logs for actual errors
2. Verify all environment variables are set
3. Wait 2-3 minutes - services need time to start

If Frontend Can't Connect to API

1. Ensure API_URL is set to your Railway domain
2. Check that port 8080 is exposed (Railway auto-detects)
3. Verify INTERNAL_API_URL=http://127.0.0.1:5055

Testing Locally

Before pushing to Railway, test with Docker:

# Build Railway Dockerfile
docker build -f Dockerfile.railway -t open-notebook-railway .

# Run with Railway-like environment
docker run -p 8080:8080 -p 5055:5055 `
  -e PORT=8080 `
  -e SURREAL_URL=ws://127.0.0.1:8000/rpc `
  -e SURREAL_USER=root `
  -e SURREAL_PASSWORD=root `
  -e SURREAL_NAMESPACE=open_notebook `
  -e SURREAL_DATABASE=production `
  -e INTERNAL_API_URL=http://127.0.0.1:5055 `
  -e API_URL=http://localhost:8080 `
  -e OPENAI_API_KEY=your_key `
  open-notebook-railway

Access at: http://localhost:8080

Next Steps

1. ✅ Commit and push all changes to GitHub
2. ✅ Configure environment variables in Railway
3. ✅ Deploy from GitHub in Railway
4. ✅ Set API_URL after getting your domain
5. ✅ Redeploy to apply API_URL
6. ✅ Test all functionality

Additional Notes

• Database persistence: Railway containers are ephemeral. For production, consider:

  • Using Railway Volumes for /mydata (database storage)
  • Exporting/importing data periodically
  • Using external database (more expensive)

• Costs: Railway charges for:

  • CPU usage
  • Memory usage
  • Bandwidth
  • Start with Hobby plan ($5/mo) for testing

• Performance: Single container runs 4 services, so:

  • May need 2GB+ RAM for smooth operation
  • Consider upgrading Railway plan if services crash

Support Resources

• 📖 RAILWAY.md - Full Railway deployment guide
• 💬 Discord Community
• 🐛 GitHub Issues

---

Important: Your deployment logs show the app IS WORKING. The issues were warnings, not blocking errors. These fixes will make the deployment more robust and eliminate the warnings.