2020-12-24 10:29:14 +00:00
|
|
|
Examples
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
The easiest way to try out nix-bitcoin is to use one of the provided examples.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
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`](configuration.nix) and then
|
|
|
|
|
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.\
|
2021-01-14 12:24:24 +00:00
|
|
|
By default, [`configuration.nix`](configuration.nix) enables `bitcoind` and `clightning`.
|
2020-12-24 10:29:14 +00:00
|
|
|
|
|
|
|
|
- [`./deploy-container.sh`](deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
|
|
|
|
|
This is the fastest way to set up a node.\
|
|
|
|
|
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
|
|
|
|
|
|
|
|
|
|
- [`./deploy-qemu-vm.sh`](deploy-qemu-vm.sh) creates a QEMU VM.\
|
2021-09-25 19:43:31 +00:00
|
|
|
Requires: [Nix](https://nixos.org/nix/), Linux
|
2020-12-24 10:29:14 +00:00
|
|
|
|
2021-03-10 13:08:40 +00:00
|
|
|
- [`./deploy-krops.sh`](deploy-krops.sh) creates a QEMU VM and deploys a
|
|
|
|
|
nix-bitcoin configuration to it using [krops](https://github.com/krebs/krops).\
|
2021-09-25 19:43:31 +00:00
|
|
|
Requires: [Nix](https://nixos.org/nix/), Linux
|
2021-03-10 13:08:40 +00:00
|
|
|
|
2020-12-24 10:29:14 +00:00
|
|
|
- [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a
|
2021-09-23 14:51:34 +00:00
|
|
|
container defined by [importable-configuration.nix](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](../modules/presets/secure-node.nix) preset.\
|
2020-12-24 10:29:14 +00:00
|
|
|
Requires: [Nix](https://nixos.org/), 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:
|
|
|
|
|
```bash
|
|
|
|
|
./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.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git clone https://github.com/fort-nix/nix-bitcoin
|
|
|
|
|
cd nix-bitcoin/test
|
|
|
|
|
|
2021-03-26 22:23:22 +00:00
|
|
|
# Run a node in a VM. No tests are executed.
|
|
|
|
|
./run-tests.sh vm
|
|
|
|
|
systemctl status bitcoind
|
|
|
|
|
|
2020-12-24 10:29:14 +00:00
|
|
|
# Run a Python test shell inside a VM node
|
|
|
|
|
./run-tests.sh debug
|
|
|
|
|
print(succeed("systemctl status bitcoind"))
|
2021-03-26 22:23:22 +00:00
|
|
|
run_test("bitcoind")
|
2020-12-24 10:29:14 +00:00
|
|
|
|
|
|
|
|
# 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
|
2021-01-30 09:47:01 +00:00
|
|
|
|
|
|
|
|
# Run a command in a container
|
|
|
|
|
./run-tests.sh --scenario '{
|
|
|
|
|
services.clightning.enable = true;
|
|
|
|
|
nix-bitcoin.nodeinfo.enable = true;
|
|
|
|
|
}' container --run c nodeinfo
|
2020-12-24 10:29:14 +00:00
|
|
|
```
|
|
|
|
|
See [`run-tests.sh`](../test/run-tests.sh) for a complete documentation.
|
2021-08-15 09:28:33 +00:00
|
|
|
|
|
|
|
|
### Real-world example
|
|
|
|
|
Check the [server repo](https://github.com/fort-nix/nixbitcoin.org) 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.
|
2021-08-16 08:42:07 +00:00
|
|
|
|
|
|
|
|
### Flakes
|
|
|
|
|
|
|
|
|
|
Flakes make it easy to include `nix-bitcoin` in an existing NixOS config.
|
|
|
|
|
The [flakes example](./flakes/flake.nix) 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](../flake.nix)).
|
