nix-bitcoin/examples
Erik Arvstedt 24fd1e9bdc
improve examples/shell.nix
The user's local node configuration directory usually contains a copy of
examples/shell.nix.

1. Move the shell implementation from shell.nix to nix-bitcoin/helper/makeShell.nix
   Because the shell is no longer defined locally in the user's config
   directory, we can now ship new shell features via nix-bitcoin updates.

2. Simplify examples/nix-bitcoin-release.nix
   nix-bitcoin-release.nix, as generated via `fetch-release`, now
   contains a simple fetchTarball statement which can be directly imported.
   This allows us to get rid of the extra `nix-bitcoin-unpacked` derivation
   which adds a dependency on the user's local nixpkgs.

   To keep `fetch-release` as simple as possible for easy auditing, we just
   fetch and verify a `nar-hash.txt` file that is now uploaded
   via `push-release.sh`.

A migration guide for updating the user's local `shell.nix` is
automatically printed when the user starts a new shell after updating
nix-bitcoin.
This is achieved by throwing an error in `generate-secrets`, which is called
on shell startup.

This commit is required to deploy the new extensible `generate-secrets`
mechanism introduced in the next commit.
2021-09-12 11:29:54 +02:00
..
flakes add flake support 2021-08-26 12:45:10 +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 joinmarket: allow recreating wallet from seed 2021-08-30 13:37:05 +02:00
deploy-container-minimal.sh examples: add deploy-container-minimal.sh 2020-10-20 12:35:23 +02:00
deploy-container.sh examples: improve robustness of deploy scripts 2021-03-16 12:46:18 +01: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
krops-vm-configuration.nix examples: add deploy-krops.sh 2021-03-15 19:02:58 +01:00
minimal-configuration.nix modules: move nix-bitcoin options to file 'nix-bitcoin.nix' 2021-08-15 22:40:35 +02:00
nix-bitcoin-release.nix Add fetch-release script 2020-04-08 07:01:35 +00:00
README.md add flake support 2021-08-26 12:45:10 +02:00
shell.nix improve examples/shell.nix 2021-09-12 11:29:54 +02:00
start-bash-session.sh examples: add option --interactive|-i 2020-10-18 13:42:58 +02:00

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