diff --git a/README.md b/README.md index f9ebaf1..e18f8e9 100644 --- a/README.md +++ b/README.md @@ -28,22 +28,24 @@ nix-bitcoin is a collection of Nix packages and NixOS modules for easily install Overview --- -A Bitcoin node verifies the Bitcoin protocol and provides ways of interacting with the Bitcoin network. nix-bitcoin -nodes are used for a variety of purposes and can serve as personal or merchant wallets, second layer public -infrastructure and as backends for Bitcoin applications. In all cases, the aim is to provide security and privacy by -default. However, while nix-bitcoin is used in production today, it is still considered experimental. +nix-bitcoin can be used for personal or merchant wallets, public infrastructure or +for Bitcoin application backends. In all cases, the aim is to provide security and +privacy by default. However, while nix-bitcoin is used in production today, it is +still considered experimental. -A full installation of nix-bitcoin is usually deployed either on a dedicated (virtual) machine or runs in a container -and is online 24/7. Alternatively, the Nix packages, NixOS modules and configurations can be used independently and -combined freely. +nix-bitcoin nodes can be deployed on dedicated hardware, virtual machines or containers. +The Nix packages and NixOS modules can be used independently and combined freely. -nix-bitcoin is built on top of Nix and NixOS which provide powerful abstractions to keep it highly customizable and +nix-bitcoin is built on top of Nix and [NixOS](https://nixos.org/) which provide powerful abstractions to keep it highly customizable and maintainable. Testament to this are nix-bitcoin's robust security features and its potent test framework. However, running nix-bitcoin does not require any previous experience with the Nix ecosystem. -Examples +Get started --- -See [here for examples](examples/README.md). +- See the [examples](examples/README.md) for an overview of all features. +- To setup a new node from scratch, see the [installation instructions](docs/install.md). +- To add nix-bitcoin to an existing NixOS configuration, see [importable-configuration.nix](examples/importable-configuration.nix) + and the [Flake example](examples/flakes/flake.nix). Features --- diff --git a/examples/README.md b/examples/README.md index 20e3d0f..93a0b26 100644 --- a/examples/README.md +++ b/examples/README.md @@ -25,9 +25,9 @@ By default, [`configuration.nix`](configuration.nix) enables `bitcoind` and `cli Requires: [Nix](https://nixos.org/nix/) - [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a - container defined by [minimal-configuration.nix](minimal-configuration.nix) that - doesn't use the [secure-node.nix](../modules/presets/secure-node.nix) preset. - Also shows how to use nix-bitcoin in an existing NixOS config.\ + 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 diff --git a/examples/deploy-container-minimal.sh b/examples/deploy-container-minimal.sh index 3e7f7eb..99b67e8 100755 --- a/examples/deploy-container-minimal.sh +++ b/examples/deploy-container-minimal.sh @@ -1,3 +1,33 @@ #!/usr/bin/env bash -exec "${BASH_SOURCE[0]%/*}/deploy-container.sh" --minimal-config "$@" +if [[ ! -v NIX_BITCOIN_EXAMPLES_DIR ]]; then + echo "Running script in nix shell env..." + cd "${BASH_SOURCE[0]%/*}" + exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*" +else + cd "$NIX_BITCOIN_EXAMPLES_DIR" +fi + +tmpDir=$(mktemp -d /tmp/nix-bitcoin-minimal-container.XXX) +trap "rm -rf $tmpDir" EXIT + +# Modify importable-configuration.nix to use the local +# source instead of fetchTarball +;|; + s|system.extraDependencies = .*|| +' > $tmpDir/importable-configuration.nix + +cat > $tmpDir/configuration.nix < + $(realpath "$configuration") ]; nix-bitcoin.generateSecrets = true; }; diff --git a/examples/flakes/flake.nix b/examples/flakes/flake.nix index aaaff29..9b8f6a9 100644 --- a/examples/flakes/flake.nix +++ b/examples/flakes/flake.nix @@ -25,8 +25,12 @@ # "${nix-bitcoin}/modules/presets/secure-node.nix" { + # Automatically generate all secrets required by services. + # The secrets are stored in /etc/nix-bitcoin-secrets nix-bitcoin.generateSecrets = true; + # Enable services. + # See ../configuration.nix for all available features. services.bitcoind.enable = true; # When using nix-bitcoin as part of a larger NixOS configuration, set the following to enable diff --git a/examples/importable-configuration.nix b/examples/importable-configuration.nix new file mode 100644 index 0000000..f77e3fe --- /dev/null +++ b/examples/importable-configuration.nix @@ -0,0 +1,38 @@ +# You can directly copy and import this file to use nix-bitcoin +# in an existing NixOS configuration. +# Make sure to check and edit all lines marked by 'FIXME:' + +# See ./flakes/flake.nix on how to include nix-bitcoin in a flake-based +# system configuration. + +let + # FIXME: + # Overwrite `builtins.fetchTarball {}` with the output of + # command ../helper/fetch-release + nix-bitcoin = builtins.fetchTarball {}; +in +{ config, pkgs, lib, ... }: { + imports = [ + "${nix-bitcoin}/modules/modules.nix" + ]; + + # Automatically generate all secrets required by services. + # The secrets are stored in /etc/nix-bitcoin-secrets + nix-bitcoin.generateSecrets = true; + + # Enable some services. + # See ./configuration.nix for all available features. + services.bitcoind.enable = true; + services.clightning.enable = true; + + # Enable interactive access to nix-bitcoin features (like bitcoin-cli) for + # your system's main user + nix-bitcoin.operator = { + enable = true; + # FIXME: Set this to your system's main user + name = "main"; + }; + + # Prevent garbage collection of the nix-bitcoin source + system.extraDependencies = [ nix-bitcoin ]; +} diff --git a/examples/minimal-configuration.nix b/examples/minimal-configuration.nix deleted file mode 100644 index 71dd4a5..0000000 --- a/examples/minimal-configuration.nix +++ /dev/null @@ -1,24 +0,0 @@ -{ config, pkgs, lib, ... }: { - imports = [ - - ]; - - nix-bitcoin.generateSecrets = true; - - services.bitcoind.enable = true; - services.clightning.enable = true; - - # When using nix-bitcoin as part of a larger NixOS configuration, set the following to enable - # interactive access to nix-bitcoin features (like bitcoin-cli) for your system's main user - nix-bitcoin.operator = { - enable = true; - name = "main"; # Set this to your system's main user - }; - - # The system's main unprivileged user. This setting is usually part of your - # existing NixOS configuration. - users.users.main = { - isNormalUser = true; - password = "a"; - }; -}