docs(readme): fix broken no-hardware Docker quickstart#1216
Open
dapos-tech wants to merge 1 commit into
Open
Conversation
The advertised "Option 1: Docker (simulated data, no hardware needed)" command exits immediately on a clean machine, which is the most common "can't get it to work" complaint (ruvnet#1125, ruvnet#509, ruvnet#951, ruvnet#301). Reproduced on a fresh pull of ruvnet/wifi-densepose:latest: $ docker run -p 3000:3000 ruvnet/wifi-densepose:latest [entrypoint] ERROR: refusing to start sensing-server ... exit 64 Three compounding issues for a no-hardware user: 1. Auth guard (ruvnet#864) refuses a 0.0.0.0 bind without a token -> exit 64 2. CSI_SOURCE defaults to `auto`, which fails loud (ruvnet#937) with no ESP32/NIC detected -> exit 78. "simulated" must be explicit. 3. The WebSocket port (3001) was not published, so the live /ws/sensing stream was unreachable; the UI lives at /ui/index.html, not /. Fix: document the verified working invocation (both env vars, both ports, correct URL). Confirmed end-to-end: container exit=0, UI HTTP 200, /api/v1/sensing/latest returns presence data, and live frames stream over ws://localhost:3001/ws/sensing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The headline "Option 1: Docker (simulated data, no hardware needed)" command in the README does not run on a clean machine. This appears to be the single most common "can't get it to work" complaint (#1125, #509, #951, #301).
Reproduced on a fresh pull of
ruvnet/wifi-densepose:latest:Three compounding issues for a no-hardware evaluator:
0.0.0.0bind without a token → exit 64 (fires first, so the command never even starts).CSI_SOURCEdefaults toauto, which fails loud (cognitum-csi-capture unit ships with --simulate (synthetic CSI) by default #937) when no ESP32/NIC is detected → exit 78. For the simulated demo it must be set explicitly.3001was not published, so the live/ws/sensingstream is unreachable, and the UI is served at/ui/index.html, not/.Fix
Document the verified working invocation — both required env vars, both ports, and the correct URL — with short inline notes pointing at the relevant issues so the security/fail-loud posture is explained rather than just worked around.
Verification
Ran the newly documented command verbatim on a fresh container:
exit=0(stays up)GET /ui/index.html→ HTTP 200GET /api/v1/sensing/latest→{"classification":{"presence":true,...},"estimated_persons":1,...}sensing_updateframes stream overws://localhost:3001/ws/sensingNo code changes — README only.
🤖 Generated with Claude Code