From dbbff8adc98bb4f226e48b0c247445c764172165 Mon Sep 17 00:00:00 2001
From: bunker-admin <admin@thebunkerops.ca>
Date: Thu, 16 Apr 2026 12:56:55 -0600
Subject: [PATCH] install: host-port preflight in install.sh + surface
 verify/teardown tools

scripts/install.sh: inline ss -Htln check before tarball download so
cockpit-on-9090 (and friends) fail early instead of breaking the stack
mid-compose-up. Culprit-specific hints for :9090 (cockpit.socket) and
:80/:443. Gracefully skipped if iproute2 not installed.

config.sh: Next Steps in release mode now surfaces
  - test-deployment.sh --wait 60 (verify step)
  - validate-env.sh (re-check ports/.env)
  - pangolin-teardown.sh (clean reset before reinstall)
Also documents the ~3min first-pull + ~90s stabilization window so
brief "unhealthy" statuses don't panic new users.

Bunker Admin
---
 config.sh          | 16 ++++++++++++----
 scripts/install.sh | 31 +++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/config.sh b/config.sh
index 2e9c2d5b..5b8d1eea 100755
--- a/config.sh
+++ b/config.sh
@@ -2200,15 +2200,23 @@ print_next_steps() {
     echo -e "  ${BOLD}1.${NC} Start all services:"
     echo -e "     ${CYAN}docker compose up -d${NC}"
     echo ""
-    echo -e "     Pre-built images will be pulled from the registry (~2 min first time)."
+    echo -e "     First run pulls ~40 images (~3 min) and stabilizes health in ~90s."
+    echo -e "     Brief unhealthy statuses during this window are expected."
     echo -e "     Database migrations and seeding run automatically on startup."
     echo ""
-    echo -e "  ${BOLD}2.${NC} Access the application:"
+    echo -e "  ${BOLD}2.${NC} Verify the install:"
+    echo -e "     ${CYAN}bash scripts/test-deployment.sh --wait 60${NC}"
+    echo ""
+    echo -e "     Checks all containers healthy, API responding, (if domain set) tunnel reachable."
+    echo ""
+    echo -e "  ${BOLD}3.${NC} Access the application:"
     echo -e "     Admin GUI:  ${CYAN}http://localhost:3000${NC}"
     echo -e "     API:        ${CYAN}http://localhost:4000${NC}"
     echo ""
-    echo -e "  ${BOLD}3.${NC} Check status:"
-    echo -e "     ${CYAN}docker compose ps${NC}"
+    echo -e "  ${BOLD}4.${NC} Useful tools:"
+    echo -e "     ${CYAN}bash scripts/validate-env.sh${NC}        # re-check .env + host ports"
+    echo -e "     ${CYAN}bash scripts/pangolin-teardown.sh${NC}   # wipe tunnel org before reinstall (dry-run by default)"
+    echo -e "     ${CYAN}docker compose ps${NC}                    # live status"
     echo -e "     ${CYAN}docker compose logs -f api --tail 20${NC}"
     echo ""
   else
diff --git a/scripts/install.sh b/scripts/install.sh
index 6b92765e..2e219d97 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -116,6 +116,37 @@ if [[ "$AVAILABLE_MB" -lt "$MIN_DISK_MB" ]]; then
 fi
 success "Disk space: ${AVAILABLE_MB}MB available (${MIN_DISK_MB}MB required)"
 
+# Host port availability — checks the ports the stack will try to bind BEFORE
+# we've downloaded anything. Avoids partially-installed state when e.g. cockpit
+# owns :9090 and breaks prometheus mid-startup.
+if command -v ss >/dev/null 2>&1; then
+  HOST_CONFLICTS=()
+  for port in 3000 4000 4100 5433 9090 3001 3030 9001 5678 8091 8025 8888 3010 4003; do
+    if ss -Htln 2>/dev/null | awk -v p=":$port" '$4 ~ p"$" {found=1} END{exit !found}'; then
+      HOST_CONFLICTS+=("$port")
+    fi
+  done
+  if [[ ${#HOST_CONFLICTS[@]} -gt 0 ]]; then
+    error "Host ports already in use: ${HOST_CONFLICTS[*]}"
+    echo ""
+    echo "  These ports must be free for the Changemaker Lite stack:"
+    for p in "${HOST_CONFLICTS[@]}"; do
+      case "$p" in
+        9090) echo "    :$p  — commonly cockpit.socket. Fix: sudo systemctl disable --now cockpit.socket" ;;
+        80|443) echo "    :$p  — host nginx/apache. Stop the host service or use a different subdomain entrypoint." ;;
+        3030) echo "    :$p  — another Gitea or service on this port." ;;
+        *) echo "    :$p" ;;
+      esac
+    done
+    echo ""
+    echo "  Or re-run later with --dir to install into a directory whose stack remaps ports."
+    exit 1
+  fi
+  success "Host ports available"
+else
+  warn "ss not installed — skipping host port check (apt install iproute2 to enable)"
+fi
+
 # =============================================================================
 # Step 2: Check install directory
 # =============================================================================