nix-bitcoin

mirror of https://github.com/fort-nix/nix-bitcoin.git synced 2024-07-07 11:16:29 +03:00

History

Jonas Nick b26cea03b3 update nixpkgs bitcoin: 27.0 -> 27.1 bitcoind: 27.0 -> 27.1 clightning: 24.02.2 -> 24.05 fulcrum: 1.10.0 -> 1.11.0 lnd: 0.17.5-beta -> 0.18.0-beta Co-authored-by: Erik Arvstedt <erik.arvstedt@gmail.com>		2024-07-03 06:12:24 +00:00
..
container	examples: add persistent container example	2024-02-25 23:00:25 +01:00
flakes	update to NixOS 23.11	2023-12-12 11:22:38 +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	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	clightning-plugins: remove unmaintained plugins prometheus & helpme	2024-04-08 06:01:47 +00: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	shellcheck: fix lint of scripts in tests	2022-08-28 18:25:37 +02:00
deploy-qemu-vm.sh	update nixpkgs	2024-07-03 06:12:24 +00: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.