nix-bitcoin

mirror of https://github.com/fort-nix/nix-bitcoin.git synced 2024-11-22 22:33:46 +03:00

History

Erik Arvstedt b7bce52da9 examples: fix call to `start-bash-session.sh` Ensure that the file relative to the example scripts is called. Previously, the unqualified call would give precedence to source files in PATH. This could lead to the wrong file being called when dir `helper` (containing another file named `start-bash-session.sh`) was in PATH.		2024-07-20 22:41:18 +02:00
..
container	examples: add persistent container example	2024-02-25 23:00:25 +01:00
flakes	update to nixos 24.05	2024-07-18 20:57:00 +02: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	update nixpkgs	2024-07-03 06:12:24 +00:00
.gitignore	docs: various improvements to installation tutorial	2021-03-15 19:02:58 +01:00
configuration.nix	update to nixos 24.05	2024-07-18 20:57:00 +02:00
deploy-container-minimal.sh	update nixpkgs	2024-07-03 06:12:24 +00:00
deploy-container.sh	update nixpkgs	2024-07-03 06:12:24 +00:00
deploy-krops.sh	examples: fix call to `start-bash-session.sh`	2024-07-20 22:41:18 +02:00
deploy-qemu-vm.sh	examples: fix call to `start-bash-session.sh`	2024-07-20 22:41:18 +02:00
importable-configuration.nix	examples: add importable-configuration.nix	2021-09-26 22:34:39 +02:00
krops-vm-configuration.nix	update nixpkgs	2024-07-03 06:12:24 +00:00
nix-bitcoin-release.nix	Add fetch-release script	2020-04-08 07:01:35 +00:00
README.md	examples: add persistent container example	2024-02-25 23:00:25 +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

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.

./deploy-container.sh creates a NixOS container.
This is the fastest way to set up a node.
Requires: Nix, a systemd-based Linux distro and root privileges
./deploy-qemu-vm.sh creates a QEMU VM.
Requires: Nix, Linux
./deploy-krops.sh creates a QEMU VM and deploys a nix-bitcoin configuration to it using krops.
Requires: Nix, Linux
./deploy-container-minimal.sh creates a container defined by 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 preset.
Requires: Nix, 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:

./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 Flakes-based 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.

Persistent container with Flakes

The persistent container example shows how to run a Flake-based node in a container.
Requires: A systemd-based Linux distro and root privileges.

Extending nix-bitcoin with Flakes

The mempool extension flake shows how to define new pkgs and modules in a Flake.
Since mempool is now a core nix-bitcoin module, this Flake just serves as an example.