ilyagr.bsky.social
+48
-8
docs/hacking.md
+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