Skip to content

Commit

Permalink
initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisguida
chrisguida committed Oct 6, 2023
0 parents commit c2fc443
Show file tree
Hide file tree
Showing 12 changed files with 692 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .replit
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
run = "cowsay Configure me!"

[nix]
channel = "stable-22_11"
38 changes: 38 additions & 0 deletions .tutorial/01-intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Deploying Your First NixOS Machine

Speaker: [Chris Guida](https://github.com/chrisguida)<br>
Twitter: [@cguida6](https://x.com/cguida6)

Welcome!

In this tutorial, you'll set up a [Mutinynet](https://mutinynet.com) bitcoin and lightning node, and you'll open some channels and send some sats!

- If you're doing this tutorial at the [btc++ conference in Berlin](https://btcplusplus.dev/berlin23/talks#cguida) on Friday, October 6, 2023, I've already set up a VPS for you to use in this workshop.
- If you're doing this tutorial sometime later, you can use any NixOS machine. The config will be a bit different since the tutorial uses a config tailored to DigitalOcean. Reach out to me and I'll be happy to help you set it up :)

So all you need to do is read through each section and follow the examples, and at the end you'll have a working mutinynet bitcoin and lightning node, which you can then deploy anywhere and customize to fit any bitcoin use case!

## Nix-bitcoin
- Nix-bitcoin is a collection of NixOS modules that allow users to easily configure a large number of interconnected bitcoin-related services on a NixOS system.
- We're using [a fork of] it today to show off how easy it makes working with bitcoin and lightning.
- Nix-bitcoin is designed with security in mind, but the system we're building today is a toy system for demo and testing purposes only.
- If you want to build a secure production system, make sure you read and understand the documentation on [nixbitcoin.org](https://nixbitcoin.org).

## Mutinynet
- [Mutinynet](https://mutinynet.com) is a custom signet based on a [fork of bitcoind](https://github.com/benthecarman/bitcoin/tree/configure-signet-blockitme), built by the [Mutiny Wallet](https://mutinywallet.com) team.
- This allows Mutinynet to have a very fast and predictable 30-second block time, which makes it ideal for testing, especially for L2 stuff like Lightning.

## Session Agenda:
- Build a mutinynet lightning node
- bitcoind
- CLN
- Bonus exercises
- RTL
- Fulcrum / Sparrow
- Mempool

## Chris's Hackathon Plugin Ideas He Could Help You With:

1. (Easy) Use nix-bitcoin to install additional services
2. (Medium) Make a nix devShell
3. (Hard) Nixify CLN
118 changes: 118 additions & 0 deletions .tutorial/02-init.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Set up your NixOS VPS

- If you're doing this tutorial at the btc++ conference in Berlin on Friday, October 6, 2023, I've already set up a VPS for you to use in this workshop.
- If you're doing this tutorial sometime later, you can use any NixOS machine. The config will be a bit different since the tutorial uses a config tailored to DigitalOcean. Reach out to me and I'll be happy to help you set it up :)

# Exercise: Generate and switch to a new config

Get your ip address and log into it:
- user: `bitcoiner`
- password: `btcpp`
```sh
ssh bitcoiner@<your ip>
```

The following command will generate a new `configuration.nix` and `hardware-configuration.nix` for your system.

This command will spit out a warning: `warning: not overwriting existing /etc/nixos/configuration.nix`. You can safely ignore this warning.

We don't need the `configuration.nix` as we're replacing it in the next step. We just need `hardware-configuration.nix`.

```sh
sudo nixos-generate-config
```

Delete the automatically generated config and make a new one:

```sh
sudo rm /etc/nixos/configuration.nix
sudo vim /etc/nixos/configuration.nix
```

Then type `i` (for insert) and copy and paste this into the file:

```nix
{ modulesPath, lib, pkgs, ... }:
{
imports = lib.optional (builtins.pathExists ./do-userdata.nix) ./do-userdata.nix ++ [
# import the autogenerated `hardware-configuration.nix`
./hardware-configuration.nix
# import the digitalocean-specific settings
(modulesPath + "/virtualisation/digital-ocean-config.nix")
];
# Resolve a conflict between the DO-specific config and `hardware-configuration.nix`
fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos";
# set the stateVersion
system.stateVersion = "23.11";
# enable flakes and nix commands
nix.extraOptions = "experimental-features = nix-command flakes";
# declare user `bitcoiner`
users.users.bitcoiner = {
isNormalUser = true;
description = "bitcoiner";
# feel free to change this or use an ssh key
# delete this if you only want SSH key access
password = "btcpp";
# here's how to set an SSH key:
# openssh.authorizedKeys.keys = [
# "<SSH key goes here>"
# ];
# Allow the `bitcoiner` user to use `sudo`
extraGroups = [ "wheel" ];
# install vim. I like it better than `nano`, but you can use either
packages = with pkgs; [
vim
# you'll want `jq` to parse your CLN node's command output
jq
];
};
# Configure OpenSSH
services.openssh = {
# Allow password authentication
settings.PasswordAuthentication = true;
# Lengthen the default SSH session timeout
# (The DO default is annoyingly short)
extraConfig = ''
ClientAliveInterval 120
ClientAliveCountMax 720
'';
};
}
```

Then hit ESCAPE (to exit insert mode) and type `ZZ` to save and exit vim

Now let's switch to the new config (same as the old config, but now you're editing it locally instead of me editing it remotely)

```sh
sudo nixos-rebuild switch
```

Now log out and log back in. Your password should still work, and this command should still work:

```sh
sudo vim /etc/nixos/configuration.nix
```

Type `:q!` then press ENTER to quit `vim` without saving.

- [ ] Generate config
- [ ] Edit it
- [ ] Switch to the new config
- [ ] Test config by running `sudo vim /etc/nixos/configuration.nix`

Now on to the more exciting part!
131 changes: 131 additions & 0 deletions .tutorial/03-bitcoind.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Bitcoind

- In this section we install and sync `bitcoind` on our NixOS box!
- This will build the [mutinynet fork of bitcoind](https://github.com/benthecarman/bitcoin/tree/configure-signet-blockitme) from source, and install via a [modified version](https://github.com/fort-nix/nix-bitcoin/commit/e177c2eb4895c152df7baabb892a9a401daa582c) of the `nix-bitcoin` `bitcoind` NixOS module, using a Nix flake.
- It will also configure `bitcoind` as a system service and start the initial block download. Syncing Mutinynet should be fairly quick; it should be done in just a few minutes.
- Shoutout to [@benthecarman](https://github.com/benthecarman/) and the Mutiny Wallet team for maintaining this fork of bitcoin and making life super easy for developers!
- Shoutout to [@erikarvstedt](https://github.com/erikarvstedt/) for modifying `nix-bitcoin` so we could run Mutinynet!

# Exercise: Add mutinynet bitcoind `nix-bitcoin` module to your system config

First, create a new file, `/etc/nixos/flake.nix`:

```sh
sudo vim /etc/nixos/flake.nix
```

Activate insert mode (`i`) and copy this in:

```nix
{
description = "btcpp-berlin-mutinynet machine configuration";
# pull in the modified `nix-bitcoin` flake into our flake
inputs.nix-bitcoin.url = "github:chrisguida/nix-bitcoin/mempool-and-fix-no-feerate";
# for a mainnet node, you would just do:
# inputs.nix-bitcoin.url = "github:fort-nix/nix-bitcoin";
# However, the main branch of nix-bitcoin does not have bitcoind-mutinynet, nor mempool,
# so it will not work with this tutorial.
# Stay tuned, though. Mempool is close :) https://github.com/fort-nix/nix-bitcoin/pull/505
outputs = { self, nix-bitcoin }: {
nixosConfigurations = {
# Our machine config
btcpp-berlin-mutinynet = nix-bitcoin.inputs.nixpkgs.lib.nixosSystem {
modules = [
# import the default NixOS modules from nix-bitcoin
nix-bitcoin.nixosModules.default
# import configuration.nix into our flake
./configuration.nix
];
};
};
};
}
```

Exit out of insert (ESCAPE) and hit `ZZ` again to save and exit.

Now let's edit `configuration.nix` again:

```sh
sudo vim /etc/nixos/configuration.nix
```
(I recommend pasting this after the services.openssh section):

```nix
services.bitcoind = {
# enable the bitcoind service from our flake
enable = true;
# enable the transaction index (optional) (needed for
# block explorers and some address indexers)
txindex = true;
# listen for peer connections
address = "0.0.0.0";
listen = true;
# set fallback fee (required for mutinynet because fee estimate is always 0)
# enable block filters (optional)
extraConfig = ''
fallbackfee=0.00000253
blockfilterindex=1
peerblockfilters=1
'';
};
```

Make sure to have nix-bitcoin generate your secrets, and set an operator (this can go immediately after the above):

```nix
nix-bitcoin.generateSecrets = true;
nix-bitcoin.operator.name = "bitcoiner";
```

Also make sure to add your user to the `bitcoin` group:

Change the `users.users.bitcoiner.extraGroups` line from

```nix
extraGroups = [ "wheel" ];
```

to


```nix
extraGroups = [ "wheel" "bitcoin" ];
```

Finally, open port 8333 in your firewall so your node is contributing to the network:
```nix
networking.firewall.allowedTCPPorts = [ 8333 ];
```

then switch your system to use your new flake:

```
sudo nixos-rebuild switch --flake /etc/nixos/#btcpp-berlin-mutinynet
```

log out of SSH and log back in to pick up the changes to your user.

make sure the bitcoin node is running and track IBD progress (mutinynet's entire blockchain is under 500MB at the time of writing and IBD should take just a few minutes):

```sh
bitcoin-cli -getinfo
```

- [ ] Create flake
- [ ] Add bitcoind to system config
- [ ] Add `nix-bitcoin` `operator` and `generate-secrets` to config
- [ ] Switch to the new config
- [ ] Log out and log back in to update your user's groups
- [ ] Test new bitcoind by running `bitcoin-cli -getinfo`
79 changes: 79 additions & 0 deletions .tutorial/04-cln.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# CLN

- In this section we install and sync `lightningd` (aka [Core Lightning](https://github.com/ElementsProject/lightning), aka CLN) on our NixOS box!
- This will build and install `lightningd` v23.05.2 via the `nix-bitcoin` `bitcoind` NixOS module, using a Nix flake.
- It will also configure `lightningd` as a system service and sync it with your mutinynet bitcoind node. You should wait until bitcoind is finished syncing before starting CLN, otherwise it might take a while to sync. If you accidentally do this, there are steps below to speed things up.
- Shoutout to the `nix-bitcoin` team for maintaining this software for anyone to use!

# Exercise: Add signet lightningd nix-bitcoin module to your system config

While our bitcoin node is syncing to mutinynet, let's add a mutinynet CLN node!

Add this after `nix-bitcoin.operator.name` in `/etc/nixos/configuration.nix` (make sure to edit the file with `sudo`)

```nix
services.clightning = {
enable = true;
address = "0.0.0.0";
plugins.summary.enable = true;
# enable some cool CLN features
extraConfig = ''
experimental-offers
experimental-dual-fund
experimental-splicing
'';
};
```

Make sure to add your user to the `clightning` group:

```nix
extraGroups = [ "wheel" "bitcoin" "clightning" ];
```

Finally, open port 9735 to your firewall so othernodes can connect to you:

Change this line:
```nix
networking.firewall.allowedTCPPorts = [ 8333 ];
```

to look like:

```nix
networking.firewall.allowedTCPPorts = [ 8333 9735 ];
```

switch again!

```
sudo nixos-rebuild switch --flake /etc/nixos/#btcpp-berlin-mutinynet
```

Now logout and log back in to reflect the new user changes.

Once back in, check your lightning node:

```
lightning-cli getinfo
```

If you started your lightning node before your bitcoin node was done syncing, this can result in a slow CLN initial sync. If this happens, you may want to just nuke it and start over, (once bitcoind is finished syncing):

```
sudo rm -rf /var/lib/clightning/signet/ && sudo systemctl restart clightning
```

This should allow CLN to sync instantly.

Obviously don't do this if you already have money and channels on your node, as these will be lost. Of course, this is just signet, so the money isn't real anyway.

Now open some channels and send some sats!

- [ ] Create flake
- [ ] Add bitcoind to system config
- [ ] Add `nix-bitcoin` `operator` and `generate-secrets` to config
- [ ] Switch to the new config
- [ ] Log out and log back in to update your user's groups
- [ ] Test new bitcoind by running `bitcoin-cli -getinfo`
Loading

0 comments on commit c2fc443

Please sign in to comment.