Console Login

Building RuView from a shallow clone with the right submodules

What breaks

RuView is a large MIT-licensed repository that turns WiFi channel state information into presence, breathing and pose data. The README offers a Docker image as the first quick-start option. I wanted to run the sensing server without Docker and without any ESP32 hardware, which is what a person evaluating the project on a plain Linux box would do. The obvious route, a shallow clone followed by cargo build, does not work. This article is about why, and the shortest repair I found.

The environment

Everything below ran in a clean container provided by the sandbox, not on a server of mine, and the results describe only that environment. Before running anything I asked the machine what it is, so that nobody has to guess which kernel, distribution and architecture the build and the tests ran on:

uname -a
Linux vm 6.18.44-fc-v726 #1 SMP PREEMPT_DYNAMIC @0 x86_64 x86_64 x86_64 GNU/Linux
cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04.5 LTS"

The machine's size matters for build times, so I asked for the core count and the memory, and quote what the two commands printed here, not a figure from memory or a specification sheet, in whole gigabytes, as free reports them:

nproc
4
free -g
Mem:              15           0          12           0           3          15

The repository facts come from the task description and not from my own checks: the latest push-triggered run of the "Continuous Integration" workflow on main concluded success. That result says nothing about how a shallow clone behaves, so I tested that myself.

First attempts

The README quick start leads with docker run, using the published ruvnet/wifi-densepose image. That is a sensible default for most readers. In this sandbox, however, the Docker command-line client exists but there is no daemon behind it, so a container cannot be started, as the client itself reports:

docker ps 2>&1 | head -2
failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory

So the container route was closed here. I cloned the repository with --depth 1, which is enough when you only want the current tree, and then tried to build the Rust sensing server from source, as the user guide describes. The workspace lives in the v2 directory, and I built only the one package I needed, in release mode:

git clone --depth 1 https://github.com/ruvnet/RuView
Cloning into 'RuView'...
cargo build --locked --release -p wifi-densepose-sensing-server
error: failed to load manifest for workspace member `/tmp/RuView/v2/crates/wifi-densepose-sensing-server`
referenced by workspace at `/tmp/RuView/v2/Cargo.toml`
failed to load manifest for dependency `wifi-densepose-rufield`
failed to load manifest for dependency `rufield-adapters`
failed to read `/tmp/RuView/vendor/rufield/crates/rufield-adapters/Cargo.toml`
No such file or directory (os error 2)

Before this build I had already installed the Rust 1.89 toolchain, because v2/rust-toolchain.toml pins channel 1.89 and the sandbox only had a newer stable. The failure is not about the compiler. It is about files that are simply not on disk.

The cause

The repository uses Git submodules for code it depends on, and the Cargo workspace refers to those directories by path. A plain git clone, shallow or not, creates the submodule directories but leaves them empty, and nothing in the build tells you that. I confirmed this in the clone I had just made, by asking Git for the state of each submodule:

git submodule status
-a802067f0444e10f267c5052119524de1b21747d v2/crates/ruforecast
-c9638faaf8ae1d910039171be487a465a5762313 v2/crates/ruv-neural
-5cc4b8625f17668e5eeede5f3d428baf143a2f7e v2/crates/ruview-swarm
-1c0eaf3f567f40b4430e99bdca78e84fe90b8e45 v2/crates/worldgraph
-b74bc035e4a3d4023665aa5479b41e938facd113 vendor/rufield
-46d816ddc4c2a8a06cd3613534a79b1d557d858b vendor/ruvector

A leading minus sign means the submodule is registered but not initialised. The full listing has ten entries (the output above shows the six that matter), and every one of them started with a minus. Four of them are Cargo workspace members under v2/crates, and two are vendored dependencies under vendor that the project's Dockerfile copies. This matches the git-clone documentation, which describes submodule fetching as something you request with --recurse-submodules. Cargo reads every workspace member manifest before it compiles anything, so an empty directory stops the build immediately, even for a single package.

Why the errors come one at a time

Cargo resolves the dependency graph of the requested package first, so the bridge crate pointing into vendor/rufield was reported first. After I fixed that, the next error named an empty workspace member. The errors arrive one layer at a time, which makes the problem look bigger than it is.

Source of truth

Three files in the repository itself, plus the Git documentation, tell us which submodules exist, which ones the server build consumes and how to fetch them. The list below gives each source and what it confirms, so you can check the claim in the file itself.

  • .gitmodules lists ten submodules with their URLs. It confirms that the empty directories are intentional and not a broken checkout.
  • docker/Dockerfile.rust is the project's own reproducible build. It builds with cargo build --locked --release -p wifi-densepose-sensing-server on rust:1.89-bookworm, and it copies v2/crates/, vendor/ruvector/ and vendor/rufield/. It does not copy the other four vendor trees, which tells us the server does not need them.
  • v2/rust-toolchain.toml pins toolchain 1.89, and its comments explain which dependencies need that version.
  • git-submodule and git-clone document that submodules are only fetched by git submodule update --init or by cloning with --recurse-submodules, and that --depth can be passed to the submodule update.

The Dockerfile is the key evidence. The Dockerfile copies those directories into its build context, so a build that follows it needs them populated. The README quick start does not mention a submodule step for a source build; I checked the quick-start text and found none, which is the gap this article fills.

Approaches compared

Clone everything recursively

git clone --recurse-submodules --shallow-submodules fetches all ten submodules at depth one. It is the simplest instruction to remember. I did not run it. The cost is bandwidth and disk: the single vendor/ruvector checkout I fetched below occupies 386 MB, and four more vendor trees would come on top of that for code the sensing server never compiles.

Initialise only the submodules the build needs

After the shallow clone, run git submodule update --init --depth 1 with an explicit list of paths. This fetches six repositories instead of ten. It needs knowledge of which six paths are required, and the Dockerfile and the Cargo errors supply that.

Skip the build and use a prebuilt artefact

The README offers a Docker image and pip install ruview. Neither was usable for what I wanted: Docker has no daemon here, and the README describes the Python wheel as breathing and heart-rate extractors plus clients, not the server I wanted. I did not install the wheel, so I make no claim about it beyond that.

Why this fix

I chose the selective submodule initialisation. It reproduces what the project's own Dockerfile consumes, so the binary I get is built from the same inputs as the published container path. It also keeps the download small, and it makes the dependency list explicit, which is useful to anyone who later wants to reproduce the build in a minimal CI job. If the six-path list proves incomplete, Cargo reports the missing path, as it did here, so the failure mode is loud and cheap.

The recursive clone would have been the lazier option, and it is a fine default on a workstation with plenty of disk. The shallow clone of the main repository stays as it is, and only the six submodules are added on top.

Step by step

Initialise the six submodules

git submodule update --init --depth 1 vendor/ruvector vendor/rufield
Submodule path 'vendor/rufield': checked out 'b74bc035e4a3d4023665aa5479b41e938facd113'
Submodule path 'vendor/ruvector': checked out '46d816ddc4c2a8a06cd3613534a79b1d557d858b'

With those two present I ran the same build again. It failed once more, this time on a different path, which is exactly the layered behaviour described in the cause section. Cargo had moved on from the dependency graph to the workspace member list and found another empty directory:

error: failed to load manifest for workspace member `/tmp/RuView/v2/crates/ruview-swarm`
failed to read `/tmp/RuView/v2/crates/ruview-swarm/Cargo.toml`
No such file or directory (os error 2)

That is the workspace-member case: Cargo wants a manifest for every member listed in v2/Cargo.toml, even for packages the server does not use. The four submodules under v2/crates therefore had to be initialised too, again with a depth of one commit:

git submodule update --init --depth 1 v2/crates/ruforecast v2/crates/ruv-neural v2/crates/ruview-swarm v2/crates/worldgraph
Submodule path 'v2/crates/ruforecast': checked out 'a802067f0444e10f267c5052119524de1b21747d'
Submodule path 'v2/crates/ruv-neural': checked out 'c9638faaf8ae1d910039171be487a465a5762313'
Submodule path 'v2/crates/ruview-swarm': checked out '5cc4b8625f17668e5eeede5f3d428baf143a2f7e'
Submodule path 'v2/crates/worldgraph': checked out '1c0eaf3f567f40b4430e99bdca78e84fe90b8e45'

Build the server

The same cargo build command as before, now with every path present, ran in the background because it takes a few minutes. It compiled 360 crates (counted from the build log) and finished with a few compiler warnings but no errors. The last line of the log reports the elapsed time on this four-core sandbox:

cargo build --locked --release -p wifi-densepose-sensing-server
    Finished `release` profile [optimized] target(s) in 4m 26s

The resulting sensing-server binary is about 8.8 MB, according to ls -la. The build used --locked, so Cargo had to take exactly the dependency versions recorded in Cargo.lock, and could not silently pick newer ones when resolving the graph.

Run it in simulated mode, with a token

The Docker entrypoint refuses to start without an API token, and the server itself enforces bearer authentication on /api/v1/* when a token is set. I generated one and started the server with the simulated source, which the user guide documents for running without hardware:

export RUVIEW_API_TOKEN=$(openssl rand -hex 32)
./target/release/sensing-server --source simulate --http-port 3000 --ws-port 3001 --ui-path ../ui

The startup log said that bearer-token enforcement was on for the API paths, and that the HTTP server listened on loopback port 3000 and the WebSocket server on port 3001. Now for a real request. The health endpoint needs no token, so I started there:

curl -s -i localhost:3000/health | head -20
HTTP/1.1 200 OK
{"clients":0,"processing":{"last_update_age_ms":9,"state":"live"},"source":"simulated","status":"ok","tick":51}

The source field says simulated, so nobody can mistake this for live sensing, and the status is ok. The interesting test for a service that exposes data about people in a room is the opposite one: does the data endpoint refuse a request that carries no token?

curl -s -i localhost:3000/api/v1/sensing/latest | head -12
HTTP/1.1 401 Unauthorized
missing or invalid bearer token (set Authorization: Bearer <RUVIEW_API_TOKEN>)

It does, with HTTP 401 and a message that names the expected header. With the token in an Authorization header, held in the shell variable H, the same endpoint returns a frame. I summarised the JSON with a short Python one-liner instead of printing the long amplitude arrays:

H="Authorization: Bearer $RUVIEW_API_TOKEN"
curl -s -H "$H" localhost:3000/api/v1/sensing/latest | python3 -c 'import sys,json; d=json.load(sys.stdin); print(sorted(d.keys())); print(d["classification"]); print(d.get("source"), d.get("vital_signs"))'
['age_ms', 'classification', 'estimated_persons', 'features', 'nodes', 'persons', 'signal_field', 'source', 'tick', 'timestamp', 'type']
{'confidence': 0.4402568975649511, 'motion_level': 'present_still', 'presence': True}
simulated None

The frame has a classification block with a presence flag, a motion level and a confidence, and the source field again says simulated. The vital_signs key is not present at the top level of this frame, so I report that as absent. Next come the UI and the node list. The dashboard page is served from the ui directory I passed, and the node list is empty, as expected without an ESP32:

curl -s -o /dev/null -w "%{http_code} %{content_type}\n" localhost:3000/ui/index.html
200 text/html
curl -s -H "$H" localhost:3000/api/v1/nodes | head -c 300
{"nodes":[],"total":0}

The tick counter in the health response was 51 on the first call and 124 on a later one a few seconds on, so the simulator is advancing and the server is not returning a frozen frame. Both calls were made a few seconds apart.

Run a test suite

A running server proves that the binary starts and answers, not that its signal code is correct. The repository has a very large workspace, so running every test was not realistic here. I picked the vitals crate, which holds the breathing and heart-rate code, and ran its tests in release mode, which reuses the build artefacts already compiled:

cargo test --locked --release -p wifi-densepose-vitals
test result: ok. 109 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.69s
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.65s

I then tried to add the signal-processing crate to the same test command, since it is the other crate behind the sensing claims. That did not work in this sandbox. A build script of the native linear-algebra dependency failed before any test could compile:

cargo test --locked --release -p wifi-densepose-vitals -p wifi-densepose-signal
error: failed to run custom build command for `openblas-src v0.10.15`

The full error text says a native TLS download failed with a self-signed certificate in the chain. I read that as the sandbox network interposing its own certificate, but I did not investigate further, so I treat the signal-crate tests as not run.

The deterministic proof script

The README also advertises a hardware-free check that replays a fixed reference signal through the Python pipeline and compares a hash with a published one. It needed no installation here, because the system Python already had the packages the script imports. It ran in a few seconds, and these are the two lines that matter:

python archive/v1/data/proof/verify.py
Status:   MATCH (bit-exact)
VERDICT: PASS

It printed a computed SHA-256 and an expected one, and they were identical. That shows the Python reference pipeline is deterministic on this machine, which is what the script claims to show. It does not say anything about the Rust server I built above, and it does not say anything about how well real WiFi signals are turned into poses or vital signs.

Short review

What worked

Initialising ten submodules is not required. Six were enough to build the sensing server with the pinned toolchain in under five minutes on four cores, and the server answered real HTTP requests, with authentication enforced and a clearly labelled simulated source. The 109 vitals unit tests passed.

Limits

Nothing here involves real CSI data, so I cannot say anything about sensing accuracy, and I tested only the simulated source. I did not open the dashboard in a browser, I did not test the WebSocket stream because the Python websockets package was not installed, and I did not run the Docker image because the sandbox has no Docker daemon. The signal crate tests did not run.

When to choose something else

On a normal workstation use git clone --recurse-submodules --shallow-submodules and avoid thinking about the list. If you only want the container, use the README Docker command, and set the token as it says. If you only need the signal processing extractors in Python, the PyPI route is probably lighter, though I did not try it. The missing step in a source build is worth reporting to the maintainers as a documentation gap.