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 a knot
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
58To begin, grab your DID from http://localhost:3000/settings.
59Then, set `TANGLED_VM_KNOT_OWNER` and
60`TANGLED_VM_SPINDLE_OWNER` to your DID.
61
62If you don't want to [set up a spindle](#running-a-spindle),
63you can use any placeholder value.
64
65You can now start a lightweight NixOS VM like so:
66
67```bash
68nix run --impure .#vm
69
70# type `poweroff` at the shell to exit the VM
71```
72
73This starts a knot on port 6000, a spindle on port 6555
74with `ssh` exposed on port 2222.
75
76Once the services are running, head to
77http://localhost:3000/knots and hit verify (and similarly,
78http://localhost:3000/spindles to verify your spindle). It
79should verify the ownership of the services instantly if
80everything went smoothly.
81
82You can push repositories to this VM with this ssh config
83block on your main machine:
84
85```bash
86Host nixos-shell
87 Hostname localhost
88 Port 2222
89 User git
90 IdentityFile ~/.ssh/my_tangled_key
91```
92
93Set up a remote called `local-dev` on a git repo:
94
95```bash
96git remote add local-dev git@nixos-shell:user/repo
97git push local-dev main
98```
99
100## running a spindle
101
102The above VM should already be running a spindle on
103`localhost:6555`. Head to http://localhost:3000/spindles and
104hit verify. You can then configure each repository to use
105this spindle and run CI jobs.
106
107Of interest when debugging spindles:
108
109```
110# service logs from journald:
111journalctl -xeu spindle
112
113# CI job logs from disk:
114ls /var/log/spindle
115
116# debugging spindle db:
117sqlite3 /var/lib/spindle/spindle.db
118
119# litecli has a nicer REPL interface:
120litecli /var/lib/spindle/spindle.db
121```