From 483eca7c7706f6484655ec12aa84eb4c2a699686 Mon Sep 17 00:00:00 2001
From: Bill <bill@bballou.com>
Date: Fri, 31 Oct 2025 14:18:48 -0400
Subject: [PATCH] docs: add port configuration troubleshooting

- Document port conflict resolution in TESTING_GUIDE.md
- Add example for custom API_PORT in .env.example
- Explain container vs host port architecture
- Provide solutions for common port conflict scenarios
---
 .env.example     |  5 +++--
 TESTING_GUIDE.md | 20 +++++++++++++++++---
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/.env.example b/.env.example
index 16dd7a1..c1289b3 100644
--- a/.env.example
+++ b/.env.example
@@ -25,9 +25,10 @@ TRADE_HTTP_PORT=8002
 GETPRICE_HTTP_PORT=8003
 
 # API Server Port (exposed on host machine for REST API)
-# Container ALWAYS uses port 8080 internally (hardcoded in entrypoint-api.sh)
-# This variable ONLY controls the host port mapping (host:8080 -> container:8080)
+# Container ALWAYS uses port 8080 internally (hardcoded in entrypoint.sh)
+# This variable ONLY controls the host port mapping (host:API_PORT -> container:8080)
 # Change this if port 8080 is already in use on your host machine
+# Example: API_PORT=8889 if port 8080 is occupied by another service
 # Used for Windmill integration and external API access
 API_PORT=8080
 
diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 022231b..d7be120 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -278,23 +278,37 @@ chmod -R 755 data logs
 ### Problem: Health check fails
 
 **Symptoms:**
-- `curl http://localhost:8080/health` returns error
-- Container is running but API not responding
+- `curl http://localhost:8080/health` returns error or HTML page
+- Container is running but API not responding on expected port
 
 **Debug steps:**
 ```bash
 # Check if API process is running
 docker exec ai-trader ps aux | grep uvicorn
 
-# Check internal health
+# Check internal health (always uses 8080 inside container)
 docker exec ai-trader curl http://localhost:8080/health
 
 # Check logs for startup errors
 docker logs ai-trader | grep -i error
+
+# Check your configured API_PORT
+grep API_PORT .env
 ```
 
 **Solutions:**
 ```bash
+# If you get HTML 404 page, another service is using your port
+# Solution 1: Change API_PORT in .env
+echo "API_PORT=8889" >> .env
+docker-compose down
+docker-compose up -d
+
+# Solution 2: Find and stop the conflicting service
+sudo lsof -i :8080
+# or
+sudo netstat -tlnp | grep 8080
+
 # If MCP services didn't start:
 docker exec ai-trader ps aux | grep python