lewis.moe
forked from
tangled.org/core
Monorepo for Tangled
docs: update knot hosting and hacking guide
Signed-off-by: oppiliappan <me@oppi.li>
oppi.li
+19
-19
docs/hacking.md
+19
-19
docs/hacking.md
···
55
quite cumbersome. So the nix flake provides a
56
`nixosConfiguration` to do so.
57
58
-
To begin, head to `http://localhost:3000/knots` in the browser
59
-
and create a knot with hostname `localhost:6000`. This will
60
-
generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it,
61
-
ideally in a `.envrc` with [direnv](https://direnv.net) so you
62
-
don't lose it.
63
64
-
You will also need to set the `$TANGLED_VM_SPINDLE_OWNER`
65
-
variable to some value. If you don't want to [set up a
66
-
spindle](#running-a-spindle), you can use any placeholder
67
-
value.
68
69
You can now start a lightweight NixOS VM like so:
70
···
75
```
76
77
This starts a knot on port 6000, a spindle on port 6555
78
-
with `ssh` exposed on port 2222. You can push repositories
79
-
to this VM with this ssh config block on your main machine:
80
81
```bash
82
Host nixos-shell
···
95
96
## running a spindle
97
98
-
You will need to find out your DID by entering your login handle into
99
-
<https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID.
100
-
101
-
The above VM should already be running a spindle on `localhost:6555`.
102
-
You can head to the spindle dashboard on `http://localhost:3000/spindles`,
103
-
and register a spindle with hostname `localhost:6555`. It should instantly
104
-
be verified. You can then configure each repository to use this spindle
105
-
and run CI jobs.
106
107
Of interest when debugging spindles:
108
···
55
quite cumbersome. So the nix flake provides a
56
`nixosConfiguration` to do so.
57
58
+
To begin, grab your DID from http://localhost:3000/settings.
59
+
Then, set `TANGLED_VM_KNOT_OWNER` and
60
+
`TANGLED_VM_SPINDLE_OWNER` to your DID.
61
62
+
If you don't want to [set up a spindle](#running-a-spindle),
63
+
you can use any placeholder value.
64
65
You can now start a lightweight NixOS VM like so:
66
···
71
```
72
73
This starts a knot on port 6000, a spindle on port 6555
74
+
with `ssh` exposed on port 2222.
75
+
76
+
Once the services are running, head to
77
+
http://localhost:3000/knots and hit verify (and similarly,
78
+
http://localhost:3000/spindles to verify your spindle). It
79
+
should verify the ownership of the services instantly if
80
+
everything went smoothly.
81
+
82
+
You can push repositories to this VM with this ssh config
83
+
block on your main machine:
84
85
```bash
86
Host nixos-shell
···
99
100
## running a spindle
101
102
+
The above VM should already be running a spindle on
103
+
`localhost:6555`. Head to http://localhost:3000/spindles and
104
+
hit verify. You can then configure each repository to use
105
+
this spindle and run CI jobs.
106
107
Of interest when debugging spindles:
108
+7
-5
docs/knot-hosting.md
+7
-5
docs/knot-hosting.md
···
73
```
74
75
Create `/home/git/.knot.env` with the following, updating the values as
76
-
necessary. The `KNOT_SERVER_SECRET` can be obtained from the
77
-
[/knots](https://tangled.sh/knots) page on Tangled.
78
79
```
80
KNOT_REPO_SCAN_PATH=/home/git
81
KNOT_SERVER_HOSTNAME=knot.example.com
82
APPVIEW_ENDPOINT=https://tangled.sh
83
-
KNOT_SERVER_SECRET=secret
84
KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
85
KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
86
```
···
128
Remember to use Let's Encrypt or similar to procure a certificate for your
129
knot domain.
130
131
-
You should now have a running knot server! You can finalize your registration by hitting the
132
-
`initialize` button on the [/knots](https://tangled.sh/knots) page.
133
134
### custom paths
135
···
73
```
74
75
Create `/home/git/.knot.env` with the following, updating the values as
76
+
necessary. The `KNOT_SERVER_OWNER` should be set to your
77
+
DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.
78
79
```
80
KNOT_REPO_SCAN_PATH=/home/git
81
KNOT_SERVER_HOSTNAME=knot.example.com
82
APPVIEW_ENDPOINT=https://tangled.sh
83
+
KNOT_SERVER_OWNER=did:plc:foobar
84
KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
85
KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
86
```
···
128
Remember to use Let's Encrypt or similar to procure a certificate for your
129
knot domain.
130
131
+
You should now have a running knot server! You can finalize
132
+
your registration by hitting the `verify` button on the
133
+
[/knots](https://tangled.sh/knots) page. This simply creates
134
+
a record on your PDS to announce the existence of the knot.
135
136
### custom paths
137
+39
docs/migrations/knot-1.7.0.md
+39
docs/migrations/knot-1.7.0.md
···
···
1
+
# Upgrading from v1.7.0
2
+
3
+
After v1.7.0, knot secrets have been deprecated. You no
4
+
longer need a secret from the appview to run a knot. All
5
+
authorized commands between services to knots are managed
6
+
via [Service
7
+
Auth](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
8
+
Knots will be read-only until upgraded.
9
+
10
+
Upgrading is quite easy, in essence:
11
+
12
+
- `KNOT_SERVER_SECRET` is no more, you can remove this
13
+
environment variable entirely
14
+
- `KNOT_SERVER_OWNER` is now required on boot, set this to
15
+
your DID. You can find your DID in the
16
+
[settings](https://tangled.sh/settings) page.
17
+
- Restart your knot once you have replace the environment
18
+
variable
19
+
- Head to the [knot dashboard](https://tangled.sh/knots) and
20
+
hit the "retry" button to verify your knot. This simply
21
+
writes a `sh.tangled.knot` record to your PDS.
22
+
23
+
## Nix
24
+
25
+
If you use the nix module, simply bump the flake to the
26
+
latest revision, and change your config block like so:
27
+
28
+
```diff
29
+
services.tangled-knot = {
30
+
enable = true;
31
+
server = {
32
+
- secretFile = /path/to/secret;
33
+
+ owner = "did:plc:foo";
34
+
.
35
+
.
36
+
.
37
+
};
38
+
};
39
+
```