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