# 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