commit 6d1ed750fbc057f473cb9cb6754fc659e06ad0aa · nel.pet/core

+46 -45

docs/hacking.md

···

       48
        
       redis-server

     

       49
        
       ```

     

       50
        
       

     

       51
       -
       ## running knots and spindles in a VM

     

       52
        
       

     

       53
        
       An end-to-end knot setup requires setting up a machine with

     

       54
        
       `sshd`, `AuthorizedKeysCommand`, and git user, which is

     

       55
        
       quite cumbersome. So the nix flake provides a

     

       56
        
       `nixosConfiguration` to do so.

     

       57
        
       

     

       58
       -
       ### Mac-specific: setting up a Nix builder

     

       0
        
       
     

       59
        
       

     

       60
       -
       In order to build Tangled's dev VM on macOS, you will first need to set up a

     

       61
       -
       Linux Nix builder. The recommended way to do so is to run a

     

       62
       -
       [`darwin.linux-builder` VM][darwin builder vm] and to register it in `nix.conf`

     

       63
       -
       as a builder for Linux with the same architecture as your Mac (`linux-aarch64`

     

       64
       -
       if you are using Apple Silicon).

     

       0
        
       
     

       0
        
       
     

       65
        
       

     

       66
       -
       > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside

     

       67
       -
       > the tangled repo so that it doesn't conflict with the other VM. For example,

     

       68
       -
       > you can do

     

       69
       -
       >

     

       70
       -
       > ```shell

     

       71
       -
       > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder

     

       72
       -
       > ```

     

       73
       -
       >

     

       74
       -
       > to store the builder VM in a temporary dir.

     

       75
       -
       >

     

       76
       -
       > You should read and follow [all the other intructions][darwin builder vm] to

     

       77
       -
       >  avoid subtle problems.

     

       78
        
       

     

       79
       -
       Alternatively, you can use any other method to set up a Linux machine with `nix`

     

       80
       -
       installed that you can `sudo ssh` into (in other words, root user on your Mac

     

       81
       -
       has to be able to ssh into the Linux machine without entering a password) and

     

       82
       -
       that has the same architecture as your Mac. See [remote builder instructions]

     

       83
       -
       for how to register such a builder in `nix.conf`.

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       84
        
       

     

       85
       -
       > WARNING: If you'd like to use

     

       86
       -
       > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or

     

       87
       -
       > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo

     

       88
       -
       > ssh` works can be tricky. It seems to be [possible with

     

       89
       -
       > Orbstack](https://github.com/orgs/orbstack/discussions/1669).

     

       90
        
       

     

       91
       -
       [darwin builder vm]:

     

       92
       -
           https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder

     

       93
       -
       [remote builder instructions]:

     

       94
       -
           https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements 

     

       95
       -
       

     

       96
       -
       ### Running a knot on a dev VM 

     

       97
        
       

     

       98
        
       To begin, grab your DID from http://localhost:3000/settings.

     

       99
        
       Then, set `TANGLED_VM_KNOT_OWNER` and

     

       100
       -
       `TANGLED_VM_SPINDLE_OWNER` to your DID.

     

       101
       -
       

     

       102
       -
       If you don't want to [set up a spindle](#running-a-spindle),

     

       103
       -
       you can use any placeholder value.

     

       104
       -
       

     

       105
       -
       You can now start a lightweight NixOS VM like so:

     

       106
        
       

     

       107
        
       ```bash

     

       108
        
       nix run --impure .#vm

     
···

       114
        
       with `ssh` exposed on port 2222.

     

       115
        
       

     

       116
        
       Once the services are running, head to

     

       117
       -
       http://localhost:3000/knots and hit verify (and similarly,

     

       118
       -
       http://localhost:3000/spindles to verify your spindle). It

     

       119
       -
       should verify the ownership of the services instantly if

     

       120
       -
       everything went smoothly.

     

       121
        
       

     

       122
        
       You can push repositories to this VM with this ssh config

     

       123
        
       block on your main machine:

     
···

       159
        
       # litecli has a nicer REPL interface:

     

       160
        
       litecli /var/lib/spindle/spindle.db

     

       161
        
       ```

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0

···

       48
        
       redis-server

     

       49
        
       ```

     

       50
        
       

     

       51
       +
       ## running knots and spindles

     

       52
        
       

     

       53
        
       An end-to-end knot setup requires setting up a machine with

     

       54
        
       `sshd`, `AuthorizedKeysCommand`, and git user, which is

     

       55
        
       quite cumbersome. So the nix flake provides a

     

       56
        
       `nixosConfiguration` to do so.

     

       57
        
       

     

       58
       +
       <details>

     

       59
       +
         <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary>

     

       60
        
       

     

       61
       +
         In order to build Tangled's dev VM on macOS, you will

     

       62
       +
         first need to set up a Linux Nix builder. The recommended

     

       63
       +
         way to do so is to run a [`darwin.linux-builder`

     

       64
       +
         VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)

     

       65
       +
         and to register it in `nix.conf` as a builder for Linux

     

       66
       +
         with the same architecture as your Mac (`linux-aarch64` if

     

       67
       +
         you are using Apple Silicon).

     

       68
        
       

     

       69
       +
         > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside

     

       70
       +
         > the tangled repo so that it doesn't conflict with the other VM. For example,

     

       71
       +
         > you can do

     

       72
       +
         >

     

       73
       +
         > ```shell

     

       74
       +
         > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder

     

       75
       +
         > ```

     

       76
       +
         >

     

       77
       +
         > to store the builder VM in a temporary dir.

     

       78
       +
         >

     

       79
       +
         > You should read and follow [all the other intructions][darwin builder vm] to

     

       80
       +
         >  avoid subtle problems.

     

       81
        
       

     

       82
       +
         Alternatively, you can use any other method to set up a

     

       83
       +
         Linux machine with `nix` installed that you can `sudo ssh`

     

       84
       +
         into (in other words, root user on your Mac has to be able

     

       85
       +
         to ssh into the Linux machine without entering a password)

     

       86
       +
         and that has the same architecture as your Mac. See

     

       87
       +
         [remote builder

     

       88
       +
         instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)

     

       89
       +
         for how to register such a builder in `nix.conf`.

     

       90
        
       

     

       91
       +
         > WARNING: If you'd like to use

     

       92
       +
         > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or

     

       93
       +
         > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo

     

       94
       +
         > ssh` works can be tricky. It seems to be [possible with

     

       95
       +
         > Orbstack](https://github.com/orgs/orbstack/discussions/1669).

     

       96
        
       

     

       97
       +
       </details>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       98
        
       

     

       99
        
       To begin, grab your DID from http://localhost:3000/settings.

     

       100
        
       Then, set `TANGLED_VM_KNOT_OWNER` and

     

       101
       +
       `TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a

     

       102
       +
       lightweight NixOS VM like so:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       103
        
       

     

       104
        
       ```bash

     

       105
        
       nix run --impure .#vm

     
···

       111
        
       with `ssh` exposed on port 2222.

     

       112
        
       

     

       113
        
       Once the services are running, head to

     

       114
       +
       http://localhost:3000/knots and hit verify. It should

     

       115
       +
       verify the ownership of the services instantly if everything

     

       116
       +
       went smoothly.

     

       0
        
       
     

       117
        
       

     

       118
        
       You can push repositories to this VM with this ssh config

     

       119
        
       block on your main machine:

     
···

       155
        
       # litecli has a nicer REPL interface:

     

       156
        
       litecli /var/lib/spindle/spindle.db

     

       157
        
       ```

     

       158
       +
       

     

       159
       +
       If for any reason you wish to disable either one of the

     

       160
       +
       services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set

     

       161
       +
       `services.tangled-spindle.enable` (or

     

       162
       +
       `services.tangled-knot.enable`) to `false`.