d713e7b15c
This replaces minimal-configuration.nix. importable-configuration.nix can be directly added to an existing NixOS configuration. This makes it easy for users to get started quickly.
86 lines
3.1 KiB
Markdown
86 lines
3.1 KiB
Markdown
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.\
|
|
By default, [`configuration.nix`](configuration.nix) enables `bitcoind` and `clightning`.
|
|
|
|
- [`./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.\
|
|
Requires: [Nix](https://nixos.org/nix/)
|
|
|
|
- [`./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).\
|
|
Requires: [Nix](https://nixos.org/nix/)
|
|
|
|
- [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a
|
|
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.\
|
|
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
|
|
|
|
# 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`](../test/run-tests.sh) for a complete documentation.
|
|
|
|
### 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.
|
|
|
|
### 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)).
|