docs: describe the fork vs upstream, add CLAUDE.md
- 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>
This commit is contained in:
@@ -4,16 +4,32 @@ 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](https://github.com/fort-nix/nix-bitcoin),
|
||||
which was archived in August 2026. Everything squirtle doesn't use has
|
||||
been removed. See [docs/fork-maintenance.md](docs/fork-maintenance.md) for
|
||||
what was cut, what's left, and the per-release checklist.
|
||||
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](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`.
|
||||
|
||||
```nix
|
||||
# flake.nix
|
||||
inputs.nix-bitcoin = {
|
||||
url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git";
|
||||
url = "git+ssh://gitea@gitea.satstack.dev/pleb/nix-bitcoin.git?ref=refs/tags/v0.1.0";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
@@ -48,12 +64,13 @@ Packages come from the consumer's nixpkgs (`pkgs.bitcoind`, `pkgs.lnd`,
|
||||
| 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 and refreshes hashes |
|
||||
| `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 squirtle in nix-pleb before switching,
|
||||
and roll back (`nixos-rebuild switch --rollback`) if a service fails at
|
||||
runtime.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user