nix-bitcoin/examples/README.md
Jonas Nick e86d1ff0ff
Merge fort-nix/nix-bitcoin#399: examples: Fix shell on non-Linux systems
46af0b1a8d examples: fix shell on non-Linux systems (Erik Arvstedt)

Pull request description:

ACKs for top commit:
  jonasnick:
    ACK 46af0b1a8d

Tree-SHA512: bc3c24c75b2d26a30f9f4f88700da8a78d8276802b47ddaf3d52097ba6ed16a7b7ca662085e2775a2cd1654b07c1759c36918ee0ab05eb90fbfeac3265576510
2021-09-27 09:14:44 +00:00

3.1 KiB

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.

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).