docs: document Nix as a supported install method - #172
Merged
Merged
Conversation
Nix support landed in freenet-core#5679: `nix run github:freenet/freenet-core` gives a supervised, self-updating peer that uses the same signed release channel and the same crash-loop rollback as every other install method. Two pages: - `/nix/` — the install guide. Leads with the command, states plainly that the peer updates itself, and distinguishes the two flake outputs, because only one of them runs a peer. `packages.freenet` is a build artifact with no supervisor; a peer started from it falls behind and eventually stops working, so the page says that rather than hedging it. - A one-line pointer in `/quickstart/`, after the OS install tabs. A NixOS user who sees only macOS/Linux/Windows concludes Nix is unsupported and builds it themselves, which is how you get an unsupervised peer. A fourth tab would be wrong (Nix runs *on* Linux and macOS) and would clutter the consumer flow, so a pointer rather than a tab. Two things the page is deliberate about: - It tells operators to install from a release TAG, not the default branch. The default branch can carry an unpublished version number, and a peer that starts ahead of every published release will not update until one overtakes it. - The NixOS snippet sets `home` on the service user. The node keeps its auto-update state (probation marker, rollback snapshot, known-bad pin) under the service user's HOME, not under $STATE_DIRECTORY. A user declared without `home` gets /var/empty, which is not writable, and the peer then runs with crash-loop rollback silently off. Detail is linked to docs/nix.md in freenet-core rather than duplicated, so there is one canonical copy to keep current.
…ackage
The page told users to run tag vX.Y.Z and to reference pkgs.freenet-node
without saying where it comes from. Name a real tag, show the flake input
wiring via specialArgs (matching the ${freenet-node} name docs/nix.md
uses), and link to the canonical unit instead of carrying a second,
already-drifted copy of it.
Claude-Session: https://claude.ai/code/session_016xwEnj4eizFJUpd1bPwPQa
sanity
force-pushed
the
docs/nix-install
branch
from
September 28, 2026 15:39
b9ffd82 to
a1bbf47
Compare
outputs takes nixpkgs but the example never declared it, so a verbatim copy failed to evaluate. Verified by evaluating the snippet together with the docs/nix.md unit: ExecStart resolves to the flake's freenet-node. Claude-Session: https://claude.ai/code/session_016xwEnj4eizFJUpd1bPwPQa
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
1 participant
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.
Document Nix as a supported install method
Nix support landed in freenet-core#5679.
nix run github:freenet/freenet-corenow gives a supervised, self-updating peer that uses the same signed release channel, the same crash-loop rollback and the same known-bad pinning as every other install method.Verified end to end before writing this: a real published v0.2.134 was seeded through the wrapper, detected the new release, exited 42, was updated in place by the node's own signature-verifying updater, and came back running 0.2.135 unattended.
Two pages
/nix/— the install guide. Leads with the command, states plainly that the peer updates itself, and separates the two flake outputs, because only one of them runs a peer.packages.freenetis a build artifact with no supervisor, so a peer started from it falls behind and eventually stops working. The page says that rather than hedging it.A one-line pointer in
/quickstart/, immediately after the OS install tabs. A NixOS user who sees only macOS/Linux/Windows concludes Nix is unsupported and builds it themselves, which is exactly how you end up with an unsupervised peer. A fourth tab would be wrong (Nix runs on Linux and macOS, it is not an alternative to them) and would clutter the consumer flow, so it is a pointer rather than a tab.Two things the page is deliberate about
Install from a release tag, not the default branch. The default branch can carry a version number that has not been published yet, and a peer that starts out ahead of every published release will not update until one overtakes it.
NixOS users get the flake wiring, and the unit by link. The page shows how to add freenet-core as a flake input and pass
freenet.packages.<system>.freenet-nodeinto the configuration viaspecialArgs, then links to the canonical unit indocs/nix.mdrather than carrying a second copy of it. An earlier draft had its own copy, which had already drifted (nostartLimitIntervalSec, no network-online ordering, no explicit directories). The package is used rather than the flake overlay because the overlay builds with the consumer's nixpkgs Rust rather than the pinned toolchain. The snippet plus the canonical unit was checked by evaluating it with Nix:ExecStartresolves to the flake'sfreenet-node.On duplication
The canonical detail stays in
docs/nix.mdin freenet-core and is linked, not copied.install.shalready has to be hand-synced between the two repos and that has caused drift before, so there is deliberately one copy of the deep material rather than three.Release tag
The flake first shipped in v0.2.136, so the hold on this PR is lifted. The page names v0.2.139 (latest at the time of writing). It does not need to track releases: a peer seeded from any tag at or after v0.2.136 updates itself on first run.
[AI-assisted - Claude]