greg
/
nix-bitcoin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nix-bitcoin/examples/README.md

66 lines
2.6 KiB
Markdown
Raw Permalink Normal View History

examples: improve Flakes-based VM - Show login message - Poweroff on shell exit - Move to top of examples/README
2022-06-01 12:35:50 -07:00
## Examples
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
The easiest way to try out nix-bitcoin is to use one of the provided examples.
examples: improve Flakes-based VM - Show login message - Poweroff on shell exit - Move to top of examples/README
2022-06-01 12:35:50 -07:00
### 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:
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
```bash
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`](configuration.nix) and then
shut down immediately. They leave no traces (outside of `/nix/store`) on the host system.\
enable-tor: disable default onion services for clightning, lnd, btcpayserver In case of btcpayserver the default onion service is a security risk because any visitor can register an admin account on a freshly setup node.
2021-01-14 04:24:24 -08:00
By default, [`configuration.nix`](configuration.nix) enables `bitcoind` and `clightning`.
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
- [`./deploy-container.sh`](deploy-container.sh) creates a [NixOS container](https://github.com/erikarvstedt/extra-container).\
This is the fastest way to set up a node.\
Requires: [Nix](https://nixos.org/), a systemd-based Linux distro and root privileges
- [`./deploy-qemu-vm.sh`](deploy-qemu-vm.sh) creates a QEMU VM.\
examples: fix shell on non-Linux systems extra-container is not supported on these systems. Also mention that VM examples require Linux.
2021-09-25 12:43:31 -07:00
Requires: [Nix](https://nixos.org/nix/), Linux
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
examples: add deploy-krops.sh
2021-03-10 05:08:40 -08:00
- [`./deploy-krops.sh`](deploy-krops.sh) creates a QEMU VM and deploys a
nix-bitcoin configuration to it using [krops](https://github.com/krebs/krops).\
examples: fix shell on non-Linux systems extra-container is not supported on these systems. Also mention that VM examples require Linux.
2021-09-25 12:43:31 -07:00
Requires: [Nix](https://nixos.org/nix/), Linux
examples: add deploy-krops.sh
2021-03-10 05:08:40 -08:00
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
- [`./deploy-container-minimal.sh`](deploy-container-minimal.sh) creates a
examples: add importable-configuration.nix This replaces minimal-configuration.nix. importable-configuration.nix can be directly added to an existing NixOS configuration. This makes it easy for users to get started quickly.
2021-09-23 07:51:34 -07:00
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.\
readme: update and split into various parts
2020-12-24 02:29:14 -08:00
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
docs: move test docs from `examples/README` to `test/README`
2023-01-15 11:27:50 -08:00
The [nix-bitcoin test suite](../test/README.md) is also useful for exploring features.
tests: define tests via flake Advantages: - Pure test evaluations - The test framework can now be used by flakes that extend nix-bitcoin - Most features of `run-tests.sh` are now accessible via `nix build`/`nix run`. We keep `run-tests.sh` for advanced features like `scenarioOverridesFile` and adhoc scenarios. Other changes: - `run-tests.sh` now builds aggregate VM tests like `basic` or `buildable` by creating all VMs in a single evaluation. This speeds up the tests and eases debugging by separating the eval and build steps. - Use the new `nix` CLI which has improved build output logging by prefixing output lines with the origin drv name.
2022-10-22 10:37:58 -07:00
examples/README: add nixbitcoin.org server repo
2021-08-15 02:28:33 -07:00
### Real-world example
Check the [server repo](https://github.com/fort-nix/nixbitcoin.org) for https://nixbitcoin.org
improve comments The comment in python-packackges was obsolete.
2023-01-20 04:45:09 -08:00
to see the configuration of a Flakes-based nix-bitcoin node that's used in production.
examples/README: add nixbitcoin.org server repo
2021-08-15 02:28:33 -07:00
The commands in `shell.nix` allow you to locally run the node in a VM or container.
add flake support This change is fully backwards compatible. We continue to use the standard non-flake evaluation mode in our examples and internal tooling until the flakes design has stabilized. 'clightning-plugins = pkgs.recurseIntoAttrs' in pkgs/default.nix is needed by flake-utils.lib.flattenTree in flake.nix. It transforms the packages in `clightning-plugins` to top-level packages named like `clightning-plugins/summary`. (The flake attr `packages` must be a non-nested attrset of derivations.)
2021-08-16 01:42:07 -07:00
### Flakes
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.