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

# 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 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 scripts/start-task-docker.sh <TASK_ID> <PORT_OFFSET>

scripts/stop-task-docker.sh

Stops and cleans up a task environment.

Usage:

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 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 scripts/create-task-compose.sh <TASK_ID> <PORT_OFFSET>

scripts/start-dev-env.sh

Simple wrapper for dev agents to start environments.

Usage:

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 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:

docker logs managing-api-TASK-123
docker logs managing-workers-TASK-123

Clean Up All Task Environments

# 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