Skip to content

docs: make the install-and-run path work on a clean machine - #50

Merged
MichaelTaylor3d merged 1 commit into
mainfrom
docs/1725-install-path-truth
Jul 28, 2026
Merged

docs: make the install-and-run path work on a clean machine#50
MichaelTaylor3d merged 1 commit into
mainfrom
docs/1725-install-path-truth

Conversation

@MichaelTaylor3d

@MichaelTaylor3d MichaelTaylor3d commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

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 computes with_dig_node = cli.with_dig_node || !cli.no_dig_node, so a bare run selects dig-node, which makes requires_elevation() true and refuses the run before downloading anything. install.sh contains no self-elevation (no sudo/EUID/id -u anywhere 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:

Route Unit / service id Source
apt repository dig-node.service apt.dig.net packaging/build-deb.sh names the unit $pkg.service; postinst runs systemctl enable --now dig-node.service
native .deb/.pkg/.msi net.dignetwork.dig-node dig-node packaging/linux/build-deb.sh, packaging/macos/*.plist
DIG Installer dignetwork-dig-node, user scope service-manager's systemd backend names the unit from to_script_name(), dropping the reverse-DNS qualifier

The 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/digd come only from the DIG Installer. The apt dig-node package sets no EXTRA_BINS, and the native .deb/.pkg/.msi each install only the dig-node binary 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-node 0.43.0 (current 0.64.0) amd64 only, dig-store 0.17.0 (current 0.19.3). The arm64 index carries no dig-node at 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 --json alternative, and the X-Dig-Store response 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 residual net.dignetwork occurrences are the rows where it is correct. static/openrpc*.json changed only in their version field, regenerated by npm 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 served install.sh is byte-identical to the repo's main.
  • apt Release + both Packages indexes, and the dig.gpg signing 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.
  • Both catalog storeIds resolve and their X-Dig-Store matches 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 sudo on 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.1 to 0.7.2. Documentation corrections with no new site capability; the X-Dig-Store section documents a header that already ships.

…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
MichaelTaylor3d force-pushed the docs/1725-install-path-truth branch from 72da6bb to 949617f Compare July 28, 2026 10:02
@MichaelTaylor3d
MichaelTaylor3d marked this pull request as ready for review July 28, 2026 10:03
@MichaelTaylor3d
MichaelTaylor3d merged commit 9faadbb into main Jul 28, 2026
8 checks passed
@MichaelTaylor3d
MichaelTaylor3d deleted the docs/1725-install-path-truth branch July 28, 2026 10:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant