managing-apps/docs/TASK_ENVIRONMENTS_SETUP.md

# Task Environments Setup with Docker Compose

This document explains how to use Docker Compose to create isolated test environments for each development task.

## Overview

Each task gets its own isolated Docker Compose environment with:
- ✅ Isolated PostgreSQL database (copy of main database)
- ✅ Isolated Redis instance
- ✅ API and Workers containers
- ✅ Uses main InfluxDB instance (shared)
- ✅ Unique ports per task to avoid conflicts

## Quick Start

### Start a Test Environment

```bash
# Simple way (auto-generates task ID)
bash scripts/start-dev-env.sh

# With specific task ID
bash scripts/start-dev-env.sh TASK-123

# With specific task ID and port offset
bash scripts/start-dev-env.sh TASK-123 10
```

### Stop a Test Environment

```bash
bash scripts/stop-task-docker.sh TASK-123
```

## Scripts

### `scripts/start-task-docker.sh`
Main script that:
1. Creates task-specific Docker Compose file
2. Starts PostgreSQL and Redis
3. Copies database from main repo
4. Starts API and Workers

**Usage:**
```bash
bash scripts/start-task-docker.sh <TASK_ID> <PORT_OFFSET>
```

### `scripts/stop-task-docker.sh`
Stops and cleans up a task environment.

**Usage:**
```bash
bash scripts/stop-task-docker.sh <TASK_ID>
```

### `scripts/copy-database-for-task.sh`
Copies database from main repo to task-specific PostgreSQL instance.

**Usage:**
```bash
bash scripts/copy-database-for-task.sh <TASK_ID> <SOURCE_HOST> <SOURCE_PORT> <TARGET_HOST> <TARGET_PORT>
```

### `scripts/create-task-compose.sh`
Generates a Docker Compose file for a specific task.

**Usage:**
```bash
bash scripts/create-task-compose.sh <TASK_ID> <PORT_OFFSET>
```

### `scripts/start-dev-env.sh`
Simple wrapper for dev agents to start environments.

**Usage:**
```bash
bash scripts/start-dev-env.sh [TASK_ID] [PORT_OFFSET]
```

## Port Allocation

Default ports (offset 0):
- PostgreSQL: 5433
- API: 5000
- Redis: 6379
- InfluxDB: 8086 (uses main instance)

With offset 10:
- PostgreSQL: 5442
- API: 5010
- Redis: 6389
- InfluxDB: 8086 (uses main instance)

## Database Setup

Each task environment:
- Gets a fresh copy of the main database
- Has isolated databases: `managing_{task_id}` and `orleans_{task_id}`
- Changes don't affect the main database
- Can be reset by stopping and restarting

## Integration with Vibe Kanban

When a task moves to "Ready for QA":
1. Vibe Kanban calls `scripts/start-task-docker.sh`
2. Environment is created with database copy
3. Test URLs are provided
4. When done, Vibe Kanban calls `scripts/stop-task-docker.sh`

## Integration with dev-manager-mcp

dev-manager-mcp can manage multiple environments:
- Start: `npx dev-manager-mcp start --command "bash scripts/start-task-docker.sh TASK-123 0"`
- Status: `npx dev-manager-mcp status`
- Stop: `npx dev-manager-mcp stop --session-key <KEY>`

## Troubleshooting

### Port Conflicts
Use a different port offset:
```bash
bash scripts/start-task-docker.sh TASK-123 10
```

### Database Copy Fails
1. Verify main database is running: `docker ps | grep postgres`
2. Check connection: `PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d managing -c '\q'`
3. Ensure PostgreSQL client is installed: `which psql`

### Services Don't Start
Check logs:
```bash
docker logs managing-api-TASK-123
docker logs managing-workers-TASK-123
```

### Clean Up All Task Environments
```bash
# List all task containers
docker ps -a | grep -E "postgres-|managing-api-|managing-workers-|redis-"

# Stop and remove all task containers
docker ps -a | grep -E "postgres-|managing-api-|managing-workers-|redis-" | awk '{print $1}' | xargs docker rm -f

# Remove all task volumes
docker volume ls | grep -E "postgresdata_|redis_data_" | awk '{print $2}' | xargs docker volume rm
```

## Best Practices

1. **Use descriptive task IDs**: `TASK-123`, `FEATURE-456`, `BUGFIX-789`
2. **Stop environments when done**: Frees up resources
3. **Use port offsets for parallel testing**: Test multiple tasks simultaneously
4. **Check port availability**: Before starting, verify ports aren't in use
5. **Monitor resource usage**: Each environment uses memory and CPU

## Architecture

```
Main Environment (localhost:5432)
├── PostgreSQL (main database)
└── InfluxDB (shared)

Task Environment (offset ports)
├── PostgreSQL (isolated, copied from main)
├── Redis (isolated)
├── API Container (connects to task PostgreSQL, main InfluxDB)
└── Workers Container (connects to task PostgreSQL, main InfluxDB)
```

## Next Steps

1. Install Vibe Kanban: See `docs/INSTALL_VIBE_KANBAN_AND_DEV_MANAGER.md`
2. Install dev-manager-mcp: See `docs/INSTALL_VIBE_KANBAN_AND_DEV_MANAGER.md`
3. Configure agent command: See `.cursor/commands/start-dev-env.md`