- README: table of differences from upstream (master), pin a release tag in the usage example, drop references to personal hosts - docs/fork-maintenance.md -> docs/maintenance.md: rewritten from a tracking note into a record of what was removed and an ongoing maintenance guide (mempool signers, per-release checklist) - CLAUDE.md: branch layout, tag a release after consumer-facing changes (v0.MINOR.PATCH), how to check changes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.6 KiB
nix-bitcoin (satstack fork)
NixOS modules for a Bitcoin node running bitcoind, lnd, electrs and mempool, with Tor onion services and host-generated secrets.
This is a trimmed fork of fort-nix/nix-bitcoin,
which was archived in August 2026. Upstream's tree is preserved on the
master branch. Development happens on main, and releases are tagged
from main, starting at v0.1.0.
How it differs from upstream
Upstream (master) |
This fork (main) |
|
|---|---|---|
| Services | ~20: bitcoind, lnd, clightning (+ plugins, REST, replication), electrs, fulcrum, mempool, btcpayserver, rtl, joinmarket, liquid, loop, pool, charge-lnd, lndconnect, hardware wallets… | bitcoind, lnd, electrs, mempool |
| Support features | netns-isolation, i2p, backups, config versioning and obsolete-option migrations, krops/nixops deployment | Tor onion services, generated secrets, operator user, systemd hardening, nodeinfo |
| Presets | secure-node, enable-tor, hardened, wireguard, … |
None: set the options you want in your own config |
| Flake inputs | nixpkgs, nixpkgs-unstable, nixpkgs-25_05, flake-utils, extra-container | nixpkgs only |
| Packages | Pinned set: lnd and others from unstable, clightning plugins, python packages, an old bitcoind, its own lndinit… | Everything from your nixpkgs, except mempool, which is built here |
| Flake outputs | nixosModules, overlays, packages, legacyPackages, lib, templates, tests |
nixosModules.default, overlays.default, packages.mempool-* |
| Tests, docs, examples, dev shell, release signing | Yes | Removed |
The code that's left is about 2,300 lines, down from about 16,500. The modules that remain keep upstream's option names, so a config that only uses those four services should carry over once it stops importing presets and stops setting removed options. See docs/maintenance.md for the full list of what was removed and how the fork is maintained.
Usage
Pin a release tag. The repo's default branch is still upstream's master.
# flake.nix
inputs.nix-bitcoin = {
url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git?ref=refs/tags/v0.1.0";
inputs.nixpkgs.follows = "nixpkgs";
};
# in a nixosSystem's modules
inputs.nix-bitcoin.nixosModules.default
{
nix-bitcoin = {
generateSecrets = true; # writes /etc/nix-bitcoin-secrets on the host
operator = { enable = true; name = "alice"; };
nodeinfo.enable = true;
onionServices.bitcoind.public = true;
};
services.tor = { enable = true; client.enable = true; };
services.bitcoind = { enable = true; tor.proxy = true; };
services.lnd.enable = true;
services.electrs.enable = true;
services.mempool.enable = true; # also enables electrs
}
Packages come from the consumer's nixpkgs (pkgs.bitcoind, pkgs.lnd,
pkgs.electrs, pkgs.lndinit). The only package built here is mempool
(pkgs/mempool/).
What's in the repo
| Path | Contents |
|---|---|
modules/ |
bitcoind, lnd, electrs, mempool, plus secrets/, operator, security, onion-services, onion-addresses, nodeinfo |
pkgs/mempool/ |
mempool backend, frontend, rust-gbt and nginx config. generate.sh bumps the version, verifies the release signature and refreshes hashes |
pkgs/lib.nix |
systemd hardening and Tor helpers shared by the modules |
helper/update-fixed-output-derivation.sh |
Used by generate.sh to recompute hashes |
There is no test suite. Build your host's system before switching to a
new release, and roll back (nixos-rebuild switch --rollback) if a
service fails at runtime.
License
MIT, see LICENSE.