@cleocode/cleo 2026.3.4 → 2026.3.7

package/packages/ct-skills/skills/railway-platform/references/07-domains.md

@@ -1,139 +0,0 @@
-# Domain Management
-
-Add custom domains and configure SSL certificates.
-
-## Railway Domain (Auto-Generated)
-
-### Generate Domain
-
-```bash
-railway domain --json
-```
-
-Creates `*.up.railway.app` domain automatically.
-
-### Service-Specific Domain
-
-```bash
-railway domain --json --service backend
-```
-
-## Custom Domain
-
-### Add Domain
-
-```bash
-railway domain example.com --json
-```
-
-Returns DNS records to configure:
-
-```json
-{
-  "domain": "example.com",
-  "dnsRecords": [
-    {
-      "type": "CNAME",
-      "host": "@",
-      "value": "railway.app"
-    }
-  ]
-}
-```
-
-### Configure DNS
-
-Add the DNS records to your provider:
-
-**CNAME Record:**
-- Type: CNAME
-- Host: @ or subdomain
-- Value: Provided by Railway
-
-### Verify Domain
-
-Domains are verified automatically once DNS propagates (can take up to 24 hours).
-
-### Wildcard Domains
-
-Railway supports wildcard domains:
-
-```bash
-railway domain "*.example.com" --json
-```
-
-## Domain Configuration
-
-### Via Environment Config
-
-```bash
-source _shared/scripts/railway-api.sh
-
-ENV_ID=$(get_environment_id)
-SERVICE_ID=$(get_service_id)
-
-# Add custom domain
-railway_api '
-  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
-    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
-      id
-    }
-  }
-' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"networking\": {\"customDomains\": {\"new-domain\": {\"domain\": \"example.com\"}}}}}}}"
-```
-
-### Remove Domain
-
-```bash
-source _shared/scripts/railway-api.sh
-
-# Remove custom domain
-railway_api '
-  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
-    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
-      id
-    }
-  }
-' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"networking\": {\"customDomains\": {\"domain-id\": null}}}}}}"
-```
-
-## SSL Certificates
-
-SSL certificates are automatically provisioned and renewed for all domains.
-
-No manual configuration required.
-
-## Port Configuration
-
-Custom domains connect to the same port as Railway domains (your service's exposed port).
-
-## Troubleshooting
-
-### Domain Not Verifying
-
-**Check DNS propagation:**
-```bash
-nslookup example.com
-dig example.com
-```
-
-**Check DNS records:**
-Ensure CNAME points exactly to the value Railway provided.
-
-### SSL Certificate Issues
-
-Certificates are auto-provisioned. If issues persist:
-1. Check domain DNS is correct
-2. Wait 24 hours for propagation
-3. Contact Railway support
-
-### Domain Already in Use
-
-If domain is used in another project:
-1. Remove from old project first
-2. Or use different domain/subdomain
-
-## Next Steps
-
-- [09-networking.md](09-networking.md) - Private networking
-- [13-troubleshooting.md](13-troubleshooting.md) - Advanced debugging

package/packages/ct-skills/skills/railway-platform/references/08-volumes.md

@@ -1,533 +0,0 @@
-# Persistent Volumes
-
-Railway volumes provide persistent storage that survives deployments and restarts.
-
-## When to Use Volumes
-
-**Use volumes for:**
-- Database data persistence
-- File uploads and user content
-- Logs that must survive restarts
-- Configuration files that change at runtime
-- Cache directories that should persist
-
-**Don't use volumes for:**
-- Temporary files (use /tmp)
-- Build artifacts
-- Static assets (serve from CDN)
-- Source code
-
-## Volume Types
-
-### Standard Volume
-
-General purpose persistent storage:
-- Mount at any path
-- Survives deployments
-- Tied to service and region
-- Backed up automatically
-
-### High-Availability Volume (Pro+)
-
-Replicated across multiple zones:
-- Higher durability
-- Automatic failover
-- Available on Pro and Enterprise plans
-
-## Creating Volumes
-
-### Via CLI
-
-```bash
-# Create volume
-railway volume add --service my-service
-
-# List volumes
-railway volume list --service my-service
-
-# Delete volume
-railway volume delete <volume-id>
-```
-
-### Via Environment Config
-
-```json
-{
-  "services": {
-    "my-service": {
-      "volumes": {
-        "my-volume": {
-          "mountPath": "/data"
-        }
-      }
-    }
-  }
-}
-```
-
-## Mount Points
-
-### Common Patterns
-
-**Database data:**
-```json
-{
-  "volumes": {
-    "postgres-data": {
-      "mountPath": "/var/lib/postgresql/data"
-    }
-  }
-}
-```
-
-**File uploads:**
-```json
-{
-  "volumes": {
-    "uploads": {
-      "mountPath": "/app/uploads"
-    }
-  }
-}
-```
-
-**Logs:**
-```json
-{
-  "volumes": {
-    "app-logs": {
-      "mountPath": "/app/logs"
-    }
-  }
-}
-```
-
-### Mount Path Requirements
-
-- Must be absolute path (starts with /)
-- Cannot mount over system directories (/bin, /etc, etc.)
-- Service must have permission to write to path
-- Single volume can only mount to one path per service
-
-## Database Volumes
-
-### PostgreSQL with Volume
-
-Railway's Postgres template automatically creates a volume. For custom setup:
-
-```json
-{
-  "services": {
-    "postgres": {
-      "source": {
-        "image": "postgres:15"
-      },
-      "volumes": {
-        "postgres-data": {
-          "mountPath": "/var/lib/postgresql/data"
-        }
-      },
-      "variables": {
-        "POSTGRES_DB": {"value": "mydb"},
-        "POSTGRES_USER": {"value": "user"},
-        "POSTGRES_PASSWORD": {"value": "password", "encrypted": true}
-      }
-    }
-  }
-}
-```
-
-### MongoDB with Volume
-
-```json
-{
-  "services": {
-    "mongo": {
-      "source": {
-        "image": "mongo:7"
-      },
-      "volumes": {
-        "mongo-data": {
-          "mountPath": "/data/db"
-        }
-      }
-    }
-  }
-}
-```
-
-### MySQL with Volume
-
-```json
-{
-  "services": {
-    "mysql": {
-      "source": {
-        "image": "mysql:8"
-      },
-      "volumes": {
-        "mysql-data": {
-          "mountPath": "/var/lib/mysql"
-        }
-      }
-    }
-  }
-}
-```
-
-## Application Volumes
-
-### File Upload Service
-
-```json
-{
-  "services": {
-    "api": {
-      "volumes": {
-        "uploads": {
-          "mountPath": "/app/public/uploads"
-        }
-      },
-      "variables": {
-        "UPLOAD_DIR": {"value": "/app/public/uploads"}
-      }
-    }
-  }
-}
-```
-
-**In your application:**
-```javascript
-// Node.js
-const uploadDir = process.env.UPLOAD_DIR || './uploads';
-
-// Python
-import os
-upload_dir = os.environ.get('UPLOAD_DIR', './uploads')
-```
-
-### Cache Directory
-
-```json
-{
-  "services": {
-    "worker": {
-      "volumes": {
-        "cache": {
-          "mountPath": "/app/cache"
-        }
-      }
-    }
-  }
-}
-```
-
-## Volume Sizing
-
-### Default Sizes
-
-- **Trial/Hobby:** Up to plan limits
-- **Pro:** Configurable up to 100GB
-- **Enterprise:** Custom limits
-
-### Monitor Usage
-
-```bash
-# Check volume usage
-railway metrics --service my-service
-```
-
-**Metrics to watch:**
-- `DISK_USAGE_GB` - Current usage
-- Volume approaching limit warnings
-
-### Resize Volumes
-
-Currently, volumes cannot be resized directly. To increase:
-
-1. Create new larger volume
-2. Copy data to new volume
-3. Update service to use new volume
-4. Delete old volume
-
-## Volume Backup & Restore
-
-### Automatic Backups
-
-Railway automatically backs up volumes:
-- Daily snapshots
-- Kept for 7 days (Pro+)
-- Point-in-time recovery
-
-### Manual Backup
-
-```bash
-# Create snapshot (via API)
-# See railway-api.sh for GraphQL mutations
-```
-
-### Restore from Backup
-
-Contact Railway support for restore assistance or use API:
-
-```bash
-# Restore volume (via API)
-```
-
-## Multi-Region Considerations
-
-### Volume Region Lock
-
-Volumes are tied to a specific region:
-- Created in service's primary region
-- Cannot be mounted across regions
-- Service must deploy to volume's region
-
-### Regional Deployment
-
-```json
-{
-  "services": {
-    "database": {
-      "volumes": {
-        "data": {
-          "mountPath": "/data"
-        }
-      },
-      "deploy": {
-        "multiRegionConfig": {
-          "us-west1": {
-            "numReplicas": 1
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## Railway Metal Volumes
-
-### Stateful Railway Metal
-
-Available March 2025 for Railway Metal regions:
-- NVMe SSD storage
-- Faster I/O performance
-- Available for all plan types
-
-### Migration
-
-Volumes on Railway Metal:
-- Created automatically for new services
-- Existing volumes migrated gradually
-- No action required
-
-**See railway-metal reference for migration details.**
-
-## Best Practices
-
-### 1. Use Descriptive Names
-
-**Good:**
-```json
-{
-  "volumes": {
-    "postgres-production-data": {
-      "mountPath": "/var/lib/postgresql/data"
-    }
-  }
-}
-```
-
-**Bad:**
-```json
-{
-  "volumes": {
-    "vol1": {
-      "mountPath": "/data"
-    }
-  }
-}
-```
-
-### 2. Mount at Standard Paths
-
-Use conventional mount points:
-- `/var/lib/<service>` for databases
-- `/app/data` or `/app/uploads` for applications
-- `/var/log/<app>` for logs
-
-### 3. Separate Concerns
-
-Use multiple volumes for different data:
-```json
-{
-  "volumes": {
-    "uploads": {"mountPath": "/app/uploads"},
-    "logs": {"mountPath": "/app/logs"},
-    "cache": {"mountPath": "/app/cache"}
-  }
-}
-```
-
-### 4. Environment Variables
-
-Expose volume paths via environment variables:
-```json
-{
-  "variables": {
-    "DATA_DIR": {"value": "/app/data"},
-    "LOG_DIR": {"value": "/app/logs"}
-  }
-}
-```
-
-### 5. Handle Missing Volumes Gracefully
-
-**Application code:**
-```javascript
-// Create directory if doesn't exist
-const fs = require('fs');
-const uploadDir = process.env.UPLOAD_DIR;
-if (!fs.existsSync(uploadDir)) {
-  fs.mkdirSync(uploadDir, { recursive: true });
-}
-```
-
-## Troubleshooting
-
-### Volume Not Mounting
-
-**Symptom:** Data not persisting between deploys
-
-**Check:**
-1. Volume created and attached to service
-2. Mount path is correct
-3. Service writing to correct path
-4. Check `railway status --json` for volume info
-
-**Debug:**
-```bash
-# SSH into container
-railway ssh
-
-# Check mount
-ls -la /your/mount/path
-df -h
-
-# Verify writes
- echo "test" > /your/mount/path/test.txt
-```
-
-### Permission Denied
-
-**Symptom:** Cannot write to volume
-
-**Fix:**
-1. Ensure mount path is writable
-2. Check user permissions in container
-3. Use absolute paths
-
-**Dockerfile fix:**
-```dockerfile
-RUN mkdir -p /app/data && chown -R app:app /app/data
-```
-
-### Out of Space
-
-**Symptom:** Write failures, disk full errors
-
-**Solution:**
-1. Check current usage: `railway metrics`
-2. Clean up unnecessary files
-3. Contact support to increase limit (Pro+)
-
-### Cross-Region Issues
-
-**Symptom:** Volume not accessible
-
-**Cause:** Service deployed to different region than volume
-
-**Fix:** Deploy service to volume's region or create new volume in target region.
-
-## Examples
-
-### Complete Database Setup
-
-```json
-{
-  "services": {
-    "postgres": {
-      "source": {
-        "image": "postgres:15-alpine"
-      },
-      "volumes": {
-        "postgres-data": {
-          "mountPath": "/var/lib/postgresql/data"
-        }
-      },
-      "variables": {
-        "POSTGRES_DB": {"value": "appdb"},
-        "POSTGRES_USER": {"value": "appuser"},
-        "POSTGRES_PASSWORD": {"value": "changeme", "encrypted": true},
-        "PGDATA": {"value": "/var/lib/postgresql/data/pgdata"}
-      }
-    }
-  }
-}
-```
-
-### File Storage Service
-
-```json
-{
-  "services": {
-    "file-api": {
-      "volumes": {
-        "uploads": {
-          "mountPath": "/data/uploads"
-        }
-      },
-      "variables": {
-        "STORAGE_PATH": {"value": "/data/uploads"},
-        "MAX_FILE_SIZE": {"value": "10485760"}
-      }
-    }
-  }
-}
-```
-
-**Express.js handler:**
-```javascript
-const express = require('express');
-const multer = require('multer');
-const path = require('path');
-
-const uploadDir = process.env.STORAGE_PATH || './uploads';
-
-const storage = multer.diskStorage({
-  destination: uploadDir,
-  filename: (req, file, cb) => {
-    cb(null, `${Date.now()}-${file.originalname}`);
-  }
-});
-
-const upload = multer({ storage });
-
-app.post('/upload', upload.single('file'), (req, res) => {
-  res.json({ url: `/files/${req.file.filename}` });
-});
-```
-
-## Summary
-
-| Aspect | Details |
-|--------|---------|
-| **Use case** | Persistent data, uploads, databases |
-| **Survives** | Deployments, restarts, service updates |
-| **Tied to** | Service and region |
-| **Backup** | Automatic daily snapshots |
-| **Size** | Up to plan limits |
-| **Regions** | Must match service region |
-
-**Key point:** Volumes persist data across deployments. Use for anything that must survive service restarts.