nix-bitcoin

History

Jonas Nick ebaa9a3f2e Merge fort-nix/nix-bitcoin#484 : Update RTL `3755b3ebea` rtl: add option `extraConfig` for nodes (Erik Arvstedt) `ff228a604d` rtl: change `nodes` options (Erik Arvstedt) `beae9f8df7` clightning-rest: 0.7.0 -> 0.7.2 (Erik Arvstedt) `4c2d908a38` rtl: 0.12.2-beta -> 0.12.3-beta (Erik Arvstedt) Pull request description: ACKs for top commit: nixbitcoin: ACK `3755b3ebea` Tree-SHA512: 21b413473792802a49694427dd488d7ba0575bb79297b8cd3d3e09707f0389fa4a65ed18eea11af167e1f42154f43685a7afc0829b769dea4b8d64007dcd7be5		2022-05-25 19:48:42 +00:00
..
flakes	add `release` branch	2022-05-06 16:49:31 +02:00
krops	examples: add krops deployment method	2021-03-15 18:53:07 +01:00
nixops	Remove nixops examples and documentation	2021-03-15 12:42:47 +00:00
qemu-vm	treewide: use services.getty option	2021-08-14 10:46:40 +02:00
.gitignore	docs: various improvements to installation tutorial	2021-03-15 19:02:58 +01:00
configuration.nix	Merge fort-nix/nix-bitcoin#484 : Update RTL	2022-05-25 19:48:42 +00:00
deploy-container-minimal.sh	examples: add importable-configuration.nix	2021-09-26 22:34:39 +02:00
deploy-container.sh	examples: add importable-configuration.nix	2021-09-26 22:34:39 +02:00
deploy-krops.sh	examples: improve robustness of deploy scripts	2021-03-16 12:46:18 +01:00
deploy-qemu-vm.sh	examples: improve robustness of deploy scripts	2021-03-16 12:46:18 +01:00
importable-configuration.nix	examples: add importable-configuration.nix	2021-09-26 22:34:39 +02:00
krops-vm-configuration.nix	examples: add deploy-krops.sh	2021-03-15 19:02:58 +01:00
nix-bitcoin-release.nix	Add fetch-release script	2020-04-08 07:01:35 +00:00
README.md	Merge fort-nix/nix-bitcoin#399 : examples: Fix shell on non-Linux systems	2021-09-27 09:14:44 +00:00
shell.nix	examples/shell.nix: Add shell version variable	2021-09-15 12:22:10 +02:00
start-bash-session.sh	examples: add option --interactive\|-i	2020-10-18 13:42:58 +02:00

README.md

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.sh creates 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.sh creates a QEMU VM.
Requires: Nix, Linux
./deploy-krops.sh creates a QEMU VM and deploys a nix-bitcoin configuration to it using krops.
Requires: Nix, Linux
./deploy-container-minimal.sh creates 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).