75b89f3957
- `waitfornewblock` was previously not included in the public RPC whitelist because it's reserved for testing and marked as hidden in bitcoind. - electrs changed its verbosity settings. `-vv` is now the best choice for normal usage. - bitcoind option `dataDirReadableByGroup` is now unused. Because it can be valuable for other use cases and implementing it is intricate, we're keeping it for now. - test: keep `nc` connection open because otherwise the electrs RPC server would now close the connection before sending a response. |
||
|---|---|---|
| .. | ||
| flakes | ||
| krops | ||
| nixops | ||
| qemu-vm | ||
| .gitignore | ||
| configuration.nix | ||
| deploy-container-minimal.sh | ||
| deploy-container.sh | ||
| deploy-krops.sh | ||
| deploy-qemu-vm.sh | ||
| importable-configuration.nix | ||
| krops-vm-configuration.nix | ||
| nix-bitcoin-release.nix | ||
| README.md | ||
| shell.nix | ||
| start-bash-session.sh | ||
Examples
The easiest way to try out nix-bitcoin is to use one of the provided examples.
git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/examples/
nix-shell
The following example scripts set up a nix-bitcoin node according to configuration.nix and then
shut down immediately. They leave no traces (outside of /nix/store) on the host system.
By default, configuration.nix enables bitcoind and clightning.
-
./deploy-container.shcreates a NixOS container.
This is the fastest way to set up a node.
Requires: Nix, a systemd-based Linux distro and root privileges -
./deploy-qemu-vm.shcreates a QEMU VM.
Requires: Nix, Linux -
./deploy-krops.shcreates a QEMU VM and deploys a nix-bitcoin configuration to it using krops.
Requires: Nix, Linux -
./deploy-container-minimal.shcreates a container defined by importable-configuration.nix.
You can copy and import this file to use nix-bitcoin in an existing NixOS configuration.
The configuration doesn't use the secure-node.nix preset.
Requires: Nix, a systemd-based Linux distro and root privileges
Run the examples with option --interactive or -i to start a shell for interacting with
the node:
./deploy-qemu-vm.sh -i
Tests
The internal test suite is also useful for exploring features.
The following run-tests.sh commands leave no traces (outside of /nix/store) on
the host system.
git clone https://github.com/fort-nix/nix-bitcoin
cd nix-bitcoin/test
# Run a node in a VM. No tests are executed.
./run-tests.sh vm
systemctl status bitcoind
# Run a Python test shell inside a VM node
./run-tests.sh debug
print(succeed("systemctl status bitcoind"))
run_test("bitcoind")
# Run a node in a container. Requires systemd and root privileges.
./run-tests.sh container
c systemctl status bitcoind
# Explore a single feature
./run-tests.sh --scenario electrs container
# Run a command in a container
./run-tests.sh --scenario '{
services.clightning.enable = true;
nix-bitcoin.nodeinfo.enable = true;
}' container --run c nodeinfo
See run-tests.sh for a complete documentation.
Real-world example
Check the server repo for https://nixbitcoin.org to see the configuration of a nix-bitcoin node that's used in production.
The commands in shell.nix allow you to locally run the node in a VM or container.
Flakes
Flakes make it easy to include nix-bitcoin in an existing NixOS config.
The flakes example shows how to use nix-bitcoin as an input to a system flake.
Run nix run or nix run .#vm from the nix-bitcoin root directory to start an example
nix-bitcoin node VM.
This command is defined by the nix-bitcoin flake (in flake.nix).