nix-bitcoin/examples
Jonas Nick 84fc4d48d3
Merge fort-nix/nix-bitcoin#574: Add dev helper and docs
b4d7e1aa8f add dev helper and docs (Erik Arvstedt)
b35d08d3f2 docs: move test docs from `examples/README` to `test/README` (Erik Arvstedt)
4d76eb9183 docs/configuration: fix typo (Erik Arvstedt)
dc0710f3f4 tests: add example scenario `customTest` (Erik Arvstedt)
9e30d2728b tests: formatting (Erik Arvstedt)
c6d85c6fe3 tests: fix broken unit file when clightning is disabled (Erik Arvstedt)
a51f7b419e run-tests: use arg instead of env var for scenario overrides (Erik Arvstedt)

Pull request description:

ACKs for top commit:
  jonasnick:
    ACK b4d7e1aa8f

Tree-SHA512: f0ed8f8fe326c64eac3b7e9f48597dd00eedb9244333e199d18d1c2c06f369cd015f77aefd48e87235a68aee0b352057249525bf015e0a564fda380bdf7bb9d1
2023-01-18 20:53:24 +00:00
..
flakes add compatibility with Nix PR #6530 (Source tree abstraction) 2022-11-03 23:08:05 +01:00
krops examples/krops: fix nixpkgs symlink sync error on macOS/BSD 2022-07-04 23:42:09 +02:00
nixops Remove nixops examples and documentation 2021-03-15 12:42:47 +00:00
qemu-vm examples/vm-config: fix syntax error 2022-11-04 00:33:53 +01:00
.gitignore docs: various improvements to installation tutorial 2021-03-15 19:02:58 +01:00
configuration.nix versioning: add fulcrum db change info 2023-01-07 19:32:54 +00:00
deploy-container-minimal.sh examples/deploy-container: fix sudo env propagation 2023-01-06 23:23:54 +01:00
deploy-container.sh examples/deploy-container: fix sudo env propagation 2023-01-06 23:23:54 +01:00
deploy-krops.sh shellcheck: fix lint of scripts in tests 2022-08-28 18:25:37 +02:00
deploy-qemu-vm.sh shellcheck: fix lint of scripts in tests 2022-08-28 18:25:37 +02:00
importable-configuration.nix examples: add importable-configuration.nix 2021-09-26 22:34:39 +02:00
krops-vm-configuration.nix examples: add deploy-krops.sh 2021-03-15 19:02:58 +01:00
nix-bitcoin-release.nix Add fetch-release script 2020-04-08 07:01:35 +00:00
README.md docs: move test docs from examples/README to test/README 2023-01-15 20:28:48 +01:00
shell.nix examples/shell.nix: Add shell version variable 2021-09-15 12:22:10 +02:00
start-bash-session.sh shellcheck: fix lint of scripts in tests 2022-08-28 18:25:37 +02:00

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