moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-railway/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: "moai-platform-railway"
+description: "Railway container deployment specialist covering Docker, multi-service architectures, persistent volumes, and auto-scaling. Use when deploying containerized full-stack applications, configuring multi-region deployments, or setting up persistent storage."
+version: 2.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['railway', 'docker', 'containers', 'multi-service', 'auto-scaling']
+context7-libraries: ['/railwayapp/railway']
+related-skills: ['moai-platform-vercel', 'moai-domain-backend']
+updated: 2026-01-11
+status: "active"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# moai-platform-railway: Container Deployment Specialist
+
+## Quick Reference
+
+Railway Platform Core: Container-first deployment platform with Docker and Railpack builds, multi-service architectures, persistent volumes, private networking, and auto-scaling capabilities.
+
+### Railway Optimal Use Cases
+
+Container Workloads:
+
+- Full-stack containerized applications with custom runtimes
+- Multi-service architectures with inter-service communication
+- Backend services requiring persistent connections such as WebSocket and gRPC
+- Database-backed applications with managed PostgreSQL, MySQL, and Redis
+
+Infrastructure Requirements:
+
+- Persistent volume storage for stateful workloads
+- Private networking for secure service mesh
+- Multi-region deployment for global availability
+- Auto-scaling based on CPU, memory, or request metrics
+
+### Build Strategy Selection
+
+Docker Build is optimal for custom system dependencies, multi-stage builds, and specific base images.
+
+Railpack Build is optimal for standard runtimes including Node.js, Python, and Go, providing zero-config and faster builds.
+
+Note: Nixpacks is deprecated. New services default to Railpack.
+
+### Key CLI Commands
+
+Railway CLI workflow begins with railway login, railway init, and railway link commands. Use railway up to deploy the current directory. Use railway up with the detach flag to deploy without waiting for logs. Use railway variables with the set flag to configure environment variables. Use railway logs with the service flag to view service logs. Use railway rollback with the previous flag to revert to the previous deployment.
+
+---
+
+## Module Index
+
+### Docker Deployment
+
+Module at modules/docker-deployment.md covers multi-stage Dockerfiles for Node.js, Python, Go, and Rust. Includes build optimization, image size reduction, health checks, and Railpack migration.
+
+### Multi-Service Architecture
+
+Module at modules/multi-service.md covers monorepo deployments, service communication, variable references, private networking, and message queue patterns.
+
+### Volumes and Storage
+
+Module at modules/volumes-storage.md covers persistent volume configuration, file storage service, SQLite on volumes, and backup/restore patterns.
+
+### Networking and Domains
+
+Module at modules/networking-domains.md covers private networking, custom domains with SSL, multi-region deployment, auto-scaling, and WebSocket support.
+
+---
+
+## Implementation Guide
+
+### Phase 1: Project Setup
+
+Begin with railway login, railway init, and railway link commands to authenticate, initialize, and link to a project.
+
+The railway.toml configuration file specifies build settings with builder set to DOCKERFILE and dockerfilePath pointing to the Dockerfile. Deploy settings include healthcheckPath for the health endpoint, healthcheckTimeout in seconds, restartPolicyType for restart behavior, and numReplicas for instance count. Resource settings under deploy.resources specify memory allocation and CPU limits.
+
+### Phase 2: Container Configuration
+
+For a quick start Node.js Dockerfile, the builder stage uses node:20-alpine as base, sets WORKDIR to /app, copies package files, runs npm ci, copies source files, and runs npm run build.
+
+The runner stage also uses node:20-alpine, sets WORKDIR to /app, sets NODE_ENV to production, creates a nodejs group and appuser user with specific IDs, copies node_modules and dist from the builder stage, switches to appuser, exposes port 3000, and runs the node command with dist/main.js.
+
+For detailed patterns, see modules/docker-deployment.md.
+
+### Phase 3: Multi-Service Setup
+
+Service Variable References use the double curly brace syntax with dollar sign prefix. Reference Postgres.DATABASE_URL for database connections, Redis.REDIS_URL for Redis connections, and api.RAILWAY_PRIVATE_DOMAIN for internal service communication.
+
+For Private Networking, create a getInternalUrl helper function that takes a service name and optional port defaulting to 3000. The function retrieves the RAILWAY_PRIVATE_DOMAIN environment variable for the service name in uppercase, returning the internal URL with http protocol and port, or localhost fallback.
+
+For detailed patterns, see modules/multi-service.md.
+
+### Phase 4: Storage and Scaling
+
+Volume Configuration in railway.toml uses a volumes array section specifying mountPath for the directory path, name for the volume identifier, and size for the storage allocation.
+
+Auto-Scaling Configuration in deploy.scaling section specifies minReplicas, maxReplicas, and targetCPUUtilization percentage.
+
+Multi-Region Configuration uses deploy.regions array with entries containing name for the region identifier and replicas for the instance count per region.
+
+---
+
+## CI/CD Integration
+
+For GitHub Actions integration, create a workflow file named Railway Deploy with trigger on push to main branch. The deploy job runs on ubuntu-latest, checks out code, installs Railway CLI globally using npm, and runs railway up with detach flag using the RAILWAY_TOKEN secret from GitHub secrets.
+
+---
+
+## Context7 Documentation Access
+
+Step 1: Use mcp__context7__resolve-library-id with "railway" to get the library ID.
+
+Step 2: Use mcp__context7__get-library-docs with the resolved ID and specific topic.
+
+---
+
+## Works Well With
+
+- moai-platform-vercel for edge deployment for frontend
+- moai-domain-backend for backend architecture patterns
+- moai-lang-python for Python FastAPI deployment
+- moai-lang-typescript for TypeScript Node.js patterns
+- moai-lang-go for Go service deployment
+
+---
+
+## Additional Resources
+
+- reference.md provides extended documentation and configuration
+- examples.md provides working code examples for common scenarios
+
+---
+
+Status: Production Ready
+Version: 2.1.0
+Updated: 2026-01-11

moai_adk/templates/.claude/skills/moai-platform-railway/examples.md

@@ -0,0 +1,539 @@
+# Railway Deployment Examples
+
+Working code examples for common Railway deployment scenarios.
+
+---
+
+## Example 1: Full-Stack Node.js Application
+
+### Project Structure
+
+```
+project/
+├── apps/
+│   ├── api/
+│   │   ├── Dockerfile
+│   │   ├── railway.toml
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   └── web/
+│       ├── Dockerfile
+│       ├── railway.toml
+│       └── src/
+├── package.json
+└── turbo.json
+```
+
+### API Service
+
+apps/api/Dockerfile:
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 appuser
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+apps/api/railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 60
+numReplicas = 2
+
+[deploy.resources]
+memory = "512Mi"
+cpu = "0.5"
+```
+
+apps/api/src/index.ts:
+```typescript
+import express from 'express'
+import { Pool } from 'pg'
+
+const app = express()
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+
+app.use(express.json())
+
+app.get('/health', async (req, res) => {
+  try {
+    await pool.query('SELECT 1')
+    res.json({ status: 'healthy', database: 'connected' })
+  } catch (error) {
+    res.status(503).json({ status: 'unhealthy', database: 'disconnected' })
+  }
+})
+
+app.get('/api/users', async (req, res) => {
+  const result = await pool.query('SELECT id, name, email FROM users')
+  res.json(result.rows)
+})
+
+const port = process.env.PORT || 3000
+app.listen(port, '0.0.0.0', () => {
+  console.log(`API server running on port ${port}`)
+})
+```
+
+---
+
+## Example 2: Python FastAPI with Worker
+
+### API Service
+
+apps/api/Dockerfile:
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir poetry
+COPY pyproject.toml poetry.lock ./
+RUN poetry config virtualenvs.create false && poetry install --no-dev
+
+FROM python:3.12-slim AS runner
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY . .
+RUN useradd --create-home appuser
+USER appuser
+EXPOSE 8000
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+apps/api/main.py:
+```python
+from fastapi import FastAPI, BackgroundTasks
+from redis import Redis
+import json
+import os
+
+app = FastAPI()
+redis = Redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"))
+
+@app.get("/health")
+async def health():
+    try:
+        redis.ping()
+        return {"status": "healthy", "redis": "connected"}
+    except Exception:
+        return {"status": "unhealthy", "redis": "disconnected"}
+
+@app.post("/api/jobs")
+async def create_job(data: dict):
+    job_id = str(uuid.uuid4())
+    redis.lpush("job_queue", json.dumps({"id": job_id, "data": data}))
+    return {"job_id": job_id, "status": "queued"}
+```
+
+### Worker Service
+
+apps/worker/main.py:
+```python
+import json
+import time
+import os
+from redis import Redis
+
+redis = Redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379"))
+
+def process_job(job_data: dict):
+    print(f"Processing job: {job_data['id']}")
+    # Simulate work
+    time.sleep(2)
+    print(f"Completed job: {job_data['id']}")
+
+def main():
+    print("Worker started, waiting for jobs...")
+    while True:
+        _, message = redis.brpop("job_queue")
+        job = json.loads(message)
+        process_job(job)
+
+if __name__ == "__main__":
+    main()
+```
+
+apps/worker/railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+startCommand = "python main.py"
+numReplicas = 2
+
+[deploy.resources]
+memory = "256Mi"
+cpu = "0.25"
+```
+
+---
+
+## Example 3: Go Microservice with Volumes
+
+### Main Application
+
+main.go:
+```go
+package main
+
+import (
+    "encoding/json"
+    "log"
+    "net/http"
+    "os"
+    "path/filepath"
+)
+
+type FileStorage struct {
+    basePath string
+}
+
+func NewFileStorage() *FileStorage {
+    path := os.Getenv("RAILWAY_VOLUME_MOUNT_PATH")
+    if path == "" {
+        path = "/app/data"
+    }
+    os.MkdirAll(path, 0755)
+    return &FileStorage{basePath: path}
+}
+
+func (fs *FileStorage) Save(name string, data []byte) error {
+    return os.WriteFile(filepath.Join(fs.basePath, name), data, 0644)
+}
+
+func (fs *FileStorage) Load(name string) ([]byte, error) {
+    return os.ReadFile(filepath.Join(fs.basePath, name))
+}
+
+func main() {
+    storage := NewFileStorage()
+    
+    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+        json.NewEncoder(w).Encode(map[string]string{"status": "healthy"})
+    })
+    
+    http.HandleFunc("/files", func(w http.ResponseWriter, r *http.Request) {
+        if r.Method == "POST" {
+            var data struct {
+                Name    string `json:"name"`
+                Content string `json:"content"`
+            }
+            json.NewDecoder(r.Body).Decode(&data)
+            storage.Save(data.Name, []byte(data.Content))
+            json.NewEncoder(w).Encode(map[string]string{"status": "saved"})
+        }
+    })
+    
+    port := os.Getenv("PORT")
+    if port == "" {
+        port = "8080"
+    }
+    log.Printf("Server starting on port %s", port)
+    log.Fatal(http.ListenAndServe(":"+port, nil))
+}
+```
+
+railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 30
+numReplicas = 1  # Required for volumes
+
+[[volumes]]
+mountPath = "/app/data"
+name = "file-storage"
+size = "10Gi"
+
+[deploy.resources]
+memory = "256Mi"
+cpu = "0.25"
+```
+
+---
+
+## Example 4: Scheduled Backup Service
+
+### Backup Script
+
+backup.ts:
+```typescript
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { createReadStream } from 'fs'
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
+
+const execAsync = promisify(exec)
+
+const s3 = new S3Client({
+  region: process.env.AWS_REGION!,
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
+  }
+})
+
+async function backupDatabase(): Promise<void> {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backupFile = `/tmp/backup-${timestamp}.sql.gz`
+  
+  // Create PostgreSQL dump
+  await execAsync(
+    `pg_dump "${process.env.DATABASE_URL}" | gzip > ${backupFile}`
+  )
+  
+  // Upload to S3
+  await s3.send(new PutObjectCommand({
+    Bucket: process.env.BACKUP_BUCKET!,
+    Key: `database-backups/backup-${timestamp}.sql.gz`,
+    Body: createReadStream(backupFile)
+  }))
+  
+  // Cleanup
+  await execAsync(`rm ${backupFile}`)
+  
+  console.log(`Backup completed: backup-${timestamp}.sql.gz`)
+}
+
+backupDatabase().catch(console.error)
+```
+
+railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+startCommand = "npx ts-node backup.ts"
+cronSchedule = "0 0 * * *"  # Daily at midnight
+numReplicas = 1
+
+[deploy.resources]
+memory = "256Mi"
+cpu = "0.25"
+```
+
+---
+
+## Example 5: Multi-Region API with Read Replicas
+
+### Connection Manager
+
+db.ts:
+```typescript
+import { Pool } from 'pg'
+
+const primaryPool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10,
+  idleTimeoutMillis: 30000
+})
+
+const replicaPool = new Pool({
+  connectionString: process.env.DATABASE_REPLICA_URL || process.env.DATABASE_URL,
+  max: 20,
+  idleTimeoutMillis: 30000
+})
+
+export async function query(
+  sql: string,
+  params?: any[],
+  options: { forceWrite?: boolean } = {}
+): Promise<any> {
+  const isWrite = !sql.trim().toLowerCase().startsWith('select')
+  const pool = (isWrite || options.forceWrite) ? primaryPool : replicaPool
+  
+  const result = await pool.query(sql, params)
+  return result.rows
+}
+
+export async function transaction<T>(
+  callback: (query: (sql: string, params?: any[]) => Promise<any>) => Promise<T>
+): Promise<T> {
+  const client = await primaryPool.connect()
+  try {
+    await client.query('BEGIN')
+    const result = await callback((sql, params) => client.query(sql, params).then(r => r.rows))
+    await client.query('COMMIT')
+    return result
+  } catch (error) {
+    await client.query('ROLLBACK')
+    throw error
+  } finally {
+    client.release()
+  }
+}
+```
+
+railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 60
+
+[[deploy.regions]]
+name = "us-west1"
+replicas = 3
+
+[[deploy.regions]]
+name = "europe-west4"
+replicas = 2
+
+[deploy.scaling]
+minReplicas = 2
+maxReplicas = 10
+targetRequestsPerSecond = 100
+
+[deploy.resources]
+memory = "1Gi"
+cpu = "1"
+```
+
+---
+
+## Example 6: WebSocket Service
+
+### WebSocket Server
+
+websocket.ts:
+```typescript
+import { WebSocketServer } from 'ws'
+import { createServer } from 'http'
+import express from 'express'
+
+const app = express()
+const server = createServer(app)
+const wss = new WebSocketServer({ server })
+
+const clients = new Set<WebSocket>()
+
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'healthy',
+    clients: clients.size,
+    replica: process.env.RAILWAY_REPLICA_ID
+  })
+})
+
+wss.on('connection', (ws, req) => {
+  clients.add(ws)
+  console.log(`Client connected. Total: ${clients.size}`)
+  
+  ws.on('message', (message) => {
+    // Broadcast to all clients
+    const data = message.toString()
+    clients.forEach(client => {
+      if (client !== ws && client.readyState === 1) {
+        client.send(data)
+      }
+    })
+  })
+  
+  ws.on('close', () => {
+    clients.delete(ws)
+    console.log(`Client disconnected. Total: ${clients.size}`)
+  })
+  
+  ws.on('error', console.error)
+})
+
+const port = process.env.PORT || 3000
+server.listen(port, '0.0.0.0', () => {
+  console.log(`WebSocket server running on port ${port}`)
+})
+```
+
+railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 30
+numReplicas = 3
+
+[deploy.resources]
+memory = "512Mi"
+cpu = "0.5"
+```
+
+---
+
+## GitHub Actions Workflow
+
+Complete CI/CD pipeline:
+
+```yaml
+name: Railway Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm test
+      - run: npm run lint
+
+  deploy:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Railway CLI
+        run: npm i -g @railway/cli
+      - name: Deploy to Railway
+        run: railway up --detach
+      - name: Verify Deployment
+        run: |
+          sleep 30
+          railway status
+```
+
+---
+
+Status: Production Ready | Updated: 2025-12-30