kot.pink
1# hacking on tangled
2
3We highly recommend [installing
4nix](https://nixos.org/download/) (the package manager)
5before working on the codebase. The nix flake provides a lot
6of helpers to get started and most importantly, builds and
7dev shells are entirely deterministic.
8
9To set up your dev environment:
10
11```bash
12nix develop
13```
14
15Non-nix users can look at the `devShell` attribute in the
16`flake.nix` file to determine necessary dependencies.
17
18## running the appview
19
20The nix flake also exposes a few `app` attributes (run `nix
21flake show` to see a full list of what the flake provides),
22one of the apps runs the appview with the `air`
23live-reloader:
24
25```bash
26TANGLED_DEV=true nix run .#watch-appview
27
28# TANGLED_DB_PATH might be of interest to point to
29# different sqlite DBs
30
31# in a separate shell, you can live-reload tailwind
32nix run .#watch-tailwind
33```
34
35To authenticate with the appview, you will need redis and
36OAUTH JWKs to be setup:
37
38```
39# oauth jwks should already be setup by the nix devshell:
40echo $TANGLED_OAUTH_JWKS
41{"crv":"P-256","d":"tELKHYH-Dko6qo4ozYcVPE1ah6LvXHFV2wpcWpi8ab4","kid":"1753352226","kty":"EC","x":"mRzYpLzAGq74kJez9UbgGfV040DxgsXpMbaVsdy8RZs","y":"azqqXzUYywMlLb2Uc5AVG18nuLXyPnXr4kI4T39eeIc"}
42
43# if not, you can set it up yourself:
44go build -o genjwks.out ./cmd/genjwks
45export TANGLED_OAUTH_JWKS="$(./genjwks.out)"
46
47# run redis in at a new shell to store oauth sessions
48redis-server
49```
50
51## running knots and spindles in a VM
52
53An end-to-end knot setup requires setting up a machine with
54`sshd`, `AuthorizedKeysCommand`, and git user, which is
55quite cumbersome. So the nix flake provides a
56`nixosConfiguration` to do so.
57
58### Mac-specific: setting up a Nix builder
59
60In order to build Tangled's dev VM on macOS, you will first need to set up a
61Linux 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`
63as a builder for Linux with the same architecture as your Mac (`linux-aarch64`
64if 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
79Alternatively, you can use any other method to set up a Linux machine with `nix`
80installed that you can `sudo ssh` into (in other words, root user on your Mac
81has to be able to ssh into the Linux machine without entering a password) and
82that has the same architecture as your Mac. See [remote builder instructions]
83for 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
98To begin, grab your DID from http://localhost:3000/settings.
99Then, set `TANGLED_VM_KNOT_OWNER` and
100`TANGLED_VM_SPINDLE_OWNER` to your DID.
101
102If you don't want to [set up a spindle](#running-a-spindle),
103you can use any placeholder value.
104
105You can now start a lightweight NixOS VM like so:
106
107```bash
108nix run --impure .#vm
109
110# type `poweroff` at the shell to exit the VM
111```
112
113This starts a knot on port 6000, a spindle on port 6555
114with `ssh` exposed on port 2222.
115
116Once the services are running, head to
117http://localhost:3000/knots and hit verify (and similarly,
118http://localhost:3000/spindles to verify your spindle). It
119should verify the ownership of the services instantly if
120everything went smoothly.
121
122You can push repositories to this VM with this ssh config
123block on your main machine:
124
125```bash
126Host nixos-shell
127 Hostname localhost
128 Port 2222
129 User git
130 IdentityFile ~/.ssh/my_tangled_key
131```
132
133Set up a remote called `local-dev` on a git repo:
134
135```bash
136git remote add local-dev git@nixos-shell:user/repo
137git push local-dev main
138```
139
140### running a spindle
141
142The above VM should already be running a spindle on
143`localhost:6555`. Head to http://localhost:3000/spindles and
144hit verify. You can then configure each repository to use
145this spindle and run CI jobs.
146
147Of interest when debugging spindles:
148
149```
150# service logs from journald:
151journalctl -xeu spindle
152
153# CI job logs from disk:
154ls /var/log/spindle
155
156# debugging spindle db:
157sqlite3 /var/lib/spindle/spindle.db
158
159# litecli has a nicer REPL interface:
160litecli /var/lib/spindle/spindle.db
161```