docs(forge): the disk-full triage block measures at the bind source, not at /data (#1507) #1790

Merged
jaylouisw merged 1 commit from fix/1117-0435 into main 2026-11-17 04:51:16 +00:00
Owner

Fixes #1507 (the remaining instance of one defect on the page - the storage decision itself still needs the host).

What was wrong

The first instruction block on docs/FORGE_TROUBLESHOOTING.md, headed "On the host, in this order", told a host shell to run:

df -h /data
du -sh /data/gitea/data/tmp/local-repo/* 2>/dev/null | sort -h | tail -20

/data is the container's mount point - the page records the bind .../forgejo/data -> /data a few sections below. On the host df errors to stderr and the du, with 2>/dev/null, prints nothing and exits 0. The reader sees a blank line and concludes the failed merge attempts left nothing behind, then goes looking for space that is sitting in half-written clones. That is the empty-result-read-as-measurement mistake the later sections of this page exist to correct - #1784 and #1787 fixed it twice further down and left this occurrence, which is the first thing a reader runs.

What changed

  • the block now starts with docker inspect forgejo to name the bind, then loops the two bind sources (/mnt/cache/appdata/forgejo/data, /mnt/user/appdata/forgejo/data), printing absent: <path> for a candidate that is not there instead of nothing;
  • df and the du run at $base / $tmp, where a host shell can see them; the 2>/dev/null now only silences a glob whose directory was already proved to exist, so silence means "empty", not "wrong path";
  • one sentence notes that a /mnt/user/... bind is the FUSE view, so its df reports the shfs pool and not the disk.

Tests

test/forge-space-accounting.test.js - 29 assertions, 0 failed (was 22; 7 new). Four of the new ones are red against origin/main's copy of the page. The block is anchored on its unique preceding paragraph, because two sections open with the same sentence and the first version of these assertions read the wrong one.

Gates: scripts/syntax-check.js 374 files OK; scripts/check-control-bytes.js clean; scripts/check-doc-citations.js clean apart from the two known suspects in SIMULATION.md/UPSTREAM-DESIGN.md. Engine code untouched, so no full suite.

Refs #1507 (still blocked on the host: ssh odin now demands a Tailscale SSH browser check, so the du that says which volume holds the 47 GiB cannot be run from here).

Fixes #1507 (the remaining instance of one defect on the page - the storage decision itself still needs the host). ## What was wrong The first instruction block on `docs/FORGE_TROUBLESHOOTING.md`, headed *"On the host, in this order"*, told a host shell to run: ```bash df -h /data du -sh /data/gitea/data/tmp/local-repo/* 2>/dev/null | sort -h | tail -20 ``` `/data` is the **container's** mount point - the page records the bind `.../forgejo/data -> /data` a few sections below. On the host `df` errors to stderr and the `du`, with `2>/dev/null`, prints nothing and exits 0. The reader sees a blank line and concludes the failed merge attempts left nothing behind, then goes looking for space that is sitting in half-written clones. That is the empty-result-read-as-measurement mistake the later sections of this page exist to correct - #1784 and #1787 fixed it twice further down and left this occurrence, which is the *first* thing a reader runs. ## What changed - the block now starts with `docker inspect forgejo` to name the bind, then loops the two bind sources (`/mnt/cache/appdata/forgejo/data`, `/mnt/user/appdata/forgejo/data`), printing `absent: <path>` for a candidate that is not there instead of nothing; - `df` and the `du` run at `$base` / `$tmp`, where a host shell can see them; the `2>/dev/null` now only silences a glob whose directory was already proved to exist, so silence means "empty", not "wrong path"; - one sentence notes that a `/mnt/user/...` bind is the FUSE view, so its `df` reports the shfs pool and not the disk. ## Tests `test/forge-space-accounting.test.js` - **29 assertions, 0 failed** (was 22; 7 new). Four of the new ones are red against `origin/main`'s copy of the page. The block is anchored on its unique preceding paragraph, because two sections open with the same sentence and the first version of these assertions read the wrong one. Gates: `scripts/syntax-check.js` 374 files OK; `scripts/check-control-bytes.js` clean; `scripts/check-doc-citations.js` clean apart from the two known suspects in `SIMULATION.md`/`UPSTREAM-DESIGN.md`. Engine code untouched, so no full suite. Refs #1507 (still blocked on the host: `ssh odin` now demands a Tailscale SSH browser check, so the `du` that says which volume holds the 47 GiB cannot be run from here).
docs(forge): the disk-full triage block measures at the bind, not at /data (#1507)
All checks were successful
CI / Classify the change (pull_request) Successful in 8s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Server smoke test (pull_request) Successful in 10s
CI / Docker build (pull_request) Successful in 24s
CI / Test (Node 20) (pull_request) Successful in 53s
CI / Test (Node 22) (pull_request) Successful in 1m1s
CI / Test (Node 18) (pull_request) Successful in 1m5s
CI / Arm auto-merge (pull_request) Successful in 6s
54db42aef4
The first block on the page, headed "On the host, in this order", opened with
`df -h /data` and a `du` at `/data/gitea/data/tmp/local-repo/*` silenced with
`2>/dev/null`. /data is the container's mount point - the page records the bind
.../forgejo/data -> /data a few sections below - so on a host `df` errors to
stderr and the `du` prints nothing at all. A reader concludes the failed merge
attempts left nothing behind, and goes looking for space that is sitting in
half-clones: the empty-result-as-measurement mistake the later sections fix.

Probe the two bind sources, echo `absent: <path>` instead of silence, and name
the drvfs/FUSE caveat so `df` on /mnt/user is not read as the disk. The tests
anchor on this block now (two sections open with the same sentence) and were red
on the previous page: 4 of 29.
jaylouisw force-pushed fix/1117-0435 from 54db42aef4
All checks were successful
CI / Classify the change (pull_request) Successful in 8s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 13s
CI / Server smoke test (pull_request) Successful in 10s
CI / Docker build (pull_request) Successful in 24s
CI / Test (Node 20) (pull_request) Successful in 53s
CI / Test (Node 22) (pull_request) Successful in 1m1s
CI / Test (Node 18) (pull_request) Successful in 1m5s
CI / Arm auto-merge (pull_request) Successful in 6s
to 0da80fdc78
All checks were successful
CI / Classify the change (pull_request) Successful in 47s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 25s
CI / Server smoke test (pull_request) Successful in 7s
CI / Test (Node 20) (pull_request) Successful in 44s
CI / Test (Node 18) (pull_request) Successful in 52s
CI / Docker build (pull_request) Successful in 23s
CI / Test (Node 22) (pull_request) Successful in 48s
CI / Arm auto-merge (pull_request) Successful in 7s
2026-11-17 04:42:09 +00:00
Compare
jaylouisw force-pushed fix/1117-0435 from 0da80fdc78
All checks were successful
CI / Classify the change (pull_request) Successful in 47s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 25s
CI / Server smoke test (pull_request) Successful in 7s
CI / Test (Node 20) (pull_request) Successful in 44s
CI / Test (Node 18) (pull_request) Successful in 52s
CI / Docker build (pull_request) Successful in 23s
CI / Test (Node 22) (pull_request) Successful in 48s
CI / Arm auto-merge (pull_request) Successful in 7s
to 3ce432b3b2
All checks were successful
CI / Classify the change (pull_request) Successful in 9s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 7s
CI / Server smoke test (pull_request) Successful in 10s
CI / Docker build (pull_request) Successful in 24s
CI / Test (Node 20) (pull_request) Successful in 54s
CI / Test (Node 22) (pull_request) Successful in 58s
CI / Test (Node 18) (pull_request) Successful in 1m3s
CI / Arm auto-merge (pull_request) Successful in 21s
2026-11-17 04:45:50 +00:00
Compare
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1790
No description provided.