# Railway Deployment Guide

## Service Architecture

Production environments can use a multi-service architecture on Railway:

### Key Services

1. **API Gateway** (e.g., Kong) - Routes requests to backend services
2. **Backend** - Main application service (handles auth, users, billing, etc.)
3. **CMS** - Content management (e.g., Strapi)
4. **Database** - PostgreSQL database

### Critical: Deploy to the Correct Service

**ALWAYS deploy backend code to the correct backend service, NOT the gateway!**

## Deployment Commands

### 1. List All Services
```bash
railway status --json | jq -r '.services.edges[].node.name'
```

### 2. Deploy to Backend Service
```bash
# Option 1: Deploy with service flag (RECOMMENDED)
railway up --detach --service "your-backend-service"

# Option 2: Link to service first, then deploy
railway link --service "your-backend-service"
railway up --detach
```

### 3. Check Deployment Status
```bash
railway status --json | jq -r '.services.edges[] | select(.node.name == "your-service") | .node.serviceInstances.edges[0].node.latestDeployment'
```

## Common Mistakes to Avoid

- **DON'T:** Deploy without specifying service (deploys to wrong service)
- **DO:** Always specify the service explicitly
- **DON'T:** Assume `railway up` knows which service based on the code
- **DO:** Use Railway docs to understand service structure first

## GitHub CI/CD Integration

Railway can auto-deploy from GitHub when CI passes. If CI fails:

### Option 1: Fix CI and Let Auto-Deploy Work
```bash
# Fix failing tests, commit fixes, push to main
# Railway auto-deploys when CI passes
```

### Option 2: Force Deploy (Bypass CI)
```bash
# Use when change is critical and safe despite CI failures
railway up --detach --service your-backend-service
```

## Verifying Deployment

### 1. Check Health Endpoint
```bash
curl https://your-domain.com/health | jq
```

### 2. Check Railway Dashboard
- Build logs: https://railway.com/project/{project-id}/service/{service-id}
- Deployment status
- Error logs if deployment failed

## Database Connection Issues

If you see "Database connection failed" after deployment:

1. **Wait 2-3 minutes** - Service might still be starting
2. **Check Railway logs** - Look for connection errors
3. **Verify environment variables** - DATABASE_URL must be set correctly
4. **Check database service status** - Ensure PostgreSQL is running

## Troubleshooting

### Issue: "Service not found"
**Solution:** List services first, use exact service name
```bash
railway status --json | jq -r '.services.edges[].node.name'
railway up --service your-service  # Use exact name from list
```

### Issue: "Multiple services found"
**Solution:** Always use `--service` flag explicitly

### Issue: Deployment succeeds but changes don't appear
**Possible causes:**
1. Deployed to wrong service (check service name)
2. Code not committed to git (Railway deploys from git, not local files)
3. Deployment still in progress (wait longer)
4. Cache issue (try hard refresh or new incognito window)

## Best Practices

1. **Always verify service name before deploying**
2. **Use explicit service flags**
3. **Check deployment status after deploying**
4. **Use Railway dashboard for detailed logs**

## Quick Reference

```bash
# Deploy backend code
railway up --detach --service "your-backend-service"

# Check all services and their status
railway status --json | jq -r '.services.edges[].node | {name, latestDeployment: .serviceInstances.edges[0].node.latestDeployment.status}'
```
