Eloquent

Documentation

Production Deployment

This guide covers deploying Eloquent services and applications to production using GitHub releases and CI/CD workflows.

Deployment Overview

Code Change → GitHub PR → Merge → Create Release → CI/CD → Kubernetes

Release Process

1. Create a Release

For backend services:

# Tag format: service-name-v1.2.3
git tag agents-v1.2.3
git push origin agents-v1.2.3

# Or create release via GitHub UI
gh release create agents-v1.2.3 \
  --title "Agents Service v1.2.3" \
  --notes "- Added new tool execution\n- Fixed memory leak"

For frontend apps:

# Tag format: app-name-v1.2.3
git tag eloquent-app-v1.2.3
git push origin eloquent-app-v1.2.3

2. CI/CD Workflow

The release triggers GitHub Actions:

# .github/workflows/release.yml
name: Release

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Extract service name and version
        run: |
          TAG=${GITHUB_REF#refs/tags/}
          SERVICE=$(echo $TAG | sed 's/-v[0-9].*//')
          VERSION=$(echo $TAG | sed 's/.*-v//')
          echo "SERVICE=$SERVICE" >> $GITHUB_ENV
          echo "VERSION=$VERSION" >> $GITHUB_ENV

      - name: Build and push Docker image
        run: |
          docker build -t ghcr.io/org/eloquent/$SERVICE:$VERSION ./services/$SERVICE
          docker push ghcr.io/org/eloquent/$SERVICE:$VERSION

      - name: Deploy to Kubernetes
        run: |
          helm upgrade --install $SERVICE ./deploy/helm/$SERVICE \
            --set image.tag=$VERSION \
            --namespace eloquent

Service Deployment

Helm Chart Structure

deploy/helm/agents/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   └── ingress.yaml
└── values-prod.yaml

values.yaml

replicaCount: 2

image:
  repository: ghcr.io/org/eloquent/agents
  tag: latest
  pullPolicy: Always

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

env:
  - name: NATS_URL
    value: nats://nats:4222
  - name: REDIS_URL
    valueFrom:
      secretKeyRef:
        name: redis-credentials
        key: url

Frontend Deployment

Vercel/Cloudflare

# vercel.json
{
  "buildCommand": "pnpm build",
  "outputDirectory": ".next",
  "framework": "nextjs",
  "regions": ["iad1"]
}

Environment Variables

# Production environment
NEXT_PUBLIC_API_GATEWAY_URL=https://api.eloquent.ai
API_GATEWAY_URL=http://api-gateway-service:8080
JWT_SECRET=<production-secret>

Monitoring Deployments

Check Rollout Status

kubectl rollout status deployment/agents -n eloquent

View Logs

kubectl logs -l app=agents -n eloquent --tail=100 -f

Rollback

# Rollback to previous version
kubectl rollout undo deployment/agents -n eloquent

# Rollback to specific revision
kubectl rollout undo deployment/agents --to-revision=3 -n eloquent

Release Checklist

Before creating a release:

  1. Run tests: make test
  2. Check types: make generate && make type-check
  3. Update changelog: Document changes
  4. Verify locally: Test with Docker
  5. Create PR: Get review approval
  6. Merge to main: Squash and merge
  7. Create release: Tag and publish

Canary Deployments

Progressive Rollout

# deployment.yaml
spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0

Traffic Splitting (Istio)

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
spec:
  http:
  - route:
    - destination:
        host: agents
        subset: stable
      weight: 90
    - destination:
        host: agents
        subset: canary
      weight: 10

Best Practices

  1. Semantic versioning - Use MAJOR.MINOR.PATCH
  2. Small, frequent releases - Easier to debug
  3. Feature flags - Control feature rollout
  4. Automated rollback - On health check failures
  5. Monitor after deploy - Watch error rates

Next Steps