From 8c2b720564f5cca50c826f00cd3f49940ad73cb9 Mon Sep 17 00:00:00 2001
From: Igor Loskutov <igor.loskutoff@gmail.com>
Date: Wed, 11 Feb 2026 14:17:19 -0500
Subject: [PATCH] fix: improve port conflict detection and ollama model check
 in standalone setup

- Filter OrbStack/Docker Desktop PIDs from port conflict check (false positives on Mac)
- Check all infra ports (5432, 6379, 3900, 3903) not just app ports
- Fix ollama model detection to match on name column only
- Document OrbStack and cross-project port conflicts in troubleshooting
---
 docs/docs/installation/setup-standalone.md | 10 +++++++--
 scripts/setup-standalone.sh                | 25 ++++++++++++++--------
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/docs/installation/setup-standalone.md b/docs/docs/installation/setup-standalone.md
index 78eaa2f9..320ca3fe 100644
--- a/docs/docs/installation/setup-standalone.md
+++ b/docs/docs/installation/setup-standalone.md
@@ -168,6 +168,8 @@ If the frontend or backend behaves unexpectedly (e.g., env vars seem ignored, ch
 lsof -i :3000   # frontend
 lsof -i :1250   # backend
 lsof -i :5432   # postgres
+lsof -i :3900   # Garage S3 API
+lsof -i :6379   # Redis
 
 # Kill stale processes on a port
 lsof -ti :3000 | xargs kill
@@ -175,9 +177,13 @@ lsof -ti :3000 | xargs kill
 
 Common causes:
 - A stale `next dev` or `pnpm dev` process from another terminal/worktree
-- Another Docker Compose project (different worktree) with containers on the same ports
+- Another Docker Compose project (different worktree) with containers on the same ports — the setup script only manages its own project; containers from other projects must be stopped manually (`docker ps` to find them, `docker stop` to kill them)
 
-The setup script checks for port conflicts before starting services.
+The setup script checks ports 3000, 1250, 5432, 6379, 3900, 3903 for conflicts before starting services. It ignores OrbStack/Docker Desktop port forwarding processes (which always bind these ports but are not real conflicts).
+
+### OrbStack false port-conflict warnings (Mac)
+
+If you use OrbStack as your Docker runtime, `lsof` will show OrbStack binding ports like 3000, 1250, etc. even when no containers are running. This is OrbStack's port forwarding mechanism — not a real conflict. The setup script filters these out automatically.
 
 ### Re-enabling authentication
 
diff --git a/scripts/setup-standalone.sh b/scripts/setup-standalone.sh
index 790339f6..82d68fec 100755
--- a/scripts/setup-standalone.sh
+++ b/scripts/setup-standalone.sh
@@ -113,7 +113,7 @@ step_llm() {
             echo ""
 
             # Pull model if not already present
-            if ollama list 2>/dev/null | grep -q "$MODEL"; then
+            if ollama list 2>/dev/null | awk '{print $1}' | grep -qx "$MODEL"; then
                 ok "Model $MODEL already pulled"
             else
                 info "Pulling model $MODEL (this may take a while)..."
@@ -143,7 +143,7 @@ step_llm() {
             echo ""
 
             # Pull model inside container
-            if compose_cmd exec "$OLLAMA_SVC" ollama list 2>/dev/null | grep -q "$MODEL"; then
+            if compose_cmd exec "$OLLAMA_SVC" ollama list 2>/dev/null | awk '{print $1}' | grep -qx "$MODEL"; then
                 ok "Model $MODEL already pulled"
             else
                 info "Pulling model $MODEL inside container (this may take a while)..."
@@ -290,16 +290,23 @@ ENVEOF
 step_services() {
     info "Step 5: Starting Docker services"
 
-    # Check for port conflicts — stale processes silently shadow Docker port mappings
+    # Check for port conflicts — stale processes silently shadow Docker port mappings.
+    # OrbStack/Docker Desktop bind ports for forwarding; ignore those PIDs.
     local ports_ok=true
-    for port in 3000 1250; do
-        local pid
-        pid=$(lsof -ti :"$port" 2>/dev/null || true)
-        if [[ -n "$pid" ]]; then
-            warn "Port $port already in use by PID $pid"
+    for port in 3000 1250 5432 6379 3900 3903; do
+        local pids
+        pids=$(lsof -ti :"$port" 2>/dev/null || true)
+        for pid in $pids; do
+            local pname
+            pname=$(ps -p "$pid" -o comm= 2>/dev/null || true)
+            # OrbStack and Docker Desktop own port forwarding — not real conflicts
+            if [[ "$pname" == *"OrbStack"* ]] || [[ "$pname" == *"com.docker"* ]] || [[ "$pname" == *"vpnkit"* ]]; then
+                continue
+            fi
+            warn "Port $port already in use by PID $pid ($pname)"
             warn "Kill it with: lsof -ti :$port | xargs kill"
             ports_ok=false
-        fi
+        done
     done
     if [[ "$ports_ok" == "false" ]]; then
         warn "Port conflicts detected — Docker containers may not be reachable"