@cleocode/cleo 2026.2.5 → 2026.2.6

package/packages/ct-skills/skills/railway-platform/references/04-deployments.md

@@ -0,0 +1,210 @@
+# Deployments
+
+Deploy code, manage releases, and debug issues.
+
+## Deploy Code
+
+### Basic Deploy
+
+```bash
+railway up --detach
+```
+
+### With Commit Message
+
+```bash
+railway up --detach -m "Add user authentication"
+```
+
+Always use commit messages for clarity.
+
+### CI Mode (Streaming)
+
+```bash
+railway up --ci -m "Deploy with streaming logs"
+```
+
+Use for debugging builds. Streams build logs until completion.
+
+### Deploy Specific Service
+
+```bash
+railway up --detach --service backend
+```
+
+### Deploy to Unlinked Project
+
+```bash
+railway up --project <project-id> --environment production --detach
+```
+
+## Deployment Lifecycle
+
+### Redeploy
+
+Redeploy latest without new code:
+
+```bash
+railway redeploy --service my-service -y
+```
+
+Use when:
+- Config changed via environment
+- External resources updated
+- Service needs restart
+
+### Restart
+
+Restart container without rebuild:
+
+```bash
+railway restart --service my-service -y
+```
+
+Picks up external changes (S3, config maps).
+
+### Remove Deployment
+
+Take down service (keeps service):
+
+```bash
+railway down -y
+```
+
+## View Logs
+
+### Deployment Logs
+
+```bash
+railway logs --lines 100
+```
+
+### Build Logs
+
+```bash
+railway logs --build --lines 100
+```
+
+### Latest Deployment
+
+```bash
+railway logs --latest --lines 100
+```
+
+For failed/in-progress deployments.
+
+### Filter Logs
+
+```bash
+# Errors only
+railway logs --lines 50 --filter "@level:error"
+
+# Text search
+railway logs --lines 50 --filter "connection refused"
+
+# Time-based
+railway logs --since 1h --lines 100
+```
+
+### Time Formats
+
+- Relative: `30s`, `5m`, `2h`, `1d`, `1w`
+- ISO 8601: `2024-01-15T10:00:00Z`
+
+## List Deployments
+
+```bash
+railway deployment list --limit 10 --json
+```
+
+Shows:
+- Deployment IDs
+- Status (SUCCESS, FAILED, DEPLOYING, BUILDING)
+- Timestamps
+
+## Deployment Status
+
+| Status | Meaning |
+|--------|---------|
+| SUCCESS | Deployed and running |
+| FAILED | Build or deploy failed |
+| DEPLOYING | Currently deploying |
+| BUILDING | Build in progress |
+| CRASHED | Runtime crash |
+| REMOVED | Deployment removed |
+
+## Troubleshooting
+
+### Build Failures
+
+**Symptoms:** Status shows FAILED, CI mode shows errors.
+
+**Common causes:**
+- Missing dependencies (package.json, requirements.txt)
+- Incorrect build command
+- Out of memory
+- Dockerfile errors
+
+**Fixes:**
+```bash
+# Check build logs
+railway logs --build --lines 200
+
+# Increase memory
+# Set variable: NODE_OPTIONS="--max-old-space-size=4096"
+
+# Fix build command
+# See 06-environments.md
+```
+
+### Service Crashes
+
+**Symptoms:** Status shows CRASHED, constant restarts.
+
+**Common causes:**
+- Port not using $PORT env var
+- Missing start command
+- Runtime errors
+
+**Fixes:**
+```bash
+# Check deploy logs
+railway logs --lines 200
+
+# Verify PORT usage
+# Should listen on process.env.PORT || 8080
+
+# Check start command
+# See 06-environments.md
+```
+
+### SSH Debugging
+
+```bash
+railway ssh
+```
+
+Access running container for interactive debugging.
+
+## Rollback
+
+### Via Dashboard
+
+1. Go to service → Deployments
+2. Find working deployment
+3. Click "Redeploy"
+
+### Via CLI
+
+```bash
+# Get deployment ID
+railway deployment list --limit 5
+
+# Redeploy specific deployment
+railway redeploy --service my-service -y
+```
+
+## Next Steps
+
+- [06-environments.md](06-environments.md) - Fix config issues
+- [13-troubleshooting.md](13-troubleshooting.md) - Advanced debugging

package/packages/ct-skills/skills/railway-platform/references/05-databases.md

@@ -0,0 +1,142 @@
+# Databases
+
+Deploy and connect PostgreSQL, Redis, MySQL, and MongoDB.
+
+## Available Databases
+
+| Database | Template Code | Default Variable |
+|----------|---------------|------------------|
+| PostgreSQL | `postgres` | `DATABASE_URL` |
+| Redis | `redis` | `REDIS_URL` |
+| MySQL | `mysql` | `MYSQL_URL` |
+| MongoDB | `mongodb` | `MONGO_URL` |
+
+## Check for Existing Databases
+
+Before creating, check if database exists:
+
+```bash
+source _shared/scripts/railway-api.sh
+
+ENV_ID=$(get_environment_id)
+
+railway_api '
+  query environmentConfig($environmentId: String!) {
+    environment(id: $environmentId) {
+      config(decryptVariables: false)
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\"}" | jq '.data.environment.config.services | to_entries[] | select(.value.source.image | contains("postgres") or contains("redis") or contains("mysql") or contains("mongo"))'
+```
+
+## Deploy Database Template
+
+### Step 1: Get Template
+
+```bash
+source _shared/scripts/railway-api.sh
+
+railway_api '
+  query template($code: String!) {
+    template(code: $code) {
+      id
+      name
+      serializedConfig
+    }
+  }
+' '{"code": "postgres"}'
+```
+
+### Step 2: Deploy
+
+```bash
+PROJECT_ID=$(get_project_id)
+ENV_ID=$(get_environment_id)
+
+# Get workspace ID
+WORKSPACE_ID=$(railway_api '
+  query getWorkspace($projectId: String!) {
+    project(id: $projectId) { workspaceId }
+  }
+' "{\"projectId\": \"$PROJECT_ID\"}" | jq -r '.data.project.workspaceId')
+
+# Deploy template
+railway_api '
+  mutation deployTemplate($input: TemplateDeployV2Input!) {
+    templateDeployV2(input: $input) {
+      projectId
+      workflowId
+    }
+  }
+' "{\"input\": {\"templateId\": \"TEMPLATE_ID\", \"serializedConfig\": SERIALIZED_CONFIG, \"projectId\": \"$PROJECT_ID\", \"environmentId\": \"$ENV_ID\", \"workspaceId\": \"$WORKSPACE_ID\"}}"
+```
+
+## Connect Service to Database
+
+### Backend Connection
+
+```bash
+source _shared/scripts/railway-api.sh
+
+ENV_ID=$(get_environment_id)
+SERVICE_ID=$(get_service_id)
+
+# Stage DATABASE_URL variable
+railway_api '
+  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
+    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
+      id
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"variables\": {\"DATABASE_URL\": {\"value\": \"\\${{Postgres.DATABASE_URL}}\"}}}}}}"
+
+# Apply changes
+railway_api '
+  mutation commitStaged($environmentId: String!, $message: String) {
+    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"message\": \"Add database connection\"}"
+```
+
+### Connection URLs
+
+**PostgreSQL:**
+- Private: `${{Postgres.DATABASE_URL}}`
+- Public: `${{Postgres.DATABASE_PUBLIC_URL}}` (with TCP proxy)
+
+**Redis:**
+- Private: `${{Redis.REDIS_URL}}`
+- Public: `${{Redis.REDIS_PUBLIC_URL}}`
+
+**MySQL:**
+- Private: `${{MySQL.MYSQL_URL}}`
+- Public: `${{MySQL.MYSQL_PUBLIC_URL}}`
+
+**MongoDB:**
+- Private: `${{MongoDB.MONGO_URL}}`
+- Public: `${{MongoDB.MONGO_PUBLIC_URL}}`
+
+## Database with Volume
+
+Databases created from templates automatically include volumes for persistence.
+
+To verify:
+```bash
+railway status --json | jq '.services[] | select(.name | test("postgres|redis|mysql|mongo"; "i")) | .volumes'
+```
+
+## Complete Example
+
+```bash
+# 1. Check if postgres exists
+# 2. If not, deploy postgres template
+# 3. Get backend service ID
+# 4. Wire DATABASE_URL
+# 5. Apply changes
+# 6. Deploy backend
+```
+
+## Next Steps
+
+- [08-volumes.md](08-volumes.md) - Persistent storage details
+- [09-networking.md](09-networking.md) - TCP proxy for external access

package/packages/ct-skills/skills/railway-platform/references/06-environments.md

@@ -0,0 +1,261 @@
+# Environment Configuration
+
+Manage variables, build settings, deploy settings, and service configuration.
+
+## Environment Variables
+
+### Set Variable
+
+```bash
+railway variables set KEY=value
+```
+
+### Set Multiple Variables
+
+```bash
+railway variables set KEY1=value1 KEY2=value2
+```
+
+### List Variables
+
+```bash
+railway variables --json
+```
+
+Shows rendered (resolved) values.
+
+### Delete Variable
+
+```bash
+railway variables delete KEY
+```
+
+### Raw Editor
+
+For bulk changes, use dashboard Variables tab → "Raw Editor".
+
+## Advanced Configuration
+
+### Query Current Config
+
+```bash
+source _shared/scripts/railway-api.sh
+
+ENV_ID=$(get_environment_id)
+
+railway_api '
+  query envConfig($environmentId: String!) {
+    environment(id: $environmentId) {
+      id
+      config(decryptVariables: false)
+    }
+    environmentStagedChanges(environmentId: $environmentId) {
+      id
+      patch(decryptVariables: false)
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\"}"
+```
+
+### Stage Changes
+
+```bash
+SERVICE_ID=$(get_service_id)
+
+railway_api '
+  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
+    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
+      id
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"variables\": {\"API_KEY\": {\"value\": \"secret\", \"encrypted\": true}}}}}}"
+```
+
+### Apply Staged Changes
+
+```bash
+railway_api '
+  mutation commitStaged($environmentId: String!, $message: String) {
+    environmentPatchCommitStaged(environmentId: $environmentId, commitMessage: $message)
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"message\": \"Add API_KEY variable\"}"
+```
+
+## Build Configuration
+
+### Custom Build Command
+
+```json
+{
+  "services": {
+    "my-service": {
+      "build": {
+        "buildCommand": "npm run build:production"
+      }
+    }
+  }
+}
+```
+
+### Custom Start Command
+
+```json
+{
+  "services": {
+    "my-service": {
+      "deploy": {
+        "startCommand": "node dist/server.js"
+      }
+    }
+  }
+}
+```
+
+### Root Directory
+
+For subdirectory deployment:
+
+```json
+{
+  "services": {
+    "frontend": {
+      "rootDirectory": "/frontend"
+    }
+  }
+}
+```
+
+### Watch Paths
+
+Control which file changes trigger rebuilds:
+
+```json
+{
+  "services": {
+    "backend": {
+      "source": {
+        "watchPatterns": [
+          "/backend/**",
+          "/shared/**"
+        ]
+      }
+    }
+  }
+}
+```
+
+## Deploy Configuration
+
+### Health Checks
+
+```json
+{
+  "services": {
+    "api": {
+      "deploy": {
+        "healthcheck": {
+          "enabled": true,
+          "path": "/health",
+          "port": 8080
+        }
+      }
+    }
+  }
+}
+```
+
+### Replicas
+
+```json
+{
+  "services": {
+    "api": {
+      "deploy": {
+        "multiRegionConfig": {
+          "us-west1": {
+            "numReplicas": 2
+          },
+          "us-east1": {
+            "numReplicas": 2
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Restart Policy
+
+```json
+{
+  "services": {
+    "worker": {
+      "deploy": {
+        "restartPolicy": {
+          "type": "ON_FAILURE",
+          "maxRetries": 3
+        }
+      }
+    }
+  }
+}
+```
+
+## Variable References
+
+Reference variables from other services:
+
+```json
+{
+  "services": {
+    "backend": {
+      "variables": {
+        "DATABASE_URL": {
+          "value": "${{Postgres.DATABASE_URL}}"
+        }
+      }
+    }
+  }
+}
+```
+
+See [12-monorepo.md](12-monorepo.md) for variable reference syntax details.
+
+## Complete Configuration Example
+
+```json
+{
+  "services": {
+    "api": {
+      "build": {
+        "buildCommand": "npm run build",
+        "builder": "NIXPACKS"
+      },
+      "deploy": {
+        "startCommand": "npm start",
+        "healthcheck": {
+          "enabled": true,
+          "path": "/health"
+        },
+        "multiRegionConfig": {
+          "us-west1": {"numReplicas": 2}
+        }
+      },
+      "variables": {
+        "NODE_ENV": {"value": "production"},
+        "DATABASE_URL": {"value": "${{Postgres.DATABASE_URL}}"}
+      },
+      "source": {
+        "watchPatterns": ["/api/**", "/shared/**"]
+      }
+    }
+  }
+}
+```
+
+## Next Steps
+
+- [12-monorepo.md](12-monorepo.md) - Monorepo configuration
+- [08-volumes.md](08-volumes.md) - Persistent storage
+- [07-domains.md](07-domains.md) - Domain configuration