Merge fort-nix/nix-bitcoin#396: examples: add importable-configuration.nix

2a16db6919 readme: add 'Get started' section (Erik Arvstedt)
d713e7b15c examples: add importable-configuration.nix (Erik Arvstedt)

Pull request description:

ACKs for top commit:
  jonasnick:
    ACK 2a16db6919

Tree-SHA512: 76338cbd852503df2fa316d4fd6833ad423f166aed4ac556c6917bdf6b39610f8a62323e6bd7c9d191238bb6f6dce9e918b0b303dc80a6534497eb89cb7ec344

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
 ---

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

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 <nix-bitcoin>
+# source instead of fetchTarball
+<importable-configuration.nix sed '
+  s|nix-bitcoin = .*|nix-bitcoin = toString <nix-bitcoin>;|;
+  s|system.extraDependencies = .*||
+' > $tmpDir/importable-configuration.nix
+
+cat > $tmpDir/configuration.nix <<EOF
+  {
+    imports = [ $tmpDir/importable-configuration.nix ];
+    users.users.main = {
+      isNormalUser = true;
+      password = "a";
+    };
+    # When WAN is disabled, DNS bootstrapping slows down service startup by ~15 s
+    services.clightning.extraConfig = "disable-dns";
+  }
+EOF
+
+"${BASH_SOURCE[0]%/*}/deploy-container.sh" $tmpDir/configuration.nix "$@"

examples/deploy-container.sh

@@ -28,14 +28,14 @@ if [[ $EUID != 0 ]]; then
 fi
 
 interactive=
-minimalConfig=
+configuration=
 for arg in "$@"; do
     case $arg in
         -i|--interactive)
             interactive=1
             ;;
-        --minimal-config)
-            minimalConfig=1
+        *)
+            configuration=$arg
             ;;
     esac
 done
@@ -61,9 +61,7 @@ echo "Node info:"
 c nodeinfo
 '
 
-if [[ $minimalConfig ]]; then
-    configuration=minimal-configuration.nix
-else
+if [[ ! $configuration ]]; then
     configuration=configuration.nix
     demoCmds="${demoCmds}${nodeInfoCmd}"
 fi
@@ -84,7 +82,7 @@ read -d '' src <<EOF || true
     extra.enableWAN = true;
     config = { pkgs, config, lib, ... }: {
       imports = [
-        <${configuration}>
+        $(realpath "$configuration")
       ];
       nix-bitcoin.generateSecrets = true;
     };

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

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 ];
+}

examples/minimal-configuration.nix

@@ -1,24 +0,0 @@
-{ config, pkgs, lib, ... }: {
-  imports = [
-    <nix-bitcoin/modules/modules.nix>
-  ];
-
-  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";
-  };
-}