docs(connect): clearer WS port preflight prompt, default to disable (#69)

When the WS port is already taken, the installer now explains that the WS
sink is an optional local WebSocket (a shred -> jito-shredstream setup does
not use it), spells out each option's consequence, and defaults to disable
rather than continue — the port is known taken, so continuing was the one
choice guaranteed to fail to bind.

Author: juan-malbeclabs

CHANGELOG.md

@@ -301,7 +301,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **WebSocket port preflight**: before starting the container the installer checks whether the WS
     port is already bound on the host and, interactively, offers to pick another port, disable the
     sink, or continue (non-interactively it warns and continues — the bridge then runs without the
-    sink, tunnel unaffected).
+    sink, tunnel unaffected). The interactive prompt now explains what the WS sink is (an *optional*
+    local WebSocket a shred → jito-shredstream setup does not use), spells out each option's
+    consequence, and **defaults to disable** rather than continue — the port is already known taken,
+    so continuing was the one choice guaranteed to fail to bind.
   - **`WS_BIND=""` now works through the one-liner**: `WS_BIND` is forwarded whenever it is *set*,
     including set-but-empty, so the WS sink can be disabled straight from the pipe (previously only
     non-empty values were relayed, forcing a hand-written `docker run`).

scripts/connect-devnet.sh

@@ -437,8 +437,10 @@ preflight_ws_port() {
   local who=""
   command -v ss >/dev/null 2>&1 && who="$($SUDO ss -Hltnp 2>/dev/null | awk -v p=":${p}\$" '$4 ~ p {print $NF; exit}')"
   warn "TCP port $p is already in use${who:+ ($who)}; the WS market-data sink can't bind there."
+  info "The WS market-data sink is an OPTIONAL local WebSocket that re-serves ingested feed data to consumers on this host."
+  info "A shred -> jito-shredstream setup does NOT use it; if nothing on this host consumes it, disabling is safe (it does not affect shred forwarding or the DoubleZero tunnel)."
   if [ -r "$TTY" ] && [ "$DZ_ASSUME_YES" != 1 ]; then
-    local choice; choice="$(ask 'WS port in use — [p]ick another port, [d]isable the WS sink, or [c]ontinue anyway' 'c')"
+    local choice; choice="$(ask 'WS port in use — [p] pick another port, [d] disable the sink (clean: no sink, no bind error), [c] continue anyway (bridge starts but the sink fails to bind; fine only if you do not use it)' 'd')"
     case "$choice" in
       p|P) local np; np="$(ask 'New WS port' '8181')"; WS_BIND="0.0.0.0:${np}"; WS_PORT="$np"
            info "WS sink will use 0.0.0.0:${np}."; preflight_ws_port ;;   # re-check the new choice

scripts/connect-testnet.sh

@@ -432,8 +432,10 @@ preflight_ws_port() {
   local who=""
   command -v ss >/dev/null 2>&1 && who="$($SUDO ss -Hltnp 2>/dev/null | awk -v p=":${p}\$" '$4 ~ p {print $NF; exit}')"
   warn "TCP port $p is already in use${who:+ ($who)}; the WS market-data sink can't bind there."
+  info "The WS market-data sink is an OPTIONAL local WebSocket that re-serves ingested feed data to consumers on this host."
+  info "A shred -> jito-shredstream setup does NOT use it; if nothing on this host consumes it, disabling is safe (it does not affect shred forwarding or the DoubleZero tunnel)."
   if [ -r "$TTY" ] && [ "$DZ_ASSUME_YES" != 1 ]; then
-    local choice; choice="$(ask 'WS port in use — [p]ick another port, [d]isable the WS sink, or [c]ontinue anyway' 'c')"
+    local choice; choice="$(ask 'WS port in use — [p] pick another port, [d] disable the sink (clean: no sink, no bind error), [c] continue anyway (bridge starts but the sink fails to bind; fine only if you do not use it)' 'd')"
     case "$choice" in
       p|P) local np; np="$(ask 'New WS port' '8181')"; WS_BIND="0.0.0.0:${np}"; WS_PORT="$np"
            info "WS sink will use 0.0.0.0:${np}."; preflight_ws_port ;;   # re-check the new choice

scripts/connect.sh

@@ -432,8 +432,10 @@ preflight_ws_port() {
   local who=""
   command -v ss >/dev/null 2>&1 && who="$($SUDO ss -Hltnp 2>/dev/null | awk -v p=":${p}\$" '$4 ~ p {print $NF; exit}')"
   warn "TCP port $p is already in use${who:+ ($who)}; the WS market-data sink can't bind there."
+  info "The WS market-data sink is an OPTIONAL local WebSocket that re-serves ingested feed data to consumers on this host."
+  info "A shred -> jito-shredstream setup does NOT use it; if nothing on this host consumes it, disabling is safe (it does not affect shred forwarding or the DoubleZero tunnel)."
   if [ -r "$TTY" ] && [ "$DZ_ASSUME_YES" != 1 ]; then
-    local choice; choice="$(ask 'WS port in use — [p]ick another port, [d]isable the WS sink, or [c]ontinue anyway' 'c')"
+    local choice; choice="$(ask 'WS port in use — [p] pick another port, [d] disable the sink (clean: no sink, no bind error), [c] continue anyway (bridge starts but the sink fails to bind; fine only if you do not use it)' 'd')"
     case "$choice" in
       p|P) local np; np="$(ask 'New WS port' '8181')"; WS_BIND="0.0.0.0:${np}"; WS_PORT="$np"
            info "WS sink will use 0.0.0.0:${np}."; preflight_ws_port ;;   # re-check the new choice