veryroundbird.house
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
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<details>
59 <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary>
60
61 In order to build Tangled's dev VM on macOS, you will
62 first need to set up a Linux Nix builder. The recommended
63 way to do so is to run a [`darwin.linux-builder`
64 VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)
65 and to register it in `nix.conf` as a builder for Linux
66 with the same architecture as your Mac (`linux-aarch64` if
67 you are using Apple Silicon).
68
69 > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside
70 > the tangled repo so that it doesn't conflict with the other VM. For example,
71 > you can do
72 >
73 > ```shell
74 > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder
75 > ```
76 >
77 > to store the builder VM in a temporary dir.
78 >
79 > You should read and follow [all the other intructions][darwin builder vm] to
80 > avoid subtle problems.
81
82 Alternatively, you can use any other method to set up a
83 Linux machine with `nix` installed that you can `sudo ssh`
84 into (in other words, root user on your Mac has to be able
85 to ssh into the Linux machine without entering a password)
86 and that has the same architecture as your Mac. See
87 [remote builder
88 instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)
89 for how to register such a builder in `nix.conf`.
90
91 > WARNING: If you'd like to use
92 > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
93 > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
94 > ssh` works can be tricky. It seems to be [possible with
95 > Orbstack](https://github.com/orgs/orbstack/discussions/1669).
96
97</details>
98
99To begin, grab your DID from http://localhost:3000/settings.
100Then, set `TANGLED_VM_KNOT_OWNER` and
101`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a
102lightweight NixOS VM like so:
103
104```bash
105nix run --impure .#vm
106
107# type `poweroff` at the shell to exit the VM
108```
109
110This starts a knot on port 6000, a spindle on port 6555
111with `ssh` exposed on port 2222.
112
113Once the services are running, head to
114http://localhost:3000/knots and hit verify. It should
115verify the ownership of the services instantly if everything
116went smoothly.
117
118You can push repositories to this VM with this ssh config
119block on your main machine:
120
121```bash
122Host nixos-shell
123 Hostname localhost
124 Port 2222
125 User git
126 IdentityFile ~/.ssh/my_tangled_key
127```
128
129Set up a remote called `local-dev` on a git repo:
130
131```bash
132git remote add local-dev git@nixos-shell:user/repo
133git push local-dev main
134```
135
136### running a spindle
137
138The above VM should already be running a spindle on
139`localhost:6555`. Head to http://localhost:3000/spindles and
140hit verify. You can then configure each repository to use
141this spindle and run CI jobs.
142
143Of interest when debugging spindles:
144
145```
146# service logs from journald:
147journalctl -xeu spindle
148
149# CI job logs from disk:
150ls /var/log/spindle
151
152# debugging spindle db:
153sqlite3 /var/lib/spindle/spindle.db
154
155# litecli has a nicer REPL interface:
156litecli /var/lib/spindle/spindle.db
157```
158
159If for any reason you wish to disable either one of the
160services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set
161`services.tangled-spindle.enable` (or
162`services.tangled-knot.enable`) to `false`.