Spaces:
Sleeping
Sleeping
File size: 5,534 Bytes
f871fed | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 | # 🚂 Railway Deployment Guide for Open Notebook
## Prerequisites
- A [Railway](https://railway.app/) 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](https://railway.app/)
- 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:
```bash
# 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`):
```bash
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
```bash
# 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:
```dockerfile
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](../README.md)
- 💬 [Discord Community](https://discord.gg/37XJPXfz2w)
- 🐛 [GitHub Issues](https://github.com/lfnovo/open-notebook/issues)
- 🚂 [Railway Docs](https://docs.railway.app/)
## 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](../docs/deployment/index.md) for more options.
|