From 6d36b54d35eda4c54632ecdd0f068e8d905e0058 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Mon, 11 Aug 2025 15:45:05 -0700 Subject: [PATCH] hacking.md: mac-specific VM instructions Change-Id: vtrtqqwxpxpzvnuyronskwzlnzwwwsuu 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 --- docs/hacking.md | 56 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/hacking.md b/docs/hacking.md index 62940aa..1121177 100644 --- a/docs/hacking.md +++ b/docs/hacking.md @@ -48,13 +48,53 @@ export TANGLED_OAUTH_JWKS="$(./genjwks.out)" redis-server ``` -## running a knot +## running knots and spindles in a VM An end-to-end knot setup requires setting up a machine with `sshd`, `AuthorizedKeysCommand`, and git user, which is quite cumbersome. So the nix flake provides a `nixosConfiguration` to do so. +### Mac-specific: setting up a Nix builder + +In order to build Tangled's dev VM on macOS, you will first need to set up a +Linux Nix builder. The recommended way to do so is to run a +[`darwin.linux-builder` VM][darwin builder vm] and to register it in `nix.conf` +as a builder for Linux with the same architecture as your Mac (`linux-aarch64` +if you are using Apple Silicon). + +> IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside +> the tangled repo so that it doesn't conflict with the other VM. For example, +> you can do +> +> ```shell +> cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder +> ``` +> +> to store the builder VM in a temporary dir. +> +> You should read and follow [all the other intructions][darwin builder vm] to +> avoid subtle problems. + +Alternatively, you can use any other method to set up a Linux machine with `nix` +installed that you can `sudo ssh` into (in other words, root user on your Mac +has to be able to ssh into the Linux machine without entering a password) and +that has the same architecture as your Mac. See [remote builder instructions] +for how to register such a builder in `nix.conf`. + +> WARNING: If you'd like to use +> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or +> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo +> ssh` works can be tricky. It seems to be [possible with +> Orbstack](https://github.com/orgs/orbstack/discussions/1669). + +[darwin builder vm]: + https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder +[remote builder instructions]: + https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements + +### Running a knot on a dev VM + To begin, head to `http://localhost:3000/knots` in the browser and create a knot with hostname `localhost:6000`. This will generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it, @@ -95,16 +135,16 @@ git remote add local-dev git@nixos-shell:user/repo git push local-dev main ``` -## running a spindle +### running a spindle You will need to find out your DID by entering your login handle into -. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID. +. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID and follow the +instructions in the previous section. -The above VM should already be running a spindle on `localhost:6555`. -You can head to the spindle dashboard on `http://localhost:3000/spindles`, -and register a spindle with hostname `localhost:6555`. It should instantly -be verified. You can then configure each repository to use this spindle -and run CI jobs. +The dev VM should be running a spindle on `localhost:6555`. You can head to the +spindle dashboard on `http://localhost:3000/spindles`, and register a spindle +with hostname `localhost:6555`. It should instantly be verified. You can then +configure each repository to use this spindle and run CI jobs. Of interest when debugging spindles: -- 2.43.0