Narrative pass over troubleshooting.md against the code. Seven claims were
wrong, several of them actively misleading:
- **Tor is not a container.** §15/§16 told operators to run
`podman ps --filter name=tor` / `podman restart tor` and to read
`/var/lib/archipelago/tor/hidden_service/hostname`. Tor is the host's Debian
package running as `debian-tor`; Archipelago drives it by staging a torrc and
poking `archipelago-tor-helper` (`scripts/tor-helper.sh`, which does
`systemctl restart tor`). The hidden-service dir is
`hidden_service_archipelago` (suffixed), it's root-owned 0700, and the file a
normal user can actually read is the synced copy at
`/var/lib/archipelago/tor-hostnames/<service>`.
- **The USB installer has no "Repair" mode.** Cited three times as the recovery
path. The boot menu has exactly three entries: Install, Install (verbose),
Boot from local disk. Replaced with what those entries can actually do, plus
the fact that the installer prompts for a disk and requires typing `yes`, so
booting it isn't itself destructive.
- **`bitcoin-cli -datadir=/data`** — the container's datadir is
`/home/bitcoin/.bitcoin` and RPC creds are in a generated `/tmp/rpc.conf`;
the documented command could not have authenticated.
- **"edit bitcoin.conf to add addnode="** — the entrypoint passes an explicit
`-conf` and logs "ignoring legacy datadir bitcoin.conf". Flags come from the
manifest (and the signed catalog entry that overrides it).
- **"Bitcoin requires 600GB+"** — only above the manifest's 1000 GB threshold;
below it the node runs pruned at `-prune=550`.
- **`sudo systemctl restart podman`** — apps run under rootless Podman as the
`archipelago` user, so that restarts an unrelated root socket.
- **"Settings > Network"** — DNS config and disk cleanup are both on the Server
page (`/server`), not Settings.
Also: header claimed "the 20 most common issues" over 21 sections, and §16
presented Tor as required for peering when it's the last fallback after
mesh → LAN → FIPS.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The walkthrough told new users to log in with `password123` and said they'd
be "prompted to change this password immediately". Neither is true on a
release build:
- `AuthManager::ensure_default_user` is never called. `main.rs:356-362`
says so explicitly ("Don't auto-create default user — let onboarding flow
handle password setup via auth.setup"), and the function is `#[allow(dead_code)]`.
- The only `password123` login path is `api/rpc/auth.rs:36-46`, which is
`#[cfg(debug_assertions)]` AND `dev_mode` AND only fires *before* setup —
no release binary carries it.
- `Login.vue` calls `auth.isSetup` on mount and renders the "Set Up Your
Node" password-creation form when it returns false. That is the real
first-boot screen, and it is the only `auth.setup` caller in the frontend.
So there is nothing to be "prompted to change" — the user creates the
password themselves, and the doc's version taught them to look for a
default that does not exist.
Fixed in four places:
- user-walkthrough Step 8 rewritten as "Create Your Password"
- troubleshooting's "Default password is password123" solution replaced,
including the warning that deleting user.json does NOT recover a lost
password (the onboarding gate refuses auth.setup on a provisioned node)
- api-reference cURL example uses a placeholder, not the fake default
- 1.8.0 hardening plan's "kill default credentials" item now reflects that
the web half is done and only the SSH defaults still ship
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three real incidents from live-testing the flash feature on archy-x250-dev,
each traced through logs on the node and fixed at the root:
- A failed flash left the mesh listener auto-resuming into a reconnect loop
whose backoff reset to its 5s minimum on any momentary connection, even
mid-boot-loop — every retry's open() toggles DTR/RTS, which resets many
ESP32 boards, so the retries were themselves sustaining the loop. Backoff
now only resets after a session runs stably for 20s+, and the flash job
no longer auto-resumes the listener after a failure (only on success,
after a settle delay).
- The HTTP client's blanket 30s request timeout covered entire downloads
(Meshtastic's zip is ~170MB), killing large transfers mid-stream; fixed
with a per-chunk stall timeout instead of a fixed total-transfer cap. But
the download's initial request had no timeout at all, so a slow-to-start
server hung it forever — wedging the single-flash-job guard permanently
("already in progress" on every subsequent attempt). Fixed with a bounded
wait for the response to start, plus an absolute ceiling around the whole
job as a last-resort safety net.
- archy-rnodeconf's PyInstaller freeze broke its own internal esptool
invocation (sys.executable pointed at the frozen binary itself instead of
a real interpreter) — fixed via a new runtime hook. esptool's own
auto-reset-into-bootloader handshake is separately known to be flaky on
some CP2102/CH340 boards; it now retries once at a conservative baud
rate instead of failing outright, and failure logs show the full error
chain instead of just the outer context message.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- operations-runbook: redact the plaintext sudo password (rotate it — it
stays in git history); replace the nonexistent test-cross-node.sh /
test-reboot-survival.sh with the real entry points (lifecycle gate,
multinode smoke, e2e/post-install scripts)
- hotfix-process: de-hardcode the v1.0.x framing, point releases at
create-release.sh + primary Gitea, correct the rollback backup paths
(/opt/archipelago/rollback + updater backup dir, not /usr/local/bin)
- troubleshooting: connectivity probe start9.com -> debian.org
- INSTALL.sh: drop removed endurain app, point at developer-guide.md
(development-setup.md never existed)
- tests/lifecycle/TESTING.md: replace the stale 2026-06-21 mid-session
resume block with a resolved note; release-gate item 8 reflects the
2026-07-08 version decision (1.8.0-alpha)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
20 issues covering connection, apps, Bitcoin sync, backup, updates,
kiosk mode, network, performance, and emergency recovery. Each with
diagnostic commands and step-by-step solutions.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ssmithxandClaude Sonnet 5