docs: make the install-and-run path work on a clean machine - #50
Merged
Conversation
…at work Every command on the install path was executed against the live artifacts and verified against the shipped installer and packaging sources. Four documented claims did not hold, and the corrections differ per install route: - The one-line install needs elevation. The default plan registers the dig-node and dig-dns services and writes into a protected install root, so an unelevated run is refused before anything is downloaded, and the bootstrap script does not elevate itself. Document `| sudo sh` and, on Windows, an elevated PowerShell. - The systemd unit id depends on the route: the apt package registers `dig-node.service`, the native .deb/.pkg/.msi register `net.dignetwork.dig-node`, and the DIG Installer registers `dignetwork-dig-node` in the user scope. Replace the single wrong id with a per-route table, and note that a user-scope unit needs a login session. - The `dign` and `digd` aliases come only from the DIG Installer. The apt packages and the native OS packages carry neither, so the apt page no longer promises them and instead states exactly what it installs. - apt trails the current releases and publishes no arm64 dig-node, so the apt page leads with what it serves today and points elsewhere for a current node. Also drops the stale not-yet-provisioned notes now that install.sh, install.ps1 and apt.dig.net all serve real artifacts; removes the claims that the installer runs the native OS packages and that the apt package registers the chia:// scheme handler; adds a first-fetch check against a live store plus the scriptable `dign status --json` alternative; and documents the X-Dig-Store response header as a machine-readable way to resolve a subdomain to its store. A new unit lint pins each corrected command across every page and all fourteen locale copies. Its rules are universally quantified on purpose: a single missed occurrence fails, rather than being masked by a corrected occurrence elsewhere, which is how several of these claims survived earlier passes. Version: patch. Documentation corrections with no new site capability — the X-Dig-Store section documents a header that already ships. Co-Authored-By: Claude <noreply@anthropic.com>
MichaelTaylor3d
force-pushed
the
docs/1725-install-path-truth
branch
from
July 28, 2026 10:02
72da6bb to
949617f
Compare
MichaelTaylor3d
marked this pull request as ready for review
July 28, 2026 10:03
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
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.
Makes every command on the docs.dig.net install-and-run path work on a clean machine.
Tracking: DIG-Network/dig_ecosystem#1725, DIG-Network/dig_ecosystem#848
What changed, and why each claim was wrong
Every correction was verified against the shipped installer/packaging sources and the live artifacts, not inferred.
1. The one-line install needs elevation.
dig-installer's CLI computeswith_dig_node = cli.with_dig_node || !cli.no_dig_node, so a bare run selects dig-node, which makesrequires_elevation()true and refuses the run before downloading anything.install.shcontains no self-elevation (nosudo/EUID/id -uanywhere in the 2612 bytes served). Documented as| sudo sh, and an elevated PowerShell on Windows.2. The systemd unit id is route-dependent — three different names. The previous single id was wrong for two of the three routes:
dig-node.servicepackaging/build-deb.shnames the unit$pkg.service;postinstrunssystemctl enable --now dig-node.service.deb/.pkg/.msinet.dignetwork.dig-nodepackaging/linux/build-deb.sh,packaging/macos/*.plistdignetwork-dig-node, user scopeservice-manager's systemd backend names the unit fromto_script_name(), dropping the reverse-DNS qualifierThe DIG Installer runs
dig-node install(not the native packages), and that path prefers user-level systemd, so its unit lives in the user scope and needs a login session. The page now says so and points headless servers at the system-service routes.3.
dign/digdcome only from the DIG Installer. The aptdig-nodepackage sets noEXTRA_BINS, and the native.deb/.pkg/.msieach install only thedig-nodebinary plus its service. The apt page no longer promises the aliases and states what it does install.4. apt is behind and x86-64 only. Live
dists/stable/main/binary-{amd64,arm64}/Packages:dig-node0.43.0 (current 0.64.0) amd64 only,dig-store0.17.0 (current 0.19.3). Thearm64index carries nodig-nodeat all. The apt page now leads with that table so a reader can choose knowingly.Also removed: the not-yet-provisioned notes (install.sh, install.ps1 and apt.dig.net all serve real artifacts now), the claim that the installer runs the native OS packages, and the claim that the apt package registers the
chia://scheme handler.Added: a first-fetch check against a live store, the scriptable
dign status --jsonalternative, and theX-Dig-Storeresponse header as a machine-readable way to resolve a subdomain to its store.Blast radius checked
Docs-only content plus one new test file — no exported symbol, script, or generated contract changed. Swept the whole
docs/tree for every install command, every service/unit id, every alias promise, and every provisioning caveat; the four residualnet.dignetworkoccurrences are the rows where it is correct.static/openrpc*.jsonchanged only in their version field, regenerated bynpm run gen(drift gate passed). The machine-spec drift gate, the error catalog, and the RPC tables are untouched.Verification
Executed:
install.sh/install.ps1— HTTP 200,text/x-shellscript/text/plain, and the servedinstall.shis byte-identical to the repo'smain.Release+ bothPackagesindexes, and thedig.gpgsigning key (1709-byte armored key, so the apt setup steps work).curl -sI https://chia-offer.on.dig.net/ | grep -i '^x-dig-'— the documented command, verbatim, producing the documented output.X-Dig-Storematches the catalog exactly.npm run test:unit— 28 pass, 0 fail.npm run build— green, all 14 locales, broken-link check included.npm run typecheck,npm run lint— clean.Not executed (no Linux/macOS/Windows target available): the install commands themselves. Their correctness rests on the installer's own elevation logic and packaging sources, cited above. Unverified-by-execution items are called out in the lane report rather than presented as tested.
The new lint was proved load-bearing by reverting fixes individually on a committed tree: reverting the
sudoon one page alone fails it (2 of 3 rules) even though the other four pages remain correct, and reverting the apt unit id alone fails all 3.Version
Patch —
0.7.1to0.7.2. Documentation corrections with no new site capability; theX-Dig-Storesection documents a header that already ships.