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
```bash
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:**
```env
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`):

```env
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:

```powershell
# 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](./RAILWAY.md) - Full Railway deployment guide
- 💬 [Discord Community](https://discord.gg/37XJPXfz2w)
- 🐛 [GitHub Issues](https://github.com/lfnovo/open-notebook/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.