From 161b5275dc103d5b5df8805fd736209cf6590b90 Mon Sep 17 00:00:00 2001 From: oppiliappan Date: Fri, 22 Aug 2025 10:52:29 +0100 Subject: [PATCH] docs: update knot hosting and hacking guide Signed-off-by: oppiliappan --- docs/hacking.md | 38 +++++++++++++++++----------------- docs/knot-hosting.md | 12 ++++++----- docs/migrations/knot-1.7.0.md | 39 +++++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+), 24 deletions(-) create mode 100644 docs/migrations/knot-1.7.0.md diff --git a/docs/hacking.md b/docs/hacking.md index 427596dc..fa64c1c1 100644 --- a/docs/hacking.md +++ b/docs/hacking.md @@ -55,16 +55,12 @@ An end-to-end knot setup requires setting up a machine with quite cumbersome. So the nix flake provides a `nixosConfiguration` to do so. -To begin, head to `http://localhost:3000/knots` in the browser -and create a knot with hostname `localhost:6000`. This will -generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it, -ideally in a `.envrc` with [direnv](https://direnv.net) so you -don't lose it. +To begin, grab your DID from http://localhost:3000/settings. +Then, set `TANGLED_VM_KNOT_OWNER` and +`TANGLED_VM_SPINDLE_OWNER` to your DID. -You will also need to set the `$TANGLED_VM_SPINDLE_OWNER` -variable to some value. If you don't want to [set up a -spindle](#running-a-spindle), you can use any placeholder -value. +If you don't want to [set up a spindle](#running-a-spindle), +you can use any placeholder value. You can now start a lightweight NixOS VM like so: @@ -75,8 +71,16 @@ nix run --impure .#vm ``` This starts a knot on port 6000, a spindle on port 6555 -with `ssh` exposed on port 2222. You can push repositories -to this VM with this ssh config block on your main machine: +with `ssh` exposed on port 2222. + +Once the services are running, head to +http://localhost:3000/knots and hit verify (and similarly, +http://localhost:3000/spindles to verify your spindle). It +should verify the ownership of the services instantly if +everything went smoothly. + +You can push repositories to this VM with this ssh config +block on your main machine: ```bash Host nixos-shell @@ -95,14 +99,10 @@ git push local-dev main ## running a spindle -You will need to find out your DID by entering your login handle into -. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID. - -The above VM should already be running a spindle on `localhost:6555`. -You can head to the spindle dashboard on `http://localhost:3000/spindles`, -and register a spindle with hostname `localhost:6555`. It should instantly -be verified. You can then configure each repository to use this spindle -and run CI jobs. +The above VM should already be running a spindle on +`localhost:6555`. Head to http://localhost:3000/spindles and +hit verify. You can then configure each repository to use +this spindle and run CI jobs. Of interest when debugging spindles: diff --git a/docs/knot-hosting.md b/docs/knot-hosting.md index f27de5aa..b6a5f219 100644 --- a/docs/knot-hosting.md +++ b/docs/knot-hosting.md @@ -73,14 +73,14 @@ sudo adduser git ``` Create `/home/git/.knot.env` with the following, updating the values as -necessary. The `KNOT_SERVER_SECRET` can be obtained from the -[/knots](https://tangled.sh/knots) page on Tangled. +necessary. The `KNOT_SERVER_OWNER` should be set to your +DID, you can find your DID in the [Settings](https://tangled.sh/settings) page. ``` KNOT_REPO_SCAN_PATH=/home/git KNOT_SERVER_HOSTNAME=knot.example.com APPVIEW_ENDPOINT=https://tangled.sh -KNOT_SERVER_SECRET=secret +KNOT_SERVER_OWNER=did:plc:foobar KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444 KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555 ``` @@ -128,8 +128,10 @@ server { Remember to use Let's Encrypt or similar to procure a certificate for your knot domain. -You should now have a running knot server! You can finalize your registration by hitting the -`initialize` button on the [/knots](https://tangled.sh/knots) page. +You should now have a running knot server! You can finalize +your registration by hitting the `verify` button on the +[/knots](https://tangled.sh/knots) page. This simply creates +a record on your PDS to announce the existence of the knot. ### custom paths diff --git a/docs/migrations/knot-1.7.0.md b/docs/migrations/knot-1.7.0.md new file mode 100644 index 00000000..b18199f8 --- /dev/null +++ b/docs/migrations/knot-1.7.0.md @@ -0,0 +1,39 @@ +# Upgrading from v1.7.0 + +After v1.7.0, knot secrets have been deprecated. You no +longer need a secret from the appview to run a knot. All +authorized commands between services to knots are managed +via [Service +Auth](https://atproto.com/specs/xrpc#inter-service-authentication-jwt). +Knots will be read-only until upgraded. + +Upgrading is quite easy, in essence: + +- `KNOT_SERVER_SECRET` is no more, you can remove this + environment variable entirely +- `KNOT_SERVER_OWNER` is now required on boot, set this to + your DID. You can find your DID in the + [settings](https://tangled.sh/settings) page. +- Restart your knot once you have replace the environment + variable +- Head to the [knot dashboard](https://tangled.sh/knots) and + hit the "retry" button to verify your knot. This simply + writes a `sh.tangled.knot` record to your PDS. + +## Nix + +If you use the nix module, simply bump the flake to the +latest revision, and change your config block like so: + +```diff + services.tangled-knot = { + enable = true; + server = { +- secretFile = /path/to/secret; ++ owner = "did:plc:foo"; + . + . + . + }; + }; +``` -- 2.51.2