hacking.md: mac-specific VM instructions #489

merged
opened by
ilyagr.bsky.social 4 months ago targeting master from ilyagr.bsky.social/core: machacking
On a Mac, to build Tangled's VM with Nix, you first have to set up a Linux builder for Nix. With the help of @winter, I was able to do so in the way described here.
It would be helpful to develop easier ways to do it, but this is the easiest one I know at the moment.
Signed-off-by: Ilya Grigoriev ilyagr@users.noreply.github.com
options
unified split
Changed files
+48 -8
docs
hacking.md
+48 -8
docs/hacking.md
···

       48
       48
        
       redis-server

     

       49
       49
        
       ```

     

       50
       50
        
       

     

       51
       51
       -
       ## running a knot

     

       51
       51
       +
       ## running knots and spindles in a VM

     

       52
       52
        
       

     

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

     

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

     

       55
       55
        
       quite cumbersome. So the nix flake provides a

     

       56
       56
        
       `nixosConfiguration` to do so.

     

       57
       57
        
       

     

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

     

       59
       59
       +
       

     

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

     

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

     

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

     

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

     

       64
       64
       +
       if you are using Apple Silicon).

     

       65
       65
       +
       

     

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

     

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

     

       68
       68
       +
       > you can do

     

       69
       69
       +
       >

     

       70
       70
       +
       > ```shell

     

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

     

       72
       72
       +
       > ```

     

       73
       73
       +
       >

     

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

     

       75
       75
       +
       >

     

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

     

       77
       77
       +
       >  avoid subtle problems.

     

       78
       78
       +
       

     

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

     

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

     

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

     

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

     

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

     

       84
       84
       +
       

     

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

     

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

     

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

     

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

     

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

     

       90
       90
       +
       

     

       91
       91
       +
       [darwin builder vm]:

     

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

     

       93
       93
       +
       [remote builder instructions]:

     

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

     

       95
       95
       +
       

     

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

     

       97
       97
       +
       

     

       58
       98
        
       To begin, head to `http://localhost:3000/knots` in the browser

     

       59
       99
        
       and create a knot with hostname `localhost:6000`. This will

     

       60
       100
        
       generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it,

     
···

       95
       135
        
       git push local-dev main

     

       96
       136
        
       ```

     

       97
       137
        
       

     

       98
       98
       -
       ## running a spindle

     

       138
       138
       +
       ### running a spindle

     

       99
       139
        
       

     

       100
       140
        
       You will need to find out your DID by entering your login handle into

     

       101
       101
       -
       <https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID.

     

       141
       141
       +
       <https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID and follow the

     

       142
       142
       +
       instructions in the previous section.

     

       102
       143
        
       

     

       103
       103
       -
       The above VM should already be running a spindle on `localhost:6555`.

     

       104
       104
       -
       You can head to the spindle dashboard on `http://localhost:3000/spindles`,

     

       105
       105
       -
       and register a spindle with hostname `localhost:6555`. It should instantly

     

       106
       106
       -
       be verified. You can then configure each repository to use this spindle

     

       107
       107
       -
       and run CI jobs.

     

       144
       144
       +
       The dev VM should be running a spindle on `localhost:6555`. You can head to the

     

       145
       145
       +
       spindle dashboard on `http://localhost:3000/spindles`, and register a spindle

     

       146
       146
       +
       with hostname `localhost:6555`. It should instantly be verified. You can then

     

       147
       147
       +
       configure each repository to use this spindle and run CI jobs.

     

       108
       148
        
       

     

       109
       149
        
       Of interest when debugging spindles:

     

       110
       150