@cleocode/cleo 2026.3.2 → 2026.3.6

package/packages/ct-skills/skills/railway-platform/references/12-monorepo.md

@@ -1,294 +0,0 @@
-# Monorepo Deployment Patterns
-
-Railway supports two distinct monorepo deployment strategies. Choosing the correct approach is critical for successful builds.
-
-## Quick Decision
-
-| Question | Answer | Approach |
-|----------|--------|----------|
-| Do apps import shared code? | Yes | **Custom Commands** |
-| Are apps completely independent? | Yes | **Root Directory** |
-| Using pnpm/yarn workspaces? | Yes | **Custom Commands** |
-| Using Turborepo/Nx? | Yes | **Custom Commands** |
-
-## Strategy 1: Root Directory (Isolated Monorepo)
-
-**Use when:** Apps are completely independent, no shared code between them.
-
-**How it works:** Only the specified directory's code is available during build.
-
-**Example structure:**
-```
-├── frontend/          # React app
-│   ├── package.json   # Standalone
-│   └── src/
-└── backend/           # Python API
-    ├── requirements.txt
-    └── main.py
-```
-
-**Configuration:**
-```json
-{
-  "services": {
-    "frontend-service-id": {
-      "rootDirectory": "/frontend"
-    },
-    "backend-service-id": {
-      "rootDirectory": "/backend"
-    }
-  }
-}
-```
-
-## Strategy 2: Custom Commands (Shared Monorepo)
-
-**Use when:** Apps share code from common packages or use workspace tools.
-
-**How it works:** Full repo is available, commands filter to specific packages.
-
-**Example structure:**
-```
-├── package.json           # Root workspace config
-├── packages/
-│   ├── frontend/          # Imports from shared
-│   ├── backend/           # Imports from shared
-│   └── shared/            # Shared utilities
-├── pnpm-workspace.yaml
-└── turbo.json
-```
-
-**Configuration:**
-
-### pnpm Workspaces
-```json
-{
-  "services": {
-    "frontend-service-id": {
-      "build": {
-        "buildCommand": "pnpm --filter frontend build"
-      },
-      "deploy": {
-        "startCommand": "pnpm --filter frontend start"
-      },
-      "source": {
-        "watchPatterns": [
-          "/packages/frontend/**",
-          "/packages/shared/**"
-        ]
-      }
-    }
-  }
-}
-```
-
-### npm Workspaces
-```json
-{
-  "services": {
-    "backend-service-id": {
-      "build": {
-        "buildCommand": "npm run build --workspace=packages/backend"
-      },
-      "deploy": {
-        "startCommand": "npm run start --workspace=packages/backend"
-      }
-    }
-  }
-}
-```
-
-### Yarn Workspaces
-```json
-{
-  "services": {
-    "backend-service-id": {
-      "build": {
-        "buildCommand": "yarn workspace backend build"
-      },
-      "deploy": {
-        "startCommand": "yarn workspace backend start"
-      }
-    }
-  }
-}
-```
-
-### Turborepo
-```json
-{
-  "services": {
-    "frontend-service-id": {
-      "build": {
-        "buildCommand": "turbo run build --filter=frontend"
-      },
-      "deploy": {
-        "startCommand": "turbo run start --filter=frontend"
-      },
-      "source": {
-        "watchPatterns": [
-          "/apps/frontend/**",
-          "/packages/**"
-        ]
-      }
-    }
-  }
-}
-```
-
-## Watch Paths
-
-Prevent unnecessary rebuilds by setting watch patterns.
-
-**Critical:** Include shared packages that services depend on.
-
-```json
-{
-  "services": {
-    "frontend-service-id": {
-      "source": {
-        "watchPatterns": [
-          "/packages/frontend/**",
-          "/packages/shared/**",
-          "/packages/ui/**"
-        ]
-      }
-    },
-    "backend-service-id": {
-      "source": {
-        "watchPatterns": [
-          "/packages/backend/**",
-          "/packages/shared/**",
-          "/packages/db/**"
-        ]
-      }
-    }
-  }
-}
-```
-
-**Pattern format:** Gitignore-style patterns
-- `/packages/frontend/**` - All files in frontend
-- `!**/*.md` - Ignore markdown changes
-
-## Common Mistakes
-
-### Mistake 1: Root Directory with Shared Code
-
-**Wrong:**
-```json
-{
-  "services": {
-    "backend": {
-      "rootDirectory": "/packages/backend"
-    }
-  }
-}
-```
-**Result:** Build fails - shared package not accessible.
-
-**Right:**
-```json
-{
-  "services": {
-    "backend": {
-      "build": {
-        "buildCommand": "pnpm --filter backend build"
-      },
-      "deploy": {
-        "startCommand": "pnpm --filter backend start"
-      }
-    }
-  }
-}
-```
-
-### Mistake 2: Missing Shared Package in Watch Paths
-
-**Wrong:**
-```json
-{
-  "services": {
-    "backend": {
-      "source": {
-        "watchPatterns": ["/packages/backend/**"]
-      }
-    }
-  }
-}
-```
-**Result:** Changes to shared package don't trigger backend rebuild.
-
-**Right:**
-```json
-{
-  "source": {
-    "watchPatterns": [
-      "/packages/backend/**",
-      "/packages/shared/**"
-    ]
-  }
-}
-```
-
-## Detection
-
-### Check for Isolated Monorepo
-```bash
-# Apps have separate package.json
-# No imports between directories
-# No workspace config at root
-ls apps/*/package.json | wc -l  # Multiple package.json
-! test -f package.json || ! grep -q workspaces package.json
-```
-
-### Check for Shared Monorepo
-```bash
-# Has workspace indicators
-[[ -f pnpm-workspace.yaml ]] || [[ -f turbo.json ]] || [[ -f nx.json ]] || grep -q workspaces package.json
-
-# Or imports from sibling packages
-grep -r "@myapp/shared" packages/
-```
-
-## Examples
-
-### Complete Microservices Setup
-
-```json
-{
-  "services": {
-    "gateway": {
-      "variables": {
-        "AUTH_SERVICE": {"value": "http://auth.railway.internal:8080"},
-        "USER_SERVICE": {"value": "http://users.railway.internal:8080"},
-        "ORDER_SERVICE": {"value": "http://orders.railway.internal:8080"}
-      }
-    },
-    "auth": {
-      "variables": {
-        "DATABASE_URL": {"value": "${{AuthDB.DATABASE_URL}}"},
-        "REDIS_URL": {"value": "${{Redis.REDIS_URL}}"}
-      }
-    },
-    "users": {
-      "variables": {
-        "DATABASE_URL": {"value": "${{UsersDB.DATABASE_URL}}"},
-        "AUTH_URL": {"value": "http://auth.railway.internal:8080"}
-      }
-    }
-  }
-}
-```
-
-## Summary
-
-| Aspect | Root Directory | Custom Commands |
-|--------|---------------|-----------------|
-| **Code isolation** | Each service sees only its directory | All services see full repo |
-| **Shared packages** | Not supported | Fully supported |
-| **Build speed** | Faster (less context) | Slower (full repo) |
-| **Workspace tools** | Not compatible | Required |
-| **Watch paths** | Optional | Essential |
-
-**Golden rule:** If apps import from each other or use workspace tools, use Custom Commands. If completely independent, use Root Directory.

package/packages/ct-skills/skills/railway-platform/references/13-troubleshooting.md

@@ -1,335 +0,0 @@
-# Troubleshooting
-
-Common issues and their solutions.
-
-## Installation Issues
-
-### "command not found: railway"
-
-**Cause:** CLI not installed or not in PATH.
-
-**Solution:**
-```bash
-# Install
-npm install -g @railway/cli
-
-# Or via Homebrew
-brew install railway
-
-# Verify
-which railway
-```
-
-### "EACCES: permission denied"
-
-**Cause:** npm global permissions issue.
-
-**Solution:**
-```bash
-# Fix npm permissions
-mkdir ~/.npm-global
-npm config set prefix '~/.npm-global'
-export PATH=~/.npm-global/bin:$PATH
-
-# Then reinstall
-npm install -g @railway/cli
-```
-
-## Authentication Issues
-
-### "not authenticated"
-
-**Cause:** Not logged in.
-
-**Solution:**
-```bash
-railway login
-
-# For SSH/browserless
-railway login --browserless
-```
-
-### "token expired"
-
-**Cause:** Session expired.
-
-**Solution:**
-```bash
-railway logout
-railway login
-```
-
-## Project Issues
-
-### "No linked project"
-
-**Cause:** Current directory not linked to Railway project.
-
-**Solution:**
-```bash
-# Link to existing
-railway link -p project-name
-
-# Or create new
-railway init -n new-project
-
-# Check parent directories
-# Railway CLI walks up directory tree
-```
-
-### "Project not found"
-
-**Cause:** Wrong project name or no access.
-
-**Solution:**
-```bash
-# List available projects
-railway list
-
-# Verify access in Railway dashboard
-```
-
-## Deployment Issues
-
-### "Build failed"
-
-**Symptoms:** Deployment status FAILED, CI mode shows errors.
-
-**Common Causes & Fixes:**
-
-**Missing dependencies:**
-```bash
-# Check package.json, requirements.txt exist
-cat package.json | head -20
-
-# Verify lock file
-ls package-lock.json yarn.lock pnpm-lock.yaml
-```
-
-**Out of memory:**
-```bash
-# Increase Node memory
-railway variables set NODE_OPTIONS="--max-old-space-size=4096"
-```
-
-**Wrong build command:**
-```bash
-# Check build command
-railway logs --build --lines 100
-
-# See 06-environments.md to fix
-```
-
-### "Service crashed"
-
-**Symptoms:** Status CRASHED, constant restarts.
-
-**Common Causes & Fixes:**
-
-**Port not configured:**
-```javascript
-// Wrong
-app.listen(3000);
-
-// Right
-app.listen(process.env.PORT || 3000);
-```
-
-**Missing start command:**
-```bash
-# Verify start command
-railway logs --lines 50
-
-# Set in package.json or via config
-```
-
-**Runtime error:**
-```bash
-# Check logs
-railway logs --lines 200
-
-# SSH to debug
-railway ssh
-```
-
-### "No such file or directory"
-
-**Cause:** File path issues in container.
-
-**Fix:**
-```bash
-# Use absolute paths
-const path = require('path');
-const file = path.join(__dirname, 'file.txt');
-
-# Or use process.cwd()
-const file = path.join(process.cwd(), 'file.txt');
-```
-
-## Database Issues
-
-### "connection refused"
-
-**Cause:** Cannot connect to database.
-
-**Check:**
-1. Database service running
-2. Using correct DATABASE_URL
-3. Same environment
-4. Database initialized
-
-**Debug:**
-```bash
-# Test connection
-railway connect
-
-# Check database logs
-railway logs --service postgres --lines 100
-```
-
-### "database does not exist"
-
-**Cause:** Database not initialized.
-
-**Solution:**
-```bash
-# Wait for database to start
-# Or recreate from template
-```
-
-## Networking Issues
-
-### "ENOTFOUND api.railway.internal"
-
-**Cause:** Private domain not resolving.
-
-**Check:**
-1. Services in same project/environment
-2. Target service deployed
-3. Using correct domain format
-
-**Debug:**
-```bash
-# SSH and test
-railway ssh
-nslookup api.railway.internal
-ping api.railway.internal
-```
-
-### "Connection timeout"
-
-**Cause:** Service not responding.
-
-**Check:**
-1. Service running: `railway service status`
-2. Correct port exposed
-3. No firewall blocking
-4. Health checks passing
-
-## Performance Issues
-
-### Slow response times
-
-**Check:**
-```bash
-# View metrics
-railway metrics --service my-service
-
-# Check CPU/Memory usage
-# Look for spikes during requests
-```
-
-**Solutions:**
-- Increase replicas
-- Add caching (Redis)
-- Optimize database queries
-- Use CDN for static assets
-
-### High memory usage
-
-**Solutions:**
-- Check for memory leaks
-- Optimize data processing
-- Increase memory limit (if on Pro)
-- Use streaming for large files
-
-## Debugging Commands
-
-### Full Status Check
-
-```bash
-# CLI installed
-command -v railway && echo "✓ CLI installed" || echo "✗ CLI missing"
-
-# Authenticated
-railway whoami --json && echo "✓ Authenticated" || echo "✗ Not authenticated"
-
-# Project linked
-railway status --json && echo "✓ Project linked" || echo "✗ Not linked"
-
-# Service deployed
-railway service status --json | jq '.deployment.status'
-```
-
-### Log Analysis
-
-```bash
-# Recent errors
-railway logs --lines 100 --filter "@level:error"
-
-# Specific time range
-railway logs --since 1h --until 30m --lines 200
-
-# Build and deploy
-railway logs --build --lines 100
-railway logs --lines 100
-```
-
-### SSH Debugging
-
-```bash
-# Access container
-railway ssh
-
-# Check environment
-env | grep RAILWAY
-
-# Test network
-curl http://localhost:$PORT/health
-
-# Check files
-ls -la /app
-```
-
-## Getting Help
-
-### Railway Support
-
-1. **Central Station:** https://station.railway.com
-2. **Discord:** https://discord.gg/railway
-3. **Documentation:** https://docs.railway.com
-
-### Information to Provide
-
-When asking for help, include:
-- Project ID
-- Service name
-- Error messages
-- Recent changes
-- Deployment ID (if specific)
-
-### Debug Bundle
-
-```bash
-# Collect debug info
-{
-  echo "=== Status ==="
-  railway status --json
-  
-  echo "=== Recent Deployments ==="
-  railway deployment list --limit 5 --json
-  
-  echo "=== Recent Logs ==="
-  railway logs --lines 50
-} > debug.txt
-```