# WakelAI Instance Creation Timeout - Fixes Applied

## Problem
Instance creation at `wakelai.com/dashboard/instances` was taking too long, showing "Creating environment..." for extended periods.

## Root Causes Identified
1. **Synchronous Docker Operations**: HTTP requests blocked on `docker compose up` with 15-minute timeout
2. **Port Allocation Issues**: In-memory port tracking lost state on PM2 restarts (133+ restarts)
3. **No Background Processing**: No job queue or async handling
4. **Large Docker Image**: 3.97GB Hermes image requiring pull time
5. **Database Schema Issues**: Missing `port` column in wrong database

## Solutions Implemented

### 1. Database-Backed Port Allocation ✅
**File**: `src/lib/port-allocator.ts`
- Replaced in-memory `Set` with database persistence using `AllocatedPort` model
- Added automatic cleanup of stale allocations on startup
- Port reconciliation with Docker state
- PM2 restart safe

**Database Schema**: Added to `prisma/schema.prisma`
```prisma
model AllocatedPort {
  id              Int       @id @default(autoincrement())
  port             Int       @unique
  instanceId       String?   @unique
  instanceSlug     String?
  allocatedAt      DateTime  @default(now())
  releasedAt       DateTime?
}
```

### 2. Asynchronous Instance Creation ✅
**File**: `src/lib/instance-queue.ts`
- Implemented in-memory job queue for instance creation
- HTTP requests return immediately with `jobId`
- Background processing of Docker operations
- Status polling support

**API Changes**:
- POST `/api/instances` now returns `202 Accepted` with `jobId`
- Added GET `/api/instances/[id]/status?jobId=x` for polling

### 3. Optimized Docker Operations ✅
**File**: `src/lib/dokploy.ts`
- Reduced timeout from 15 minutes to 5 minutes
- Better error handling

### 4. Docker Image Pre-Pulling ✅
**File**: `src/lib/docker-utils.ts`
- Background pre-pull of Hermes image on startup
- Docker health checks
- Reduced first-time instance creation time

### 5. Startup Initialization ✅
**Files**: `src/lib/startup.ts`, `src/app/layout.tsx`
- Port allocator initialization with cleanup
- Docker image pre-pull
- Docker health verification

## API Usage Changes

### Before (Synchronous):
```typescript
// Response would take 2-5+ minutes
POST /api/instances
{
  "name": "my-instance"
}
→ 200 OK with instance and credentials (after waiting)
```

### After (Asynchronous):
```typescript
// Returns immediately
POST /api/instances
{
  "name": "my-instance"
}
→ 202 Accepted
{
  "instance": {...},
  "jobId": "job_abc123_timestamp",
  "message": "Instance creation started..."
}

// Poll for status
GET /api/instances/[id]/status?jobId=job_abc123_timestamp
→ {
  "status": "pending" | "completed" | "failed",
  "instance": {...},
  "credentials": {...} // when completed
}
```

## Testing Recommendations
1. Test instance creation with the new async flow
2. Verify port allocation persistence across PM2 restarts
3. Check status polling endpoint functionality
4. Monitor Docker image pre-pulling on startup
5. Verify stale port cleanup works correctly

## Frontend Updates Needed
The frontend should be updated to:
1. Handle `202 Accepted` response with `jobId`
2. Poll the status endpoint instead of waiting for synchronous response
3. Show progress indicator during "pending" state
4. Handle success/error states appropriately

## Files Modified
- `prisma/schema.prisma` - Added AllocatedPort model
- `src/lib/port-allocator.ts` - Database-backed implementation
- `src/lib/instance-queue.ts` - New job queue system
- `src/lib/docker-utils.ts` - New Docker utilities
- `src/lib/startup.ts` - New startup initialization
- `src/lib/dokploy.ts` - Timeout optimization
- `src/app/layout.tsx` - Added startup initialization
- `src/app/api/instances/route.ts` - Async queue integration
- `src/app/api/instances/[id]/status/route.ts` - New status endpoint

## Performance Improvements Expected
- **Immediate Response**: HTTP returns in <100ms instead of 2-5+ minutes
- **Better UX**: Users see progress via polling instead of hanging spinner
- **Reliability**: Port allocation survives PM2 restarts
- **Cleanup**: Stale ports automatically cleaned on startup
- **Pre-pulled Images**: Faster instance creation after startup

## Deployment Notes
- Database migration applied with `prisma db push`
- Application rebuilt and restarted via PM2
- No Redis required (in-memory queue for simplicity)