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, head to `http://localhost:3000/knots` in the browser
59and create a knot with hostname `localhost:6000`. This will
60generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it,
61ideally in a `.envrc` with [direnv](https://direnv.net) so you
62don't lose it.
63
64You will also need to set the `$TANGLED_VM_SPINDLE_OWNER`
65variable to some value. If you don't want to [set up a
66spindle](#running-a-spindle), you can use any placeholder
67value.
68
69You can now start a lightweight NixOS VM using
70`nixos-shell` like so:
71
72```bash
73nix run .#vm
74# or nixos-shell --flake .#vm
75
76# hit Ctrl-a + c + q to exit the VM
77```
78
79This starts a knot on port 6000, a spindle on port 6555
80with `ssh` exposed on port 2222. You can push repositories
81to this VM with this ssh config block on your main machine:
82
83```bash
84Host nixos-shell
85 Hostname localhost
86 Port 2222
87 User git
88 IdentityFile ~/.ssh/my_tangled_key
89```
90
91Set up a remote called `local-dev` on a git repo:
92
93```bash
94git remote add local-dev git@nixos-shell:user/repo
95git push local-dev main
96```
97
98## running a spindle
99
100You 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.
102
103The above VM should already be running a spindle on `localhost:6555`.
104You can head to the spindle dashboard on `http://localhost:3000/spindles`,
105and register a spindle with hostname `localhost:6555`. It should instantly
106be verified. You can then configure each repository to use this spindle
107and run CI jobs.
108
109Of interest when debugging spindles:
110
111```
112# service logs from journald:
113journalctl -xeu spindle
114
115# CI job logs from disk:
116ls /var/log/spindle
117
118# debugging spindle db:
119sqlite3 /var/lib/spindle/spindle.db
120
121# litecli has a nicer REPL interface:
122litecli /var/lib/spindle/spindle.db
123```