You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
nix-bitcoin/examples
Otto Sabart f3f8d650ab
shellcheck: fix the lint warnings for other generated scripts
6 months ago
..
flakes flake: use new output format 10 months ago
krops examples/krops: fix nixpkgs symlink sync error on macOS/BSD 9 months ago
nixops Remove nixops examples and documentation 2 years ago
qemu-vm shellcheck: fix the lint warnings for other generated scripts 6 months ago
.gitignore docs: various improvements to installation tutorial 2 years ago
README.md examples: improve Flakes-based VM 10 months ago
configuration.nix Merge fort-nix/nix-bitcoin#504: Add fulcrum module 8 months ago
deploy-container-minimal.sh shellcheck: fix lint of scripts in tests 7 months ago
deploy-container.sh shellcheck: fix lint of scripts in tests 7 months ago
deploy-krops.sh shellcheck: fix lint of scripts in tests 7 months ago
deploy-qemu-vm.sh shellcheck: fix lint of scripts in tests 7 months ago
importable-configuration.nix examples: add importable-configuration.nix 2 years ago
krops-vm-configuration.nix examples: add deploy-krops.sh 2 years ago
nix-bitcoin-release.nix Add fetch-release script 3 years ago
shell.nix examples/shell.nix: Add shell version variable 2 years ago
start-bash-session.sh shellcheck: fix lint of scripts in tests 7 months ago

README.md

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.

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.