feat: resolve Docker port conflicts for evals services

- Update postgres port from 5432 to 5433 to avoid conflicts
- Update redis port from 6379 to 6380 to avoid conflicts
- Update DATABASE_URL in .env.development and .env.test to use new port
- Add .env.local.example with port configuration documentation
- Update README.md with comprehensive port configuration guide
- Add PORT-CONFLICT-SOLUTION.md with detailed implementation plan

This allows evals to run alongside other postgres/redis services
without port conflicts while maintaining backward compatibility.

Author: roomote

packages/evals/.env.development

@@ -1 +1,3 @@
-DATABASE_URL=postgres://postgres:password@localhost:5432/evals_development
+DATABASE_URL=postgres://postgres:password@localhost:5433/evals_development
+EVALS_DB_PORT=5433
+EVALS_REDIS_PORT=6380

packages/evals/.env.test

@@ -1 +1,3 @@
-DATABASE_URL=postgres://postgres:password@localhost:5432/evals_test
+DATABASE_URL=postgres://postgres:password@localhost:5433/evals_test
+EVALS_DB_PORT=5433
+EVALS_REDIS_PORT=6380

packages/evals/PORT-CONFLICT-SOLUTION.md

@@ -0,0 +1,77 @@
+# Docker Port Conflict Solution for Evals
+
+## Problem
+
+The `pnpm evals` command runs Docker services for postgres (port 5432) and redis (port 6379) which conflict with other services running on the same ports.
+
+## Solution
+
+Update the environment configuration to use non-conflicting ports:
+
+- Postgres: 5433 (instead of 5432)
+- Redis: 6380 (instead of 6379)
+
+## Implementation Plan
+
+### 1. Environment File Updates
+
+Update the following files to include port configuration:
+
+**packages/evals/.env.development**
+
+```
+DATABASE_URL=postgres://postgres:password@localhost:5433/evals_development
+EVALS_DB_PORT=5433
+EVALS_REDIS_PORT=6380
+```
+
+**packages/evals/.env.test**
+
+```
+DATABASE_URL=postgres://postgres:password@localhost:5433/evals_test
+EVALS_DB_PORT=5433
+EVALS_REDIS_PORT=6380
+```
+
+### 2. Create .env.local Template
+
+Create `packages/evals/.env.local.example` to document the configuration:
+
+```
+# Copy this file to .env.local and customize as needed
+# These ports are used to avoid conflicts with other services
+
+# Database configuration
+EVALS_DB_PORT=5433
+EVALS_REDIS_PORT=6380
+
+# Optional: Override database URL if needed
+# DATABASE_URL=postgres://postgres:password@localhost:5433/evals_development
+```
+
+### 3. Docker Compose Configuration
+
+The existing docker-compose.yml already supports these environment variables:
+
+- `${EVALS_DB_PORT:-5432}:5432` for postgres
+- `${EVALS_REDIS_PORT:-6379}:6379` for redis
+
+### 4. Documentation Updates
+
+Update README.md to document the port configuration and how to avoid conflicts.
+
+## Benefits
+
+1. **No Port Conflicts**: Evals can run alongside other postgres/redis services
+2. **Backward Compatible**: Default ports remain the same if environment variables aren't set
+3. **Configurable**: Users can customize ports via environment variables
+4. **Clear Documentation**: Users understand how to resolve conflicts
+
+## Testing
+
+After implementation:
+
+1. Start existing postgres/redis services on default ports
+2. Run `pnpm evals` to verify it uses the new ports
+3. Confirm both services can run simultaneously
+4. Test database connectivity with the new port configuration

packages/evals/README.md

@@ -89,6 +89,46 @@ The setup script does the following:
 - Prompts for an OpenRouter API key to add to `.env.local`
 - Optionally builds and installs the Roo Code extension from source
 
+## Port Configuration
+
+By default, the evals system uses the following ports:
+
+- **PostgreSQL**: 5433 (external) → 5432 (internal)
+- **Redis**: 6380 (external) → 6379 (internal)
+- **Web Service**: 3446 (external) → 3000 (internal)
+
+These ports are configured to avoid conflicts with other services that might be running on the standard PostgreSQL (5432) and Redis (6379) ports.
+
+### Customizing Ports
+
+If you need to use different ports, you can customize them by creating a `.env.local` file in the `packages/evals/` directory:
+
+```sh
+# Copy the example file and customize as needed
+cp packages/evals/.env.local.example packages/evals/.env.local
+```
+
+Then edit `.env.local` to set your preferred ports:
+
+```sh
+# Custom port configuration
+EVALS_DB_PORT=5434
+EVALS_REDIS_PORT=6381
+EVALS_WEB_PORT=3447
+
+# Optional: Override database URL if needed
+DATABASE_URL=postgres://postgres:password@localhost:5434/evals_development
+```
+
+### Port Conflict Resolution
+
+If you encounter port conflicts when running `pnpm evals`, you have several options:
+
+1. **Use the default configuration** (recommended): The system now uses non-standard ports by default
+2. **Stop conflicting services**: Temporarily stop other PostgreSQL/Redis services
+3. **Customize ports**: Use the `.env.local` file to set different ports
+4. **Use Docker networks**: Run services in isolated Docker networks
+
 ## Troubleshooting
 
 Here are some errors that you might encounter along with potential fixes: