Skip to content

INTEGRATION_GUIDE.md

Latest commit

 

History

History
282 lines (207 loc) · 6.64 KB

INTEGRATION_GUIDE.md

File metadata and controls

282 lines (207 loc) · 6.64 KB
Raw

Cyrus Cloudflare Container Integration Guide

This guide walks through integrating the Cloudflare Container system with your existing Cyrus deployment.

Overview

The containerized architecture provides:

  • Isolated Environments: Each Linear issue gets its own container
  • Scalable Processing: Containers spin up/down based on demand
  • Enhanced Security: Sandboxed execution environments
  • Resource Management: Configurable CPU/memory limits per container

Architecture Flow

graph TD
    A[Linear Issue Assigned] --> B[Container Worker]
    B --> C{Container Exists?}
    C -->|No| D[Create New Container]
    C -->|Yes| E[Use Existing Container]
    D --> F[Clone Repository]
    E --> F
    F --> G[Setup Workspace]
    G --> H[Start Claude Session]
    H --> I[Process Issue]
    I --> J[Post Results to Linear]
    
    K[Issue Closed] --> L[Cleanup Container]
    L --> M[Archive Logs]
Loading

Integration Steps

1. Deploy Container Infrastructure

# Clone the container integration repository
git clone https://github.com/shebashio/cyrus-cloudflare-containers.git
cd cyrus-cloudflare-containers

# Run setup script
./scripts/setup.sh

2. Modify Existing Cyrus Installation

A. Update LinearIssueService

Replace your existing LinearIssueService import with the containerized version:

// Before
const LinearIssueService = require('./services/LinearIssueService');

// After  
const { ContainerizedLinearIssueService } = require('cyrus-cloudflare-containers/src/cyrus-integration');

const containerWorkerUrl = process.env.CONTAINER_WORKER_URL || 'https://cyrus-container-manager.your-subdomain.workers.dev';
const issueService = new ContainerizedLinearIssueService(
  new LinearIssueService(), 
  containerWorkerUrl
);

B. Environment Configuration

Add these environment variables to your Cyrus deployment:

# Container Worker Configuration
CONTAINER_WORKER_URL=https://cyrus-container-manager.your-subdomain.workers.dev
CONTAINER_MODE_ENABLED=true

# Cloudflare Configuration  
CLOUDFLARE_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id

# Existing tokens (now also passed to containers)
ANTHROPIC_API_KEY=your_claude_token
LINEAR_API_TOKEN=your_linear_token

C. Update Issue Handling Logic

Modify your main issue processing loop:

// apps/cli/src/main.js or equivalent
async function processIssueAssignment(issue, assignment) {
  if (process.env.CONTAINER_MODE_ENABLED === 'true') {
    // Use containerized processing
    return await issueService.handleIssueAssigned(issue, assignment);
  } else {
    // Fall back to traditional processing
    return await traditionalIssueService.handleIssueAssigned(issue, assignment);
  }
}

// Handle issue closure for cleanup
async function processIssueClosure(issue) {
  if (process.env.CONTAINER_MODE_ENABLED === 'true') {
    await issueService.handleIssueClosed(issue);
  }
  // Continue with normal closure processing...
}

3. Configure Container Registry

A. Build and Push Container Image

# Build the development container
npm run build

# Tag for your registry  
docker tag cyrus-dev-container:latest your-registry.com/cyrus-dev-container:latest

# Push to registry
docker push your-registry.com/cyrus-dev-container:latest

B. Update wrangler.toml

[container_registry]
image = "your-registry.com/cyrus-dev-container:latest"

[[container_class]]
name = "cyrus-dev-env"
image = "your-registry.com/cyrus-dev-container:latest"
memory = "2GB"
cpu = "1"

4. Deploy and Test

A. Deploy Worker

npm run deploy

B. Test Container Creation

# Test endpoint
curl -X POST https://your-worker-url.workers.dev/container/create \
  -H "Content-Type: application/json" \
  -d '{
    "issueId": "TEST-123",
    "repositoryUrl": "https://github.com/your-org/test-repo.git",
    "linearToken": "your-token",
    "claudeToken": "your-token"
  }'

C. Monitor Container Status

# Check container status
curl "https://your-worker-url.workers.dev/container/status?issueId=TEST-123"

Configuration Options

Container Resources

Adjust container resources in wrangler.toml:

[[container_class]]
name = "cyrus-dev-env"
memory = "4GB"      # Increase for larger codebases
cpu = "2"           # More CPU for intensive operations

Timeout Settings

Configure timeouts for long-running operations:

// In cyrus-integration.js
const sessionConfig = {
  resources: {
    memory: '4GB',
    cpu: '2', 
    timeout: '60m'  // Extend for complex issues
  }
};

Storage Configuration

Set up persistent storage for container data:

# R2 bucket for logs and artifacts
[[r2_buckets]]
binding = "CONTAINER_STORAGE"
bucket_name = "your-cyrus-container-storage"

Monitoring and Debugging

Container Logs

Access container logs through the R2 bucket:

# List container logs
npx wrangler r2 object list cyrus-container-storage --prefix logs/

# Download specific log
npx wrangler r2 object get cyrus-container-storage logs/container-id/session.log

Health Monitoring

The worker provides health endpoints:

  • GET /health - Worker health status
  • GET /container/status?issueId=<id> - Container status
  • POST /container/cleanup - Manual cleanup

Debug Mode

Enable debug logging:

# Set debug environment variable
export CYRUS_DEBUG_CONTAINERS=true

# Worker will log detailed container operations

Troubleshooting

Common Issues

  1. Container Creation Fails

    • Check Cloudflare Workers Paid plan is active
    • Verify container image exists in registry
    • Review worker logs for specific errors

  2. Container Connection Timeouts

    • Increase timeout values in configuration
    • Check container health endpoints
    • Verify network connectivity

  3. Resource Limits Exceeded

    • Monitor container resource usage
    • Adjust memory/CPU limits in wrangler.toml
    • Implement container cleanup strategies

Support

  • Review worker logs: npx wrangler tail
  • Check container status via API endpoints
  • Monitor R2 storage for archived logs
  • Cloudflare Containers Discord community

Migration Strategy

Phased Rollout

  1. Phase 1: Deploy alongside existing system
  2. Phase 2: Enable for test issues only
  3. Phase 3: Gradual rollout to production issues
  4. Phase 4: Full containerized deployment

Rollback Plan

The integration maintains fallback to traditional processing:

// Automatic fallback on container failure
if (containerCreationFails) {
  console.log('Falling back to local processing');
  return await this.linearService.handleIssueAssigned(issue, assignment);
}