commit 161b5275dc103d5b5df8805fd736209cf6590b90 · veryroundbird.house/core

+19 -19

docs/hacking.md

···

       55
       55
        
       quite cumbersome. So the nix flake provides a

     

       56
       56
        
       `nixosConfiguration` to do so.

     

       57
       57
        
       

     

       58
       58
       -
       To begin, head to `http://localhost:3000/knots` in the browser

     

       59
       59
       -
       and create a knot with hostname `localhost:6000`. This will

     

       60
       60
       -
       generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it,

     

       61
       61
       -
       ideally in a `.envrc` with [direnv](https://direnv.net) so you

     

       62
       62
       -
       don't lose it.

     

       58
       58
       +
       To begin, grab your DID from http://localhost:3000/settings.

     

       59
       59
       +
       Then, set `TANGLED_VM_KNOT_OWNER` and

     

       60
       60
       +
       `TANGLED_VM_SPINDLE_OWNER` to your DID.

     

       63
       61
        
       

     

       64
       64
       -
       You will also need to set the `$TANGLED_VM_SPINDLE_OWNER`

     

       65
       65
       -
       variable to some value. If you don't want to [set up a

     

       66
       66
       -
       spindle](#running-a-spindle), you can use any placeholder

     

       67
       67
       -
       value.

     

       62
       62
       +
       If you don't want to [set up a spindle](#running-a-spindle),

     

       63
       63
       +
       you can use any placeholder value.

     

       68
       64
        
       

     

       69
       65
        
       You can now start a lightweight NixOS VM like so:

     

       70
       66
        
       

     
···

       75
       71
        
       ```

     

       76
       72
        
       

     

       77
       73
        
       This starts a knot on port 6000, a spindle on port 6555

     

       78
       78
       -
       with `ssh` exposed on port 2222. You can push repositories

     

       79
       79
       -
       to this VM with this ssh config block on your main machine:

     

       74
       74
       +
       with `ssh` exposed on port 2222.

     

       75
       75
       +
       

     

       76
       76
       +
       Once the services are running, head to

     

       77
       77
       +
       http://localhost:3000/knots and hit verify (and similarly,

     

       78
       78
       +
       http://localhost:3000/spindles to verify your spindle). It

     

       79
       79
       +
       should verify the ownership of the services instantly if

     

       80
       80
       +
       everything went smoothly.

     

       81
       81
       +
       

     

       82
       82
       +
       You can push repositories to this VM with this ssh config

     

       83
       83
       +
       block on your main machine:

     

       80
       84
        
       

     

       81
       85
        
       ```bash

     

       82
       86
        
       Host nixos-shell

     
···

       95
       99
        
       

     

       96
       100
        
       ## running a spindle

     

       97
       101
        
       

     

       98
       98
       -
       You will need to find out your DID by entering your login handle into

     

       99
       99
       -
       <https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID.

     

       100
       100
       -
       

     

       101
       101
       -
       The above VM should already be running a spindle on `localhost:6555`.

     

       102
       102
       -
       You can head to the spindle dashboard on `http://localhost:3000/spindles`,

     

       103
       103
       -
       and register a spindle with hostname `localhost:6555`. It should instantly

     

       104
       104
       -
       be verified. You can then configure each repository to use this spindle

     

       105
       105
       -
       and run CI jobs.

     

       102
       102
       +
       The above VM should already be running a spindle on

     

       103
       103
       +
       `localhost:6555`. Head to http://localhost:3000/spindles and

     

       104
       104
       +
       hit verify. You can then configure each repository to use

     

       105
       105
       +
       this spindle and run CI jobs.

     

       106
       106
        
       

     

       107
       107
        
       Of interest when debugging spindles:

     

       108
       108

+7 -5

docs/knot-hosting.md

···

       73
       73
        
       ```

     

       74
       74
        
       

     

       75
       75
        
       Create `/home/git/.knot.env` with the following, updating the values as

     

       76
       76
       -
       necessary. The `KNOT_SERVER_SECRET` can be obtained from the

     

       77
       77
       -
       [/knots](https://tangled.sh/knots) page on Tangled.

     

       76
       76
       +
       necessary. The `KNOT_SERVER_OWNER` should be set to your

     

       77
       77
       +
       DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.

     

       78
       78
        
       

     

       79
       79
        
       ```

     

       80
       80
        
       KNOT_REPO_SCAN_PATH=/home/git

     

       81
       81
        
       KNOT_SERVER_HOSTNAME=knot.example.com

     

       82
       82
        
       APPVIEW_ENDPOINT=https://tangled.sh

     

       83
       83
       -
       KNOT_SERVER_SECRET=secret

     

       83
       83
       +
       KNOT_SERVER_OWNER=did:plc:foobar

     

       84
       84
        
       KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444

     

       85
       85
        
       KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555

     

       86
       86
        
       ```

     
···

       128
       128
        
       Remember to use Let's Encrypt or similar to procure a certificate for your

     

       129
       129
        
       knot domain.

     

       130
       130
        
       

     

       131
       131
       -
       You should now have a running knot server! You can finalize your registration by hitting the

     

       132
       132
       -
       `initialize` button on the [/knots](https://tangled.sh/knots) page.

     

       131
       131
       +
       You should now have a running knot server! You can finalize

     

       132
       132
       +
       your registration by hitting the `verify` button on the

     

       133
       133
       +
       [/knots](https://tangled.sh/knots) page. This simply creates

     

       134
       134
       +
       a record on your PDS to announce the existence of the knot.

     

       133
       135
        
       

     

       134
       136
        
       ### custom paths

     

       135
       137

+39

docs/migrations/knot-1.7.0.md

···

       1
       1
       +
       # Upgrading from v1.7.0

     

       2
       2
       +
       

     

       3
       3
       +
       After v1.7.0, knot secrets have been deprecated. You no

     

       4
       4
       +
       longer need a secret from the appview to run a knot. All

     

       5
       5
       +
       authorized commands between services to knots are managed

     

       6
       6
       +
       via [Service

     

       7
       7
       +
       Auth](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).

     

       8
       8
       +
       Knots will be read-only until upgraded.

     

       9
       9
       +
       

     

       10
       10
       +
       Upgrading is quite easy, in essence:

     

       11
       11
       +
       

     

       12
       12
       +
       - `KNOT_SERVER_SECRET` is no more, you can remove this

     

       13
       13
       +
         environment variable entirely

     

       14
       14
       +
       - `KNOT_SERVER_OWNER` is now required on boot, set this to

     

       15
       15
       +
         your DID. You can find your DID in the

     

       16
       16
       +
         [settings](https://tangled.sh/settings) page.

     

       17
       17
       +
       - Restart your knot once you have replace the environment

     

       18
       18
       +
         variable

     

       19
       19
       +
       - Head to the [knot dashboard](https://tangled.sh/knots) and

     

       20
       20
       +
         hit the "retry" button to verify your knot. This simply

     

       21
       21
       +
         writes a `sh.tangled.knot` record to your PDS.

     

       22
       22
       +
       

     

       23
       23
       +
       ## Nix

     

       24
       24
       +
       

     

       25
       25
       +
       If you use the nix module, simply bump the flake to the

     

       26
       26
       +
       latest revision, and change your config block like so:

     

       27
       27
       +
       

     

       28
       28
       +
       ```diff

     

       29
       29
       +
        services.tangled-knot = {

     

       30
       30
       +
          enable = true;

     

       31
       31
       +
          server = {

     

       32
       32
       +
       -    secretFile = /path/to/secret;

     

       33
       33
       +
       +    owner = "did:plc:foo";

     

       34
       34
       +
            .

     

       35
       35
       +
            .

     

       36
       36
       +
            .

     

       37
       37
       +
          };

     

       38
       38
       +
        };

     

       39
       39
       +
       ```