moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-railway/modules/docker-deployment.md

@@ -0,0 +1,261 @@
+# Docker Deployment Module
+
+Purpose: Container build patterns with multi-stage Dockerfiles for Node.js, Python, Go, and Rust applications on Railway.
+
+---
+
+## Build Strategy Selection
+
+Docker Build Use Cases:
+- Custom system dependencies required
+- Multi-stage builds for optimization
+- Specific base images needed
+- Binary compilation (Go, Rust)
+- Complex build processes
+
+Railpack Build Use Cases:
+- Standard runtimes without customization
+- Zero-config deployments
+- Simple web applications
+- Quick iteration during development
+
+---
+
+## Multi-Stage Build Patterns
+
+### Node.js Production Dockerfile
+
+```dockerfile
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+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=deps /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+Key Optimization Points:
+- Separate dependency and build stages for caching
+- Production-only dependencies in final image
+- Non-root user for security
+- Alpine base for minimal image size
+
+### Python Production 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"]
+```
+
+Poetry Alternatives:
+- pip with requirements.txt: pip install -r requirements.txt
+- uv package manager: pip install uv && uv pip install -r requirements.txt
+- pdm: pip install pdm && pdm install --prod
+
+### Go Production Dockerfile
+
+```dockerfile
+FROM golang:1.23-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o main .
+
+FROM alpine:latest AS runner
+RUN apk --no-cache add ca-certificates && adduser -D appuser
+WORKDIR /app
+COPY --from=builder /app/main .
+USER appuser
+EXPOSE 8080
+CMD ["./main"]
+```
+
+Build Flag Explanations:
+- CGO_ENABLED=0: Static binary without C dependencies
+- GOOS=linux: Target Linux regardless of build host
+- ldflags="-w -s": Strip debug info for smaller binary
+
+### Rust Production Dockerfile
+
+```dockerfile
+FROM rust:1.77-slim AS builder
+WORKDIR /app
+RUN apt-get update && apt-get install -y pkg-config libssl-dev
+COPY Cargo.toml Cargo.lock ./
+RUN mkdir src && echo "fn main() {}" > src/main.rs
+RUN cargo build --release
+RUN rm -rf src
+COPY . .
+RUN touch src/main.rs && cargo build --release
+
+FROM debian:bookworm-slim AS runner
+RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN useradd --create-home appuser
+WORKDIR /app
+COPY --from=builder /app/target/release/app .
+USER appuser
+EXPOSE 8080
+CMD ["./app"]
+```
+
+Cargo Build Optimization:
+- Dummy main.rs trick caches dependencies
+- Release build for production performance
+- Minimal runtime image with only binary
+
+---
+
+## Railway Configuration for Docker
+
+railway.toml with Docker Builder:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+watchPatterns = ["src/**", "Cargo.toml", "Cargo.lock"]
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 60
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 5
+numReplicas = 2
+
+[deploy.resources]
+memory = "512Mi"
+cpu = "0.5"
+```
+
+Configuration Options:
+- dockerfilePath: Custom Dockerfile location (default: ./Dockerfile)
+- watchPatterns: Files triggering rebuild on change
+- healthcheckPath: Endpoint for container health verification
+- restartPolicyType: ON_FAILURE, ALWAYS, or NEVER
+
+---
+
+## Railpack Migration
+
+Note: Nixpacks is deprecated and in maintenance mode. New projects should use Railpack.
+
+Migrating from Nixpacks to Railpack:
+```toml
+[build]
+builder = "RAILPACK"
+buildCommand = "npm run build"
+
+[deploy]
+startCommand = "npm start"
+```
+
+Railpack Benefits:
+- Faster build times
+- Better caching
+- Automatic detection of frameworks
+- Continued maintenance and updates
+
+---
+
+## Image Size Optimization
+
+Size Reduction Techniques:
+- Use Alpine or slim base images
+- Multi-stage builds to exclude build tools
+- Clean package manager caches
+- Remove unnecessary files in .dockerignore
+
+.dockerignore Example:
+```
+node_modules
+.git
+.gitignore
+README.md
+Dockerfile
+docker-compose*.yml
+.env*
+*.log
+.coverage
+__pycache__
+*.pyc
+target
+```
+
+Image Size Comparison (typical):
+- Node.js (node:20): ~1GB
+- Node.js (node:20-alpine): ~150MB
+- Python (python:3.12): ~1GB
+- Python (python:3.12-slim): ~150MB
+- Go (scratch + binary): ~10-20MB
+- Rust (debian-slim + binary): ~80-100MB
+
+---
+
+## Health Check Implementation
+
+Application Health Endpoint:
+```typescript
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    service: process.env.RAILWAY_SERVICE_NAME,
+    version: process.env.RAILWAY_GIT_COMMIT_SHA?.slice(0, 7)
+  })
+})
+```
+
+Database Connection Check:
+```typescript
+app.get('/health', async (req, res) => {
+  try {
+    await db.query('SELECT 1')
+    res.json({ status: 'healthy', database: 'connected' })
+  } catch (error) {
+    res.status(503).json({ status: 'unhealthy', database: 'disconnected' })
+  }
+})
+```
+
+---
+
+## Works Well With
+
+- modules/multi-service.md: Multi-service architecture patterns
+- modules/volumes-storage.md: Persistent volume configuration
+- moai-lang-python: Python deployment patterns
+- moai-lang-typescript: TypeScript deployment patterns
+- moai-lang-go: Go deployment patterns
+- moai-lang-rust: Rust deployment patterns
+
+---
+
+Version: 1.0.0 | Updated: 2025-12-30

moai_adk/templates/.claude/skills/moai-platform-railway/modules/multi-service.md

@@ -0,0 +1,291 @@
+# Multi-Service Architecture Module
+
+Purpose: Patterns for deploying multi-service applications with monorepo support, service communication, and orchestration on Railway.
+
+---
+
+## Monorepo Structure
+
+Recommended Directory Layout:
+```
+project/
+├── apps/
+│   ├── api/
+│   │   ├── Dockerfile
+│   │   ├── railway.toml
+│   │   └── src/
+│   ├── worker/
+│   │   ├── Dockerfile
+│   │   ├── railway.toml
+│   │   └── src/
+│   ├── scheduler/
+│   │   ├── Dockerfile
+│   │   ├── railway.toml
+│   │   └── src/
+│   └── web/
+│       ├── Dockerfile
+│       ├── railway.toml
+│       └── src/
+├── packages/
+│   ├── shared/
+│   └── database/
+├── package.json
+└── turbo.json
+```
+
+Each service requires its own railway.toml in its directory for independent deployment configuration.
+
+---
+
+## Service Configuration Patterns
+
+### API Service
+
+apps/api/railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+startCommand = "node dist/main.js"
+healthcheckPath = "/health"
+healthcheckTimeout = 60
+numReplicas = 3
+
+[deploy.resources]
+memory = "1Gi"
+cpu = "1"
+```
+
+### Worker Service
+
+apps/worker/railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+startCommand = "node dist/worker.js"
+numReplicas = 2
+
+[deploy.resources]
+memory = "512Mi"
+cpu = "0.5"
+```
+
+Worker services typically do not need health checks or public endpoints.
+
+### Scheduler Service
+
+apps/scheduler/railway.toml:
+```toml
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "./Dockerfile"
+
+[deploy]
+startCommand = "node dist/scheduler.js"
+cronSchedule = "*/5 * * * *"
+numReplicas = 1
+```
+
+Cron Schedule Format: minute hour day month weekday
+- */5 * * * *: Every 5 minutes
+- 0 * * * *: Every hour
+- 0 0 * * *: Daily at midnight
+- 0 0 * * 0: Weekly on Sunday
+
+---
+
+## Service Communication
+
+### Variable References
+
+Railway provides variable reference syntax for cross-service communication:
+- Format: ${{ServiceName.VARIABLE_NAME}}
+- Example: ${{api.DATABASE_URL}}
+
+Setting Variable References:
+1. Go to service settings in Railway dashboard
+2. Add environment variable
+3. Use reference syntax for dynamic values
+
+Common Reference Patterns:
+- Database URL: ${{Postgres.DATABASE_URL}}
+- Redis URL: ${{Redis.REDIS_URL}}
+- API Internal URL: ${{api.RAILWAY_PRIVATE_DOMAIN}}
+
+### Private Networking
+
+Internal Communication Pattern:
+```typescript
+const getInternalUrl = (service: string, port = 3000): string => {
+  const domain = process.env[`${service.toUpperCase()}_RAILWAY_PRIVATE_DOMAIN`]
+  return domain ? `http://${domain}:${port}` : `http://localhost:${port}`
+}
+
+// Usage
+const apiUrl = getInternalUrl('api', 3000)
+const workerUrl = getInternalUrl('worker', 3001)
+```
+
+Service Discovery Environment Variables:
+- RAILWAY_PRIVATE_DOMAIN: Internal hostname for this service
+- {SERVICE}_RAILWAY_PRIVATE_DOMAIN: Internal hostname for other services
+
+### Internal API Calls
+
+```typescript
+import axios from 'axios'
+
+class ServiceClient {
+  private baseUrl: string
+
+  constructor(serviceName: string, port: number = 3000) {
+    const domain = process.env[`${serviceName.toUpperCase()}_RAILWAY_PRIVATE_DOMAIN`]
+    this.baseUrl = domain ? `http://${domain}:${port}` : `http://localhost:${port}`
+  }
+
+  async get<T>(path: string): Promise<T> {
+    const response = await axios.get(`${this.baseUrl}${path}`)
+    return response.data
+  }
+
+  async post<T>(path: string, data: any): Promise<T> {
+    const response = await axios.post(`${this.baseUrl}${path}`, data)
+    return response.data
+  }
+}
+
+// Usage
+const apiClient = new ServiceClient('api', 3000)
+const users = await apiClient.get('/users')
+```
+
+---
+
+## Message Queue Patterns
+
+### Redis-Based Queue
+
+Worker Implementation:
+```typescript
+import { Queue, Worker } from 'bullmq'
+import Redis from 'ioredis'
+
+const connection = new Redis(process.env.REDIS_URL)
+
+const emailQueue = new Queue('emails', { connection })
+
+// Producer (API service)
+await emailQueue.add('welcome', { userId: 123, email: 'user@example.com' })
+
+// Consumer (Worker service)
+const worker = new Worker('emails', async (job) => {
+  if (job.name === 'welcome') {
+    await sendWelcomeEmail(job.data.email)
+  }
+}, { connection })
+```
+
+### Event-Based Communication
+
+Pub/Sub Pattern:
+```typescript
+import Redis from 'ioredis'
+
+const publisher = new Redis(process.env.REDIS_URL)
+const subscriber = new Redis(process.env.REDIS_URL)
+
+// Publisher (any service)
+await publisher.publish('user:created', JSON.stringify({ userId: 123 }))
+
+// Subscriber (worker service)
+subscriber.subscribe('user:created')
+subscriber.on('message', (channel, message) => {
+  const data = JSON.parse(message)
+  console.log(`User created: ${data.userId}`)
+})
+```
+
+---
+
+## Database Sharing
+
+Shared Database Access:
+```typescript
+// packages/database/index.ts
+import { Pool } from 'pg'
+
+export const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000
+})
+
+export const query = (text: string, params?: any[]) => pool.query(text, params)
+```
+
+Service-Specific Migrations:
+- API service owns schema migrations
+- Worker and scheduler services use read-only access where possible
+- Use database roles for access control
+
+---
+
+## Deployment Ordering
+
+Service Dependency Order:
+1. Database and cache services (PostgreSQL, Redis)
+2. Shared infrastructure services
+3. Core API services
+4. Worker and background services
+5. Frontend and edge services
+
+Railway automatically handles dependency ordering when using variable references.
+
+---
+
+## Health Monitoring
+
+Service Health Endpoint:
+```typescript
+app.get('/health', (req, res) => {
+  res.json({
+    status: 'healthy',
+    service: process.env.RAILWAY_SERVICE_NAME,
+    replica: process.env.RAILWAY_REPLICA_ID,
+    timestamp: new Date().toISOString()
+  })
+})
+```
+
+Dependency Health Check:
+```typescript
+app.get('/health/ready', async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    api: await checkApiService()
+  }
+
+  const allHealthy = Object.values(checks).every(v => v)
+  res.status(allHealthy ? 200 : 503).json({ status: allHealthy ? 'ready' : 'not_ready', checks })
+})
+```
+
+---
+
+## Works Well With
+
+- modules/docker-deployment.md: Container build patterns
+- modules/networking-domains.md: Private networking configuration
+- modules/volumes-storage.md: Shared storage patterns
+- moai-domain-backend: Backend architecture patterns
+
+---
+
+Version: 1.0.0 | Updated: 2025-12-30