GoClaw/PRODUCTION_DEPLOYMENT.md

Production Deployment Guide - GoClaw Control Center

Phase 19: Task Management System + Web Research Workflow

Overview

This deployment includes:

• Task Management System: Automatic task creation and tracking for complex operations
• Web Research Workflow: Browser Agent integration for web searches
• Auto-Task Creation: Orchestrator automatically creates tasks when components are missing
• Task Execution: Agent follows tasks and completes them systematically

Pre-Deployment Checklist

• Research workflow added to orchestrator.ts
• Web research tool integrated into ORCHESTRATOR_TOOLS
• Tasks table schema created in drizzle/schema.ts
• Query helpers implemented in server/db.ts
• tRPC endpoints created in server/routers.ts
• TasksPanel React component created
• Auto-task creation integrated into orchestratorChat
• 120+ tests passing (1 failing due to missing DB table)

Deployment Steps

Step 1: Run Database Migration

# On production server
cd /path/to/goclaw-control-center

# Run migration script
./docker/migrate-production.sh

# Or manually:
docker-compose exec app pnpm db:push

Expected Output:

[Migration] ✓ Tasks table created successfully
[Migration] ✓ Production migration completed successfully!

Step 2: Verify Tasks Table

# Connect to MySQL and verify
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE}

# Run in MySQL:
SHOW TABLES LIKE 'tasks';
DESCRIBE tasks;

Expected Columns:

• id (INT, PRIMARY KEY)
• agentId (INT, FOREIGN KEY)
• conversationId (VARCHAR)
• title (VARCHAR)
• description (TEXT)
• status (ENUM: pending, in_progress, completed, failed, blocked)
• priority (ENUM: low, medium, high, critical)
• createdAt, startedAt, completedAt (TIMESTAMP)
• result, errorMessage (TEXT)
• dependsOn (JSON)
• metadata (JSON)

Step 3: Restart Application

# Restart the app container
docker-compose restart app

# Verify it's running
docker-compose logs app

# Check for errors
docker-compose logs app | grep -i error

Step 4: Verify Web Research Workflow

# Check if research tool is available in orchestrator
curl http://localhost:3000/api/orchestrator/tools

# Expected response includes:
# - "research" tool in ORCHESTRATOR_TOOLS

Step 5: Test Task Creation

1. Open the application UI
2. Navigate to Chat
3. Send a complex task that requires research
4. Verify that:
   • Tasks are automatically created in the right panel
   • Tasks have correct status (pending → in_progress → completed)
   • Research results are displayed

Monitoring

Check Task Creation Logs

# View orchestrator logs
docker-compose logs app | grep -i "orchestrator\|task\|research"

# Monitor real-time
docker-compose logs -f app | grep -i "task\|research"

Database Monitoring

# Count tasks created
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SELECT COUNT(*) as total_tasks FROM tasks;"

# View recent tasks
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SELECT id, agentId, title, status, createdAt FROM tasks ORDER BY createdAt DESC LIMIT 10;"

Troubleshooting

Issue: "Table 'tasks' doesn't exist"

Solution:

# Run migration again
docker-compose exec app pnpm db:push

# Or manually create table
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} < drizzle/migrations/latest.sql

Issue: Research tool not working

Solution:

1. Check if browser-agent is installed:

   docker-compose exec app npm list puppeteer-core
   

2. Check Chromium availability:

   docker-compose exec app which chromium-browser
   

3. Restart the app:

   docker-compose restart app
   

Issue: Tasks not being created

Solution:

1. Check orchestrator logs:

   docker-compose logs app | grep "Auto-created"
   

2. Verify auto-task creation is enabled:

   • Check orchestrator.ts line 594-613
   • Ensure autoCreateTasks() is being called

3. Check database connection:

   docker-compose exec app pnpm test
   

Performance Optimization

Index Optimization

The tasks table includes indexes on:

• agentId - for fast agent task lookup
• status - for filtering pending tasks
• conversationId - for conversation-specific tasks

Query Performance

Monitor slow queries:

docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "SET GLOBAL slow_query_log = 'ON'; SET GLOBAL long_query_time = 2;"

Rollback Procedure

If deployment fails:

# 1. Stop the application
docker-compose stop app

# 2. Rollback migration (if needed)
docker-compose exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DATABASE} \
  -e "DROP TABLE IF EXISTS tasks;"

# 3. Restart with previous version
git checkout previous-version
docker-compose up -d app

# 4. Verify
docker-compose logs app

Post-Deployment Verification

• Tasks table created
• Research tool available
• Auto-task creation working
• Web research workflow functional
• All tests passing on production DB
• No errors in logs

Next Steps

1. Monitor for 24 hours - Watch logs for any issues
2. Test end-to-end - Create complex tasks and verify workflow
3. Collect metrics - Monitor CPU, memory, and query performance
4. Document issues - Create GitHub issues for any problems found
5. Plan Phase 20 - Next features or improvements

Support

For issues or questions:

1. Check logs: docker-compose logs app
2. Review this guide
3. Create an issue in Gitea with:
   • Error message
   • Steps to reproduce
   • Expected vs actual behavior
   • Relevant logs

---

Deployment Date: [Fill in after deployment] Deployed By: [Fill in after deployment] Status: Ready for production