Add vibe-kanban
This commit is contained in:
177
docs/TASK_ENVIRONMENTS_SETUP.md
Normal file
177
docs/TASK_ENVIRONMENTS_SETUP.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user