edbaeb9813
Advantages: - Pure test evaluations - The test framework can now be used by flakes that extend nix-bitcoin - Most features of `run-tests.sh` are now accessible via `nix build`/`nix run`. We keep `run-tests.sh` for advanced features like `scenarioOverridesFile` and adhoc scenarios. Other changes: - `run-tests.sh` now builds aggregate VM tests like `basic` or `buildable` by creating all VMs in a single evaluation. This speeds up the tests and eases debugging by separating the eval and build steps. - Use the new `nix` CLI which has improved build output logging by prefixing output lines with the origin drv name. |
||
---|---|---|
.. | ||
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.
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.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.
run-tests.sh
requires Nix >= 2.10.
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.
Flakes
Tests can also be directly accessed via Flakes:
# Build test
nix build --no-link ..#tests.default
# Run a node in a VM. No tests are executed.
nix run ..#tests.default.vm
# Run a Python test shell inside a VM node
nix run ..#tests.default.run -- --debug
# Run a node in a container. Requires extra-container, systemd and root privileges
nix run ..#tests.default.container
nix run ..#tests.default.containerLegacy # For NixOS with `system.stateVersion` <22.05
# Run a command in a container
nix run ..#tests.default.container -- --run c nodeinfo
nix run ..#tests.default.containerLegacy -- --run c nodeinfo # For NixOS with `system.stateVersion` <22.05
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.