patch of hacking.md: mac-specific VM instructions · round #1 · pull #489 · tangled.org/core

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

+48 -8

docs/hacking.md

··· 48 48 redis-server 49 49 ``` 50 50 51 - ## running a knot 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 + ### Mac-specific: setting up a Nix builder 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). 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`. 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 + 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 - ## running a spindle 138 + ### running a spindle 99 139 100 140 You will need to find out your DID by entering your login handle into 101 - <https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID. 141 + <https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID and follow the 142 + instructions in the previous section. 102 143 103 - The above VM should already be running a spindle on `localhost:6555`. 104 - You can head to the spindle dashboard on `http://localhost:3000/spindles`, 105 - and register a spindle with hostname `localhost:6555`. It should instantly 106 - be verified. You can then configure each repository to use this spindle 107 - and run CI jobs. 144 + The dev VM should be running a spindle on `localhost:6555`. You can head to the 145 + spindle dashboard on `http://localhost:3000/spindles`, and register a spindle 146 + with hostname `localhost:6555`. It should instantly be verified. You can then 147 + configure each repository to use this spindle and run CI jobs. 108 148 109 149 Of interest when debugging spindles: 110 150