tangled.org
+42
-2
docs/hacking.md
+42
-2
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, grab your DID from http://localhost:3000/settings.
59
99
Then, set `TANGLED_VM_KNOT_OWNER` and
60
100
`TANGLED_VM_SPINDLE_OWNER` to your DID.
···
97
137
git push local-dev main
98
138
```
99
139
100
-
## running a spindle
140
+
### running a spindle
101
141
102
142
The above VM should already be running a spindle on
103
143
`localhost:6555`. Head to http://localhost:3000/spindles and