diff --git a/examples/README.md b/examples/README.md index bc71860..64a54df 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,8 +1,22 @@ -Examples ---- +## 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: +```bash +nix run github:fort-nix/nix-bitcoin/release +``` +The VM (defined in [flake.nix](../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: ```bash git clone https://github.com/fort-nix/nix-bitcoin cd nix-bitcoin/examples/ @@ -79,7 +93,3 @@ The commands in `shell.nix` allow you to locally run the node in a VM or contain Flakes make it easy to include `nix-bitcoin` in an existing NixOS config. The [flakes example](./flakes/flake.nix) shows how to use `nix-bitcoin` as an input to a system flake. - -Run `nix run` or `nix run .#vm` from the nix-bitcoin root directory to start an example -nix-bitcoin node VM. -This command is defined by the nix-bitcoin flake (in [flake.nix](../flake.nix)). diff --git a/examples/flakes/flake.nix b/examples/flakes/flake.nix index c2392fd..24b7d53 100644 --- a/examples/flakes/flake.nix +++ b/examples/flakes/flake.nix @@ -8,7 +8,7 @@ nixosConfigurations.mynode = nix-bitcoin.inputs.nixpkgs.lib.nixosSystem { system = "x86_64-linux"; modules = [ - nix-bitcoin.nixosModule + nix-bitcoin.nixosModules.default # Optional: # Import the secure-node preset, an opinionated config to enhance security diff --git a/examples/qemu-vm/minimal-vm.nix b/examples/qemu-vm/minimal-vm.nix new file mode 100644 index 0000000..eb89eb6 --- /dev/null +++ b/examples/qemu-vm/minimal-vm.nix @@ -0,0 +1,49 @@ +nix-bitcoin: pkgs: system: + +rec { + inherit (nix-bitcoin.inputs) nixpkgs; + + mkVMScript = vm: pkgs.writers.writeBash "run-vm" '' + set -euo pipefail + export TMPDIR=$(mktemp -d /tmp/nix-bitcoin-vm.XXX) + trap "rm -rf $TMPDIR" EXIT + export NIX_DISK_IMAGE=$TMPDIR/nixos.qcow2 + QEMU_OPTS="-smp $(nproc) -m 1500" ${vm}/bin/run-*-vm + ''; + + vm = (import "${nixpkgs}/nixos" { + inherit system; + configuration = { lib, ... }: { + imports = [ + nix-bitcoin.nixosModules.default + "${nix-bitcoin}/modules/presets/secure-node.nix" + ]; + + nix-bitcoin.generateSecrets = true; + services.clightning.enable = true; + # For faster startup in offline VMs + services.clightning.extraConfig = "disable-dns"; + + nixpkgs.pkgs = pkgs; + virtualisation.graphics = false; + services.getty.autologinUser = "root"; + nix.nixPath = [ "nixpkgs=${nixpkgs}" ]; + + services.getty.helpLine = lib.mkAfter '' + + Welcome to nix-bitcoin! + To explore running services, try the following commands: + - nodeinfo + - systemctl status bitcoind + - systemctl status clightning + ''; + + # Power off VM when the user exits the shell + systemd.services."serial-getty@".preStop = '' + echo o >/proc/sysrq-trigger + ''; + }; + }).vm; + + runVM = mkVMScript vm; +} diff --git a/flake.nix b/flake.nix index d27d621..338bce1 100644 --- a/flake.nix +++ b/flake.nix @@ -24,11 +24,11 @@ import ./pkgs { inherit pkgs pkgsUnstable; }; }; - overlay = final: prev: let + overlays.default = final: prev: let nbPkgs = lib.mkNbPkgs { inherit (final) system; pkgs = final; }; in removeAttrs nbPkgs [ "pinned" "nixops19_09" "krops" ]; - nixosModule = { config, pkgs, lib, ... }: { + nixosModules.default = { config, pkgs, lib, ... }: { imports = [ ./modules/modules.nix ]; options = with lib; { @@ -58,7 +58,7 @@ }; }; - defaultTemplate = { + templates.default = { description = "Basic node template"; path = ./examples/flakes; }; @@ -66,46 +66,16 @@ } // (flake-utils.lib.eachSystem supportedSystems (system: let pkgs = nixpkgs.legacyPackages.${system}; - nbPkgs = self.lib.mkNbPkgs { inherit system pkgs; }; - - mkVMScript = vm: pkgs.writers.writeBash "run-vm" '' - set -euo pipefail - export TMPDIR=$(mktemp -d /tmp/nix-bitcoin-vm.XXX) - trap "rm -rf $TMPDIR" EXIT - export NIX_DISK_IMAGE=$TMPDIR/nixos.qcow2 - QEMU_OPTS="-smp $(nproc) -m 1500" ${vm}/bin/run-*-vm - ''; in rec { packages = flake-utils.lib.flattenTree (removeAttrs nbPkgs [ "pinned" "modulesPkgs" "nixops19_09" "krops" "generate-secrets" "netns-exec" ]) // { - runVM = mkVMScript packages.vm; - - # This is a simple demo VM. - # See ./examples/flakes/flake.nix on how to use nix-bitcoin with flakes. - vm = let - nix-bitcoin = self; - in - (import "${nixpkgs}/nixos" { - inherit system; - configuration = { - imports = [ - nix-bitcoin.nixosModule - "${nix-bitcoin}/modules/presets/secure-node.nix" - ]; - - nix-bitcoin.generateSecrets = true; - services.clightning.enable = true; - # For faster startup in offline VMs - services.clightning.extraConfig = "disable-dns"; - - nixpkgs.pkgs = pkgs; - virtualisation.graphics = false; - services.getty.autologinUser = "root"; - nix.nixPath = [ "nixpkgs=${nixpkgs}" ]; - }; - }).vm; + inherit (import ./examples/qemu-vm/minimal-vm.nix self pkgs system) + # A simple demo VM. + # See ./examples/flakes/flake.nix on how to use nix-bitcoin with flakes. + runVM + vm; }; # Allow accessing the whole nested `nbPkgs` attrset (including `modulesPkgs`) @@ -113,9 +83,9 @@ # `packages` is not allowed to contain nested pkgs attrsets. legacyPackages = nbPkgs; - defaultApp = apps.vm; + apps = rec { + default = vm; - apps = { # Run a basic nix-bitcoin node in a VM vm = { type = "app";