From 6d1ed750fbc057f473cb9cb6754fc659e06ad0aa Mon Sep 17 00:00:00 2001 From: oppiliappan Date: Thu, 28 Aug 2025 20:39:56 +0000 Subject: [PATCH] docs: clean up VM instructions a bit Signed-off-by: oppiliappan --- docs/hacking.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------- 1 file(s) changed, 46 insertion(s)(+), 45 deletion(s)(-) diff --git a/docs/hacking.md b/docs/hacking.md --- a/docs/hacking.md +++ b/docs/hacking.md @@ -48,61 +48,58 @@ # run redis in at a new shell to store oauth sessions redis-server ``` -## running knots and spindles in a VM +## running knots and spindles 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 +
+ MacOS users will have to setup a Nix Builder first -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). + 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](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder) + 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. + > 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`. + 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](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements) + 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). + > 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, grab your DID from http://localhost:3000/settings. Then, set `TANGLED_VM_KNOT_OWNER` and -`TANGLED_VM_SPINDLE_OWNER` to your DID. - -If you don't want to [set up a spindle](#running-a-spindle), -you can use any placeholder value. - -You can now start a lightweight NixOS VM like so: +`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a +lightweight NixOS VM like so: ```bash nix run --impure .#vm @@ -114,10 +111,9 @@ This starts a knot on port 6000, a spindle on port 6555 with `ssh` exposed on port 2222. Once the services are running, head to -http://localhost:3000/knots and hit verify (and similarly, -http://localhost:3000/spindles to verify your spindle). It -should verify the ownership of the services instantly if -everything went smoothly. +http://localhost:3000/knots and hit verify. It should +verify the ownership of the services instantly if everything +went smoothly. You can push repositories to this VM with this ssh config block on your main machine: @@ -159,3 +155,8 @@ # litecli has a nicer REPL interface: litecli /var/lib/spindle/spindle.db ``` + +If for any reason you wish to disable either one of the +services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set +`services.tangled-spindle.enable` (or +`services.tangled-knot.enable`) to `false`. -- tangled.sh