Add vibe-kanban
This commit is contained in:
BIN
.cursor/.DS_Store
vendored
BIN
.cursor/.DS_Store
vendored
Binary file not shown.
287
.cursor/commands/start-dev-env.md
Normal file
287
.cursor/commands/start-dev-env.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# start-dev-env
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this command when you want to:
|
||||
- Test your code changes in an isolated Docker Compose environment
|
||||
- Verify API endpoints work correctly after modifications
|
||||
- Test database interactions with a fresh copy of the main database
|
||||
- Iterate on changes by testing them in a real environment
|
||||
- Debug issues in an isolated environment before committing
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- .NET SDK installed (`dotnet --version`)
|
||||
- Main PostgreSQL database running on localhost:5432
|
||||
- Docker installed and running
|
||||
- PostgreSQL client (psql) installed
|
||||
- Scripts are executable: `chmod +x scripts/*.sh`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Verify Prerequisites
|
||||
|
||||
Check that all prerequisites are met:
|
||||
|
||||
1. **Check main database is accessible:**
|
||||
Run: `PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d managing -c '\q'`
|
||||
|
||||
**If connection fails:**
|
||||
- Error: "❌ Cannot connect to main database at localhost:5432"
|
||||
- **Fix**: Start the main PostgreSQL container:
|
||||
```bash
|
||||
cd src/Managing.Docker
|
||||
docker-compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres
|
||||
```
|
||||
- Wait 15 seconds for PostgreSQL to start
|
||||
- Retry connection check
|
||||
- **STOP** if database cannot be started
|
||||
|
||||
2. **Check Docker is running:**
|
||||
Run: `docker ps`
|
||||
|
||||
**If Docker is not running:**
|
||||
- Error: "❌ Docker is not running"
|
||||
- **Fix**: Start Docker Desktop or Docker daemon
|
||||
- **STOP** if Docker cannot be started
|
||||
|
||||
### Step 2: Generate Task ID
|
||||
|
||||
Generate a unique task ID for this dev session:
|
||||
|
||||
- Use format: `DEV-{timestamp}` or `DEV-{random}`
|
||||
- Example: `DEV-20250101-143022` or `DEV-A3X9`
|
||||
- Store this ID for later reference
|
||||
|
||||
### Step 3: Find Available Port
|
||||
|
||||
Find an available port offset to avoid conflicts:
|
||||
|
||||
- Start with offset 0 (ports: 5433, 5000, 6379)
|
||||
- If ports are in use, try offset 10, 20, 30, etc.
|
||||
- Check if ports are available:
|
||||
```bash
|
||||
lsof -i :5433 || echo "Port 5433 available"
|
||||
lsof -i :5000 || echo "Port 5000 available"
|
||||
```
|
||||
|
||||
### Step 4: Start Docker Environment
|
||||
|
||||
Start the Docker Compose environment with database copy:
|
||||
|
||||
Run: `bash scripts/start-task-docker.sh {TASK_ID} {PORT_OFFSET}`
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash scripts/start-task-docker.sh DEV-A3X9 0
|
||||
```
|
||||
|
||||
**Or use the simple wrapper:**
|
||||
```bash
|
||||
bash scripts/start-dev-env.sh DEV-A3X9 0
|
||||
```
|
||||
|
||||
**What this does:**
|
||||
1. Creates task-specific Docker Compose file
|
||||
2. Starts PostgreSQL on port 5433 (or 5432 + offset)
|
||||
3. Starts Redis on port 6379 (or 6379 + offset)
|
||||
4. Waits for PostgreSQL to be ready
|
||||
5. Copies database from main repo (localhost:5432) to test instance
|
||||
6. Starts API and Workers with correct connection strings
|
||||
7. Uses main InfluxDB instance at localhost:8086
|
||||
|
||||
**If start succeeds:**
|
||||
- Note the API URL (e.g., "http://localhost:5000")
|
||||
- Note the database name (e.g., "managing_dev-a3x9")
|
||||
- Continue to Step 5
|
||||
|
||||
**If start fails:**
|
||||
- Check error messages
|
||||
- Common issues:
|
||||
- Port conflicts: Try different port offset
|
||||
- Database connection: Verify main database is running
|
||||
- Docker issues: Check Docker is running
|
||||
- **Try to fix:**
|
||||
- Use different port offset
|
||||
- Restart Docker
|
||||
- Verify main database is accessible
|
||||
- **STOP** if cannot start after multiple attempts
|
||||
|
||||
### Step 5: Verify Environment is Running
|
||||
|
||||
Verify the Docker environment is working:
|
||||
|
||||
1. **Check API health endpoint:**
|
||||
Run: `curl http://localhost:{API_PORT}/health`
|
||||
|
||||
**If health check fails:**
|
||||
- Wait 30 seconds for services to start
|
||||
- Check Docker logs: `docker logs managing-api-{TASK_ID}`
|
||||
- Check for errors
|
||||
- **STOP** if services don't start after 2 minutes
|
||||
|
||||
2. **Verify database was copied:**
|
||||
Run: `PGPASSWORD=postgres psql -h localhost -p {POSTGRES_PORT} -U postgres -d managing_{TASK_ID} -c "SELECT COUNT(*) FROM \"Users\";"`
|
||||
|
||||
**If database is empty or missing:**
|
||||
- Error: "❌ Database was not copied correctly"
|
||||
- **Fix**: Re-run database copy script manually
|
||||
- **STOP** if database cannot be copied
|
||||
|
||||
### Step 6: Test Your Changes
|
||||
|
||||
Now you can test your changes:
|
||||
|
||||
1. **API endpoints:**
|
||||
- Use API URL: `http://localhost:{API_PORT}`
|
||||
- Test modified endpoints
|
||||
- Verify responses are correct
|
||||
|
||||
2. **Database interactions:**
|
||||
- Changes are isolated to this test database
|
||||
- Main database remains unchanged
|
||||
- Can test migrations, data changes, etc.
|
||||
|
||||
3. **Iterate:**
|
||||
- Make code changes
|
||||
- Rebuild solution: `/build-solution`
|
||||
- Rebuild Docker images if needed: `docker-compose -f {COMPOSE_FILE} build`
|
||||
- Restart services: `docker-compose -f {COMPOSE_FILE} restart managing-api-{TASK_ID}`
|
||||
- Test again
|
||||
|
||||
### Step 7: Stop Instance When Done
|
||||
|
||||
When finished testing, stop the Docker environment:
|
||||
|
||||
Run: `bash scripts/stop-task-docker.sh {TASK_ID}`
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash scripts/stop-task-docker.sh DEV-A3X9
|
||||
```
|
||||
|
||||
This will:
|
||||
- Stop all containers
|
||||
- Remove volumes
|
||||
- Clean up compose file
|
||||
|
||||
## Integration with Development Workflow
|
||||
|
||||
### After Making Code Changes
|
||||
|
||||
1. **Build solution:**
|
||||
- Run: `/build-solution`
|
||||
- Fix any build errors
|
||||
|
||||
2. **Start Docker environment for testing:**
|
||||
- Run: `/start-aspire-dev`
|
||||
- Note the URLs
|
||||
|
||||
3. **Test your changes:**
|
||||
- Use the API endpoints
|
||||
- Verify database interactions
|
||||
- Check logs: `docker logs managing-api-{TASK_ID}`
|
||||
|
||||
4. **Iterate if needed:**
|
||||
- Fix issues found during testing
|
||||
- Rebuild Docker images if code changed
|
||||
- Restart services
|
||||
- Test again
|
||||
|
||||
5. **Stop when done:**
|
||||
- Stop the Docker environment
|
||||
- Clean up if needed
|
||||
|
||||
### When to Use This Command
|
||||
|
||||
- ✅ After modifying API endpoints
|
||||
- ✅ After changing database models
|
||||
- ✅ After updating business logic
|
||||
- ✅ Before committing changes
|
||||
- ✅ When debugging issues
|
||||
- ✅ When testing integrations
|
||||
|
||||
### When NOT to Use This Command
|
||||
|
||||
- ❌ For production deployments (use proper CI/CD)
|
||||
- ❌ For running unit tests (use test runner)
|
||||
- ❌ For code review (use static analysis)
|
||||
|
||||
## Error Handling
|
||||
|
||||
**If main database is not accessible:**
|
||||
- Start PostgreSQL container: `cd src/Managing.Docker && docker-compose up -d postgres`
|
||||
- Wait 15 seconds
|
||||
- Retry connection check
|
||||
- **STOP** if database cannot be started
|
||||
|
||||
**If ports are in use:**
|
||||
- Try different port offset (10, 20, 30, etc.)
|
||||
- Check what's using the ports: `lsof -i :{PORT}`
|
||||
- Stop conflicting services if needed
|
||||
|
||||
**If database copy fails:**
|
||||
- Verify main database is accessible
|
||||
- Check PostgreSQL client is installed: `which psql`
|
||||
- Verify connection strings are correct
|
||||
- Check disk space
|
||||
- **STOP** if copy cannot complete
|
||||
|
||||
**If Docker services don't start:**
|
||||
- Check Docker logs: `docker logs {container_id}`
|
||||
- Verify all dependencies are installed
|
||||
- Check .NET SDK version matches requirements
|
||||
- **STOP** if services cannot start after multiple attempts
|
||||
|
||||
## Example Execution
|
||||
|
||||
**User input:** `/start-dev-env`
|
||||
|
||||
**AI execution:**
|
||||
|
||||
1. Verify prerequisites:
|
||||
- Check main database: ✅ Accessible
|
||||
- Check Docker: ✅ Running
|
||||
|
||||
2. Generate task ID: `DEV-A3X9`
|
||||
|
||||
3. Find available port: Offset 0 (ports available)
|
||||
|
||||
4. Start Docker environment:
|
||||
```bash
|
||||
bash scripts/start-task-docker.sh DEV-A3X9 0
|
||||
```
|
||||
- Creating compose file...
|
||||
- Starting PostgreSQL...
|
||||
- ✅ PostgreSQL ready
|
||||
- Copying database...
|
||||
- ✅ Database copied
|
||||
- Starting API and Workers...
|
||||
- ✅ Services started
|
||||
|
||||
5. Verify:
|
||||
- API: http://localhost:5000 ✅
|
||||
- Health check: ✅ Healthy
|
||||
- Database: ✅ Copied (1234 users found)
|
||||
|
||||
6. Success: "✅ Docker dev environment ready!"
|
||||
- API: http://localhost:5000
|
||||
- Database: managing_dev-a3x9 on port 5433
|
||||
- To stop: `bash scripts/stop-task-docker.sh DEV-A3X9`
|
||||
|
||||
## Important Notes
|
||||
|
||||
- ✅ **Always verify main database first** - Must be accessible
|
||||
- ✅ **Use unique task IDs** - Prevents conflicts
|
||||
- ✅ **Check port availability** - Avoids port conflicts
|
||||
- ✅ **Wait for services to start** - Can take 30-60 seconds
|
||||
- ✅ **Database is isolated** - Changes don't affect main database
|
||||
- ✅ **InfluxDB uses main instance** - No separate InfluxDB per task
|
||||
- ✅ **Stop when done** - Frees up resources
|
||||
- ⚠️ **Multiple instances** - Each needs unique ports
|
||||
- ⚠️ **Resource usage** - Each instance uses memory/CPU
|
||||
- 📦 **Script location**: `scripts/start-task-docker.sh`
|
||||
- 🔧 **Main database**: localhost:5432
|
||||
- 🗄️ **Test databases**: localhost:5433+ (isolated per task)
|
||||
- 📊 **InfluxDB**: Uses main instance at localhost:8086
|
||||
|
||||
Reference in New Issue
Block a user