dvjn.dev
stacked pull on docs: add hacking.md #99
+72
docs/hacking.md
+72
docs/hacking.md
···
1
+
# hacking on tangled
2
+
3
+
We highly recommend [installing
4
+
nix](https://nixos.org/download/) (the package manager)
5
+
before working on the codebase. The nix flake provides a lot
6
+
of helpers to get started and most importantly, builds and
7
+
dev shells are entirely deterministic.
8
+
9
+
To set up your dev environment:
10
+
11
+
```bash
12
+
nix develop
13
+
```
14
+
15
+
Non-nix users can look at the `devShell` attribute in the
16
+
`flake.nix` file to determine necessary dependencies.
17
+
18
+
## running the appview
19
+
20
+
The nix flake also exposes a few `app` attributes (run `nix
21
+
flake show` to see a full list of what the flake provides),
22
+
one of the apps runs the appview with the `air`
23
+
live-reloader:
24
+
25
+
```bash
26
+
TANGLED_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
32
+
nix run .#watch-tailwind
33
+
```
34
+
35
+
## running a knotserver
36
+
37
+
An end-to-end knotserver setup requires setting up a machine
38
+
with `sshd`, `repoguard`, `keyfetch`, a git user, which is
39
+
quite cumbersome and so the nix flake provides a
40
+
`nixosConfiguration` to do so.
41
+
42
+
To begin, head to `http://localhost:3000` in the browser and
43
+
generate a knotserver secret. Replace the existing secret in
44
+
`flake.nix` with the newly generated secret.
45
+
46
+
You can now start a lightweight NixOS VM using
47
+
`nixos-shell` like so:
48
+
49
+
```bash
50
+
QEMU_NET_OPTS="hostfwd=tcp::6000-:6000,hostfwd=tcp::2222-:22" nixos-shell --flake .#knotVM
51
+
52
+
# hit Ctrl-a + c + q to exit the VM
53
+
```
54
+
55
+
This starts a knotserver on port 6000 with `ssh` exposed on
56
+
port 2222. You can push repositories to this VM with this
57
+
ssh config block on your main machine:
58
+
59
+
```bash
60
+
Host nixos-shell
61
+
Hostname localhost
62
+
Port 2222
63
+
User git
64
+
IdentityFile ~/.ssh/my_tangled_key
65
+
```
66
+
67
+
Set up a remote called `local-dev` on a git repo:
68
+
69
+
```bash
70
+
git remote add local-dev git@nixos-shell:user/repo
71
+
git push local-dev main
72
+
```
+1
-4
cmd/genjwks/main.go
+1
-4
cmd/genjwks/main.go
+3
flake.nix
+3
flake.nix
···
123
123
};
124
124
repoguard = buildCmdPackage "repoguard";
125
125
keyfetch = buildCmdPackage "keyfetch";
126
+
genjwks = buildCmdPackage "genjwks";
126
127
};
127
128
packages = forAllSystems (system: {
128
129
inherit
···
133
134
knotserver-unwrapped
134
135
repoguard
135
136
keyfetch
137
+
genjwks
136
138
;
137
139
});
138
140
defaultPackage = forAllSystems (system: nixpkgsFor.${system}.appview);
···
162
164
cp -f ${inter-fonts-src}/web/InterVariable*.woff2 appview/pages/static/fonts/
163
165
cp -f ${inter-fonts-src}/web/InterDisplay*.woff2 appview/pages/static/fonts/
164
166
cp -f ${ibm-plex-mono-src}/fonts/complete/woff2/IBMPlexMono-Regular.woff2 appview/pages/static/fonts/
167
+
export TANGLED_OAUTH_JWKS="$(${pkgs.genjwks}/bin/genjwks)"
165
168
'';
166
169
env.CGO_ENABLED = 1;
167
170
};
+7
scripts/run-knotserver-vm.sh
+7
scripts/run-knotserver-vm.sh
+7
scripts/watch-appview.sh
+7
scripts/watch-appview.sh
+11
scripts/watch-knotserver.sh
+11
scripts/watch-knotserver.sh
···
1
+
#! /usr/bin/env bash
2
+
3
+
set -e
4
+
5
+
export TANGLED_DEV=true
6
+
export KNOT_SERVER_SECRET=e63d7a46b5d9d6646d30562642986899aad755a2b3912bf748dfc7989e612770
7
+
export KNOT_SERVER_HOSTNAME=localhost
8
+
export APPVIEW_ENDPOINT=http://127.0.0.1:3000
9
+
export KNOT_REPO_SCAN_PATH=./repos
10
+
11
+
nix develop --command nix run .#watch-knotserver