Merge #250: Improve examples

b574cb0 examples: add deploy-container-minimal.sh (Erik Arvstedt)
e634042 deploy-container.sh: fix sudo (Erik Arvstedt)
c19f7eb examples: add option --interactive|-i (Erik Arvstedt)
33ff8d8 examples: fix running outside of examples dir (Erik Arvstedt)

Pull request description:

ACKs for top commit:
  nixbitcoin:
    ACK b574cb0

Tree-SHA512: 1cf73206af950b157c87476a205e035311416ebb801f90f573868a8c0b8437f900e8b5b85e45e3bacbd3235972b4d3d311de394c63dd93fe4c222919d3364851

README.md

@@ -34,7 +34,7 @@ cd nix-bitcoin/examples/
 nix-shell
 ```
 
-The following example scripts set up a nix-bitcoin node according to `examples/configuration.nix` and then
+The following example scripts set up a nix-bitcoin node according to [`examples/configuration.nix`](examples/configuration.nix) and then
 shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.
 
 - [`./deploy-container.sh`](examples/deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
@@ -48,8 +48,20 @@ shut down immediately. They leave no traces (outside of `/nix/store`) on the hos
   NixOps can be used to deploy to various other backends like cloud providers.\
   Requires: [Nix](https://nixos.org/nix/), [VirtualBox](https://www.virtualbox.org)
 
+- [`./deploy-container-minimal.sh`](examples/deploy-container-minimal.sh) creates a
+  container defined by [minimal-configuration.nix](examples/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.\
+  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 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.
 

examples/deploy-container-minimal.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+exec "${BASH_SOURCE[0]%/*}/deploy-container.sh" --minimal-config "$@"

examples/deploy-container.sh

@@ -8,20 +8,35 @@ set -euo pipefail
 # Feel free to modify or to run nix-shell and execute individual statements of this
 # script in the interactive shell.
 
-if [[ $(sysctl -n net.ipv4.ip_forward) != 1 ]]; then
+if [[ ! -v IN_NIX_SHELL ]]; then
+    echo "Running script in nix shell env..."
+    cd "${BASH_SOURCE[0]%/*}"
+    exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
+fi
+
+if [[ $(sysctl -n net.ipv4.ip_forward || sudo sysctl -n net.ipv4.ip_forward) != 1 ]]; then
     echo "Error: IP forwarding (net.ipv4.ip_forward) is not enabled."
     echo "Needed for container WAN access."
     exit 1
 fi
 
-if [[ ! -v IN_NIX_SHELL ]]; then
-    echo "Running script in nix shell env..."
-    cd "${BASH_SOURCE[0]%/*}"
-    exec nix-shell --run "${BASH_SOURCE[0]}"
+if [[ $EUID != 0 ]]; then
+    # NixOS containers require root permissions
+    exec sudo "PATH=$PATH" "NIX_PATH=$NIX_PATH" "IN_NIX_SHELL=$IN_NIX_SHELL" "${BASH_SOURCE[0]}" "$@"
 fi
 
-# Uncomment to start a container shell session
-# interactive=1
+interactive=
+minimalConfig=
+for arg in "$@"; do
+    case $arg in
+        -i|--interactive)
+            interactive=1
+            ;;
+        --minimal-config)
+            minimalConfig=1
+            ;;
+    esac
+done
 
 # These commands can also be executed interactively in a shell session
 demoCmds='
@@ -35,14 +50,23 @@ echo
 echo "lightning-cli state:"
 c lightning-cli getinfo
 echo
-echo "Node info:"
-c nodeinfo
-echo
 echo "Bitcoind data dir:"
 sudo ls -al /var/lib/containers/demo-node/var/lib/bitcoind
 '
+nodeInfoCmd='
+echo
+echo "Node info:"
+c nodeinfo
+'
+
+if [[ $minimalConfig ]]; then
+    configuration=minimal-configuration.nix
+else
+    configuration=configuration.nix
+    demoCmds="${demoCmds}${nodeInfoCmd}"
+fi
 
-if [[ ${interactive:-} ]]; then
+if [[ $interactive ]]; then
     runCmd=
 else
     runCmd=(--run bash -c "$demoCmds")
@@ -51,21 +75,20 @@ fi
 # Build container.
 # Learn more: https://github.com/erikarvstedt/extra-container
 #
-read -d '' src <<'EOF' || true
+read -d '' src <<EOF || true
 { pkgs, lib, ... }: {
   containers.demo-node = {
     extra.addressPrefix = "10.250.0";
     extra.enableWAN = true;
     config = { pkgs, config, lib, ... }: {
       imports = [
-        <nix-bitcoin/examples/configuration.nix>
+        <nix-bitcoin/examples/${configuration}>
         <nix-bitcoin/modules/secrets/generate-secrets.nix>
       ];
     };
   };
 }
 EOF
-$([[ $EUID = 0 ]] || echo sudo "PATH=$PATH" "NIX_PATH=$NIX_PATH") \
-    $(type -P extra-container) shell -E "$src" "${runCmd[@]}"
+extra-container shell -E "$src" "${runCmd[@]}"
 
 # The container is automatically deleted at exit

examples/deploy-nixops.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 if [[ ! -v IN_NIX_SHELL ]]; then
     echo "Running script in nix shell env..."
     cd "${BASH_SOURCE[0]%/*}"
-    exec nix-shell --run "${BASH_SOURCE[0]}"
+    exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
 fi
 
 # Cleanup on exit
@@ -40,7 +40,11 @@ nixops deploy -d bitcoin-node
 nixops ssh bitcoin-node systemctl status bitcoind
 
 c() { nixops ssh bitcoin-node "$@"; }
-# Uncomment to start a shell session here
-# . start-bash-session.sh
+
+case ${1:-} in
+    -i|--interactive)
+        . start-bash-session.sh
+        ;;
+esac
 
 # Cleanup happens at exit (see above)

examples/deploy-qemu-vm.sh

@@ -14,7 +14,7 @@ set -euo pipefail
 if [[ ! -v IN_NIX_SHELL ]]; then
     echo "Running script in nix shell env..."
     cd "${BASH_SOURCE[0]%/*}"
-    exec nix-shell --run "${BASH_SOURCE[0]}"
+    exec nix-shell --run "./${BASH_SOURCE[0]##*/} $*"
 fi
 
 tmpDir=/tmp/nix-bitcoin-qemu-vm
@@ -91,7 +91,10 @@ echo
 echo "Node info:"
 c nodeinfo
 
-# Uncomment to start a shell session here
-# . start-bash-session.sh
+case ${1:-} in
+    -i|--interactive)
+        . start-bash-session.sh
+        ;;
+esac
 
 # Cleanup happens at exit (see above)

examples/minimal-configuration.nix

@@ -0,0 +1,22 @@
+{ config, pkgs, lib, ... }: {
+  imports = [
+    <nix-bitcoin/modules/nix-bitcoin.nix>
+    <nix-bitcoin/modules/secrets/generate-secrets.nix>
+  ];
+
+  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
+  users.users.main = {
+    isNormalUser = true;
+    password = "a";
+  };
+}

examples/start-bash-session.sh

@@ -3,7 +3,11 @@
 USAGE_INFO='
 Starting shell...
 Run "c COMMAND" to execute a command on the bitcoin node
-Run "c" to start a shell session inside the node'
+Run "c" to start a shell session inside the node
+
+Example:
+c systemctl status bitcoind
+'
 
 # BASH_ENVIRONMENT contains definitions of read-only variables like 'BASHOPTS' that
 # cause warnings on evaluation. Suppress these warnings while sourcing.