DEPLOYMENT.md•7.36 kB
# Railway Deployment Guide
This guide provides step-by-step instructions for deploying the Data Commons MCP Server on Railway.app.
## Prerequisites
1. **Railway Account**: Sign up at [railway.app](https://railway.app)
2. **Data Commons API Key**: Get one from [apikeys.datacommons.org](https://apikeys.datacommons.org/)
3. **GitHub Account**: Repository must be on GitHub for Railway deployment
## Deployment Steps
### Step 1: Prepare Your Repository
1. **Fork or Clone** this repository to your GitHub account
2. **Verify Files**: Ensure these files are present:
- `requirements.txt`
- `Procfile`
- `railway.json`
- `runtime.txt`
- `datacommons_mcp/` directory with all Python files
### Step 2: Create Railway Project
1. **Login to Railway**:
- Go to [railway.app](https://railway.app)
- Click "Login" and authenticate with GitHub
2. **Create New Project**:
- Click "New Project"
- Select "Deploy from GitHub repo"
- Choose `Data-Commons-mcp-server` repository
3. **Configure Deployment**:
- Railway will automatically detect the configuration
- Click "Deploy Now"
### Step 3: Configure Environment Variables
1. **Open Project Settings**:
- Click on your deployed service
- Go to "Variables" tab
2. **Add Required Variables**:
```
DC_API_KEY=your_actual_api_key_here
```
3. **Optional Variables** (if using custom Data Commons):
```
DC_API_ROOT=https://your-custom-instance.datacommons.org
```
4. **Save Changes**:
- Railway will automatically redeploy with new variables
### Step 4: Verify Deployment
1. **Check Deployment Status**:
- Go to "Deployments" tab
- Wait for status to show "Success" (green)
2. **Get Your URL**:
- Go to "Settings" tab
- Click "Generate Domain" under "Networking"
- Your MCP endpoint will be: `https://your-app.railway.app/mcp`
3. **Test the Endpoint**:
```bash
curl -X POST https://your-app.railway.app/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
## Configuration for MCP Clients
### Manus Configuration
Add to your Manus MCP settings:
```json
{
"mcpServers": {
"datacommons": {
"url": "https://your-app.railway.app/mcp",
"transport": "http",
"description": "Data Commons public statistics and data"
}
}
}
```
### Claude Desktop Configuration
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:
```json
{
"mcpServers": {
"datacommons": {
"command": "curl",
"args": [
"-X", "POST",
"https://your-app.railway.app/mcp",
"-H", "Content-Type: application/json",
"-d", "@-"
]
}
}
}
```
### Generic HTTP MCP Client
- **Endpoint**: `https://your-app.railway.app/mcp`
- **Method**: POST
- **Transport**: Streamable HTTP
- **Protocol**: MCP 1.0
## Monitoring and Maintenance
### View Logs
1. Go to your Railway project
2. Click on the service
3. Go to "Deployments" tab
4. Click on the active deployment
5. View real-time logs
### Check Resource Usage
1. Go to "Metrics" tab
2. Monitor:
- CPU usage
- Memory usage
- Network traffic
- Request count
### Update Deployment
Railway automatically redeploys when you push to the connected GitHub repository:
1. Make changes locally
2. Commit and push to GitHub
3. Railway detects changes and redeploys automatically
### Manual Redeploy
1. Go to "Deployments" tab
2. Click "⋮" menu on latest deployment
3. Select "Redeploy"
## Troubleshooting
### Deployment Fails
**Check Build Logs**:
1. Go to "Deployments" tab
2. Click on failed deployment
3. Review build logs for errors
**Common Issues**:
- Missing `DC_API_KEY` environment variable
- Python version mismatch (must be 3.11 or 3.12)
- Missing dependencies in `requirements.txt`
### Server Crashes
**Check Runtime Logs**:
1. View deployment logs
2. Look for Python exceptions or errors
**Common Causes**:
- Invalid API key
- Memory limit exceeded
- Network connectivity issues
### Can't Connect from MCP Client
**Verify Endpoint**:
- Ensure URL ends with `/mcp`
- Check that domain is generated and active
**Test with curl**:
```bash
curl -v https://your-app.railway.app/mcp
```
**Check CORS** (if browser-based):
- Railway should handle CORS automatically
- If issues persist, check Railway CORS settings
### API Rate Limits
**Data Commons Rate Limits**:
- Free tier: Limited requests per day
- Check [Data Commons documentation](https://docs.datacommons.org) for limits
**Solutions**:
- Implement caching (future enhancement)
- Upgrade Data Commons API tier
- Optimize query patterns
## Cost Considerations
### Railway Pricing
- **Hobby Plan**: $5/month
- 500 hours of execution time
- $0.000231/GB-hour for memory
- $0.000463/vCPU-hour
- **Pro Plan**: $20/month
- More resources and features
### Optimization Tips
1. **Sleep on Idle**: Enable in Railway settings to reduce costs
2. **Monitor Usage**: Check metrics regularly
3. **Optimize Queries**: Reduce unnecessary API calls
## Security Best Practices
### API Key Management
1. **Never Commit API Keys**: Always use environment variables
2. **Rotate Keys Regularly**: Generate new keys periodically
3. **Use Railway Secrets**: Store sensitive data in Railway variables
### Network Security
1. **HTTPS Only**: Railway provides SSL/TLS automatically
2. **Rate Limiting**: Consider implementing rate limits
3. **Access Control**: Use Railway's team features for collaboration
### Monitoring
1. **Enable Logging**: Keep deployment logs for audit
2. **Set Up Alerts**: Use Railway webhooks for notifications
3. **Regular Updates**: Keep dependencies updated
## Advanced Configuration
### Custom Domain
1. Go to "Settings" → "Networking"
2. Click "Custom Domain"
3. Add your domain (e.g., `mcp.yourdomain.com`)
4. Update DNS records as instructed
5. Railway handles SSL certificate automatically
### Environment-Specific Settings
**Development**:
```bash
DC_API_KEY=dev_key_here
LOG_LEVEL=DEBUG
```
**Production**:
```bash
DC_API_KEY=prod_key_here
LOG_LEVEL=INFO
```
### Health Checks
Railway automatically monitors your service. For custom health checks:
1. Add a health endpoint in your code
2. Configure in `railway.json`:
```json
{
"deploy": {
"healthcheckPath": "/health",
"healthcheckTimeout": 100
}
}
```
## Support and Resources
### Railway Support
- **Documentation**: [docs.railway.app](https://docs.railway.app)
- **Discord**: [Railway Community](https://discord.gg/railway)
- **Status**: [status.railway.app](https://status.railway.app)
### Data Commons Support
- **Documentation**: [docs.datacommons.org](https://docs.datacommons.org)
- **API Reference**: [datacommons.org/api](https://datacommons.org/api)
- **Community**: [Data Commons GitHub](https://github.com/datacommonsorg)
### MCP Protocol
- **Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **GitHub**: [MCP on GitHub](https://github.com/modelcontextprotocol)
## Next Steps
1. **Test Your Deployment**: Use the testing commands above
2. **Configure MCP Client**: Add to Manus or other MCP clients
3. **Monitor Performance**: Check Railway metrics regularly
4. **Optimize**: Adjust based on usage patterns
---
**Need Help?** Open an issue on GitHub or check the resources above.