84fc4d48d3
b4d7e1aa8f4ed6db1da1486c95016f266731be03 add dev helper and docs (Erik Arvstedt)
b35d08d3f2b13b74bd9e5c2bc2ec9626ae881829 docs: move test docs from `examples/README` to `test/README` (Erik Arvstedt)
4d76eb9183d5346b94ec8659438b9c467c70ce5d docs/configuration: fix typo (Erik Arvstedt)
dc0710f3f48d9c16af9e2d78ff0b018e7c60550d tests: add example scenario `customTest` (Erik Arvstedt)
9e30d2728b9e6ebef556b6b8267971878556cc25 tests: formatting (Erik Arvstedt)
c6d85c6fe389e15d82b72774aa256cabc1aac1d1 tests: fix broken unit file when clightning is disabled (Erik Arvstedt)
a51f7b419e0e65dc47c945ad775891656b758986 run-tests: use arg instead of env var for scenario overrides (Erik Arvstedt)
Pull request description:
ACKs for top commit:
jonasnick:
ACK b4d7e1aa8f4ed6db1da1486c95016f266731be03
Tree-SHA512: f0ed8f8fe326c64eac3b7e9f48597dd00eedb9244333e199d18d1c2c06f369cd015f77aefd48e87235a68aee0b352057249525bf015e0a564fda380bdf7bb9d1
Examples
The easiest way to try out nix-bitcoin is to use one of the provided examples.
Flakes-based quick start
If you use a Flakes-enabled version of Nix, run the following command to start a minimal nix-bitcoin QEMU VM:
nix run github:fort-nix/nix-bitcoin/release
The VM (defined in flake.nix) runs in the terminal and has bitcoind
and clightning installed.
It leaves no traces (outside of /nix/store) on the host system.
More examples
Clone this repo and enter the examples shell:
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 nix-bitcoin test suite is also useful for exploring features.
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.