-136

docs/contributing.md

Reviewed

··· 1 1 - # tangled contributing guide 2 2 - 3 3 - ## commit guidelines 4 4 - 5 5 - We follow a commit style similar to the Go project. Please keep commits: 6 6 - 7 7 - * **atomic**: each commit should represent one logical change 8 8 - * **descriptive**: the commit message should clearly describe what the 9 9 - change does and why it's needed 10 10 - 11 11 - ### message format 12 12 - 13 13 - ``` 14 14 - <service/top-level directory>/<affected package/directory>: <short summary of change> 15 15 - 16 16 - 17 17 - Optional longer description can go here, if necessary. Explain what the 18 18 - change does and why, especially if not obvious. Reference relevant 19 19 - issues or PRs when applicable. These can be links for now since we don't 20 20 - auto-link issues/PRs yet. 21 21 - ``` 22 22 - 23 23 - Here are some examples: 24 24 - 25 25 - ``` 26 26 - appview/state: fix token expiry check in middleware 27 27 - 28 28 - The previous check did not account for clock drift, leading to premature 29 29 - token invalidation. 30 30 - ``` 31 31 - 32 32 - ``` 33 33 - knotserver/git/service: improve error checking in upload-pack 34 34 - ``` 35 35 - 36 36 - 37 37 - ### general notes 38 38 - 39 39 - - PRs get merged "as-is" (fast-forward) -- like applying a patch-series 40 40 - using `git am`. At present, there is no squashing -- so please author 41 41 - your commits as they would appear on `master`, following the above 42 42 - guidelines. 43 43 - - If there is a lot of nesting, for example "appview: 44 44 - pages/templates/repo/fragments: ...", these can be truncated down to 45 45 - just "appview: repo/fragments: ...". If the change affects a lot of 46 46 - subdirectories, you may abbreviate to just the top-level names, e.g. 47 47 - "appview: ..." or "knotserver: ...". 48 48 - - Keep commits lowercased with no trailing period. 49 49 - - Use the imperative mood in the summary line (e.g., "fix bug" not 50 50 - "fixed bug" or "fixes bug"). 51 51 - - Try to keep the summary line under 72 characters, but we aren't too 52 52 - fussed about this. 53 53 - - Follow the same formatting for PR titles if filled manually. 54 54 - - Don't include unrelated changes in the same commit. 55 55 - - Avoid noisy commit messages like "wip" or "final fix"—rewrite history 56 56 - before submitting if necessary. 57 57 - 58 58 - ## code formatting 59 59 - 60 60 - We use a variety of tools to format our code, and multiplex them with 61 61 - [`treefmt`](https://treefmt.com): all you need to do to format your changes 62 62 - is run `nix run .#fmt` (or just `treefmt` if you're in the devshell). 63 63 - 64 64 - ## proposals for bigger changes 65 65 - 66 66 - Small fixes like typos, minor bugs, or trivial refactors can be 67 67 - submitted directly as PRs. 68 68 - 69 69 - For larger changes—especially those introducing new features, significant 70 70 - refactoring, or altering system behavior—please open a proposal first. This 71 71 - helps us evaluate the scope, design, and potential impact before implementation. 72 72 - 73 73 - ### proposal format 74 74 - 75 75 - Create a new issue titled: 76 76 - 77 77 - ``` 78 78 - proposal: <affected scope>: <summary of change> 79 79 - ``` 80 80 - 81 81 - In the description, explain: 82 82 - 83 83 - - What the change is 84 84 - - Why it's needed 85 85 - - How you plan to implement it (roughly) 86 86 - - Any open questions or tradeoffs 87 87 - 88 88 - We'll use the issue thread to discuss and refine the idea before moving 89 89 - forward. 90 90 - 91 91 - ## developer certificate of origin (DCO) 92 92 - 93 93 - We require all contributors to certify that they have the right to 94 94 - submit the code they're contributing. To do this, we follow the 95 95 - [Developer Certificate of Origin 96 96 - (DCO)](https://developercertificate.org/). 97 97 - 98 98 - By signing your commits, you're stating that the contribution is your 99 99 - own work, or that you have the right to submit it under the project's 100 100 - license. This helps us keep things clean and legally sound. 101 101 - 102 102 - To sign your commit, just add the `-s` flag when committing: 103 103 - 104 104 - ```sh 105 105 - git commit -s -m "your commit message" 106 106 - ``` 107 107 - 108 108 - This appends a line like: 109 109 - 110 110 - ``` 111 111 - Signed-off-by: Your Name <your.email@example.com> 112 112 - ``` 113 113 - 114 114 - We won't merge commits if they aren't signed off. If you forget, you can 115 115 - amend the last commit like this: 116 116 - 117 117 - ```sh 118 118 - git commit --amend -s 119 119 - ``` 120 120 - 121 121 - If you're submitting a PR with multiple commits, make sure each one is 122 122 - signed. 123 123 - 124 124 - For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command 125 125 - to make it sign off commits in the tangled repo: 126 126 - 127 127 - ```shell 128 128 - # Safety check, should say "No matching config key..." 129 129 - jj config list templates.commit_trailers 130 130 - # The command below may need to be adjusted if the command above returned something. 131 131 - jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)" 132 132 - ``` 133 133 - 134 134 - Refer to the [jj 135 135 - documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers) 136 136 - for more information.

-172

docs/hacking.md

Reviewed

··· 1 1 - # hacking on tangled 2 2 - 3 3 - We highly recommend [installing 4 4 - nix](https://nixos.org/download/) (the package manager) 5 5 - before working on the codebase. The nix flake provides a lot 6 6 - of helpers to get started and most importantly, builds and 7 7 - dev shells are entirely deterministic. 8 8 - 9 9 - To set up your dev environment: 10 10 - 11 11 - ```bash 12 12 - nix develop 13 13 - ``` 14 14 - 15 15 - Non-nix users can look at the `devShell` attribute in the 16 16 - `flake.nix` file to determine necessary dependencies. 17 17 - 18 18 - ## running the appview 19 19 - 20 20 - The nix flake also exposes a few `app` attributes (run `nix 21 21 - flake show` to see a full list of what the flake provides), 22 22 - one of the apps runs the appview with the `air` 23 23 - live-reloader: 24 24 - 25 25 - ```bash 26 26 - TANGLED_DEV=true nix run .#watch-appview 27 27 - 28 28 - # TANGLED_DB_PATH might be of interest to point to 29 29 - # different sqlite DBs 30 30 - 31 31 - # in a separate shell, you can live-reload tailwind 32 32 - nix run .#watch-tailwind 33 33 - ``` 34 34 - 35 35 - To authenticate with the appview, you will need redis and 36 36 - OAUTH JWKs to be setup: 37 37 - 38 38 - ``` 39 39 - # oauth jwks should already be setup by the nix devshell: 40 40 - echo $TANGLED_OAUTH_CLIENT_SECRET 41 41 - z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc 42 42 - 43 43 - echo $TANGLED_OAUTH_CLIENT_KID 44 44 - 1761667908 45 45 - 46 46 - # if not, you can set it up yourself: 47 47 - goat key generate -t P-256 48 48 - Key Type: P-256 / secp256r1 / ES256 private key 49 49 - Secret Key (Multibase Syntax): save this securely (eg, add to password manager) 50 50 - z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL 51 51 - Public Key (DID Key Syntax): share or publish this (eg, in DID document) 52 52 - did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR 53 53 - 54 54 - # the secret key from above 55 55 - export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..." 56 56 - 57 57 - # run redis in at a new shell to store oauth sessions 58 58 - redis-server 59 59 - ``` 60 60 - 61 61 - ## running knots and spindles 62 62 - 63 63 - An end-to-end knot setup requires setting up a machine with 64 64 - `sshd`, `AuthorizedKeysCommand`, and git user, which is 65 65 - quite cumbersome. So the nix flake provides a 66 66 - `nixosConfiguration` to do so. 67 67 - 68 68 - <details> 69 69 - <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary> 70 70 - 71 71 - In order to build Tangled's dev VM on macOS, you will 72 72 - first need to set up a Linux Nix builder. The recommended 73 73 - way to do so is to run a [`darwin.linux-builder` 74 74 - VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder) 75 75 - and to register it in `nix.conf` as a builder for Linux 76 76 - with the same architecture as your Mac (`linux-aarch64` if 77 77 - you are using Apple Silicon). 78 78 - 79 79 - > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside 80 80 - > the tangled repo so that it doesn't conflict with the other VM. For example, 81 81 - > you can do 82 82 - > 83 83 - > ```shell 84 84 - > cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder 85 85 - > ``` 86 86 - > 87 87 - > to store the builder VM in a temporary dir. 88 88 - > 89 89 - > You should read and follow [all the other intructions][darwin builder vm] to 90 90 - > avoid subtle problems. 91 91 - 92 92 - Alternatively, you can use any other method to set up a 93 93 - Linux machine with `nix` installed that you can `sudo ssh` 94 94 - into (in other words, root user on your Mac has to be able 95 95 - to ssh into the Linux machine without entering a password) 96 96 - and that has the same architecture as your Mac. See 97 97 - [remote builder 98 98 - instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements) 99 99 - for how to register such a builder in `nix.conf`. 100 100 - 101 101 - > WARNING: If you'd like to use 102 102 - > [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or 103 103 - > [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo 104 104 - > ssh` works can be tricky. It seems to be [possible with 105 105 - > Orbstack](https://github.com/orgs/orbstack/discussions/1669). 106 106 - 107 107 - </details> 108 108 - 109 109 - To begin, grab your DID from http://localhost:3000/settings. 110 110 - Then, set `TANGLED_VM_KNOT_OWNER` and 111 111 - `TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a 112 112 - lightweight NixOS VM like so: 113 113 - 114 114 - ```bash 115 115 - nix run --impure .#vm 116 116 - 117 117 - # type `poweroff` at the shell to exit the VM 118 118 - ``` 119 119 - 120 120 - This starts a knot on port 6444, a spindle on port 6555 121 121 - with `ssh` exposed on port 2222. 122 122 - 123 123 - Once the services are running, head to 124 124 - http://localhost:3000/settings/knots and hit verify. It should 125 125 - verify the ownership of the services instantly if everything 126 126 - went smoothly. 127 127 - 128 128 - You can push repositories to this VM with this ssh config 129 129 - block on your main machine: 130 130 - 131 131 - ```bash 132 132 - Host nixos-shell 133 133 - Hostname localhost 134 134 - Port 2222 135 135 - User git 136 136 - IdentityFile ~/.ssh/my_tangled_key 137 137 - ``` 138 138 - 139 139 - Set up a remote called `local-dev` on a git repo: 140 140 - 141 141 - ```bash 142 142 - git remote add local-dev git@nixos-shell:user/repo 143 143 - git push local-dev main 144 144 - ``` 145 145 - 146 146 - ### running a spindle 147 147 - 148 148 - The above VM should already be running a spindle on 149 149 - `localhost:6555`. Head to http://localhost:3000/settings/spindles and 150 150 - hit verify. You can then configure each repository to use 151 151 - this spindle and run CI jobs. 152 152 - 153 153 - Of interest when debugging spindles: 154 154 - 155 155 - ``` 156 156 - # service logs from journald: 157 157 - journalctl -xeu spindle 158 158 - 159 159 - # CI job logs from disk: 160 160 - ls /var/log/spindle 161 161 - 162 162 - # debugging spindle db: 163 163 - sqlite3 /var/lib/spindle/spindle.db 164 164 - 165 165 - # litecli has a nicer REPL interface: 166 166 - litecli /var/lib/spindle/spindle.db 167 167 - ``` 168 168 - 169 169 - If for any reason you wish to disable either one of the 170 170 - services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set 171 171 - `services.tangled.spindle.enable` (or 172 172 - `services.tangled.knot.enable`) to `false`.

-214

docs/knot-hosting.md

Reviewed

··· 1 1 - # knot self-hosting guide 2 2 - 3 3 - So you want to run your own knot server? Great! Here are a few prerequisites: 4 4 - 5 5 - 1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux distribution of some kind. 6 6 - 2. A (sub)domain name. People generally use `knot.example.com`. 7 7 - 3. A valid SSL certificate for your domain. 8 8 - 9 9 - There's a couple of ways to get started: 10 10 - * NixOS: refer to 11 11 - [flake.nix](https://tangled.sh/@tangled.sh/core/blob/master/flake.nix) 12 12 - * Docker: Documented at 13 13 - [@tangled.sh/knot-docker](https://tangled.sh/@tangled.sh/knot-docker) 14 14 - (community maintained: support is not guaranteed!) 15 15 - * Manual: Documented below. 16 16 - 17 17 - ## manual setup 18 18 - 19 19 - First, clone this repository: 20 20 - 21 21 - ``` 22 22 - git clone https://tangled.org/@tangled.org/core 23 23 - ``` 24 24 - 25 25 - Then, build the `knot` CLI. This is the knot administration and operation tool. 26 26 - For the purpose of this guide, we're only concerned with these subcommands: 27 27 - 28 28 - * `knot server`: the main knot server process, typically run as a 29 29 - supervised service 30 30 - * `knot guard`: handles role-based access control for git over SSH 31 31 - (you'll never have to run this yourself) 32 32 - * `knot keys`: fetches SSH keys associated with your knot; we'll use 33 33 - this to generate the SSH `AuthorizedKeysCommand` 34 34 - 35 35 - ``` 36 36 - cd core 37 37 - export CGO_ENABLED=1 38 38 - go build -o knot ./cmd/knot 39 39 - ``` 40 40 - 41 41 - Next, move the `knot` binary to a location owned by `root` -- 42 42 - `/usr/local/bin/` is a good choice. Make sure the binary itself is also owned by `root`: 43 43 - 44 44 - ``` 45 45 - sudo mv knot /usr/local/bin/knot 46 46 - sudo chown root:root /usr/local/bin/knot 47 47 - ``` 48 48 - 49 49 - This is necessary because SSH `AuthorizedKeysCommand` requires [really 50 50 - specific permissions](https://stackoverflow.com/a/27638306). The 51 51 - `AuthorizedKeysCommand` specifies a command that is run by `sshd` to 52 52 - retrieve a user's public SSH keys dynamically for authentication. Let's 53 53 - set that up. 54 54 - 55 55 - ``` 56 56 - sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF 57 57 - Match User git 58 58 - AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys 59 59 - AuthorizedKeysCommandUser nobody 60 60 - EOF 61 61 - ``` 62 62 - 63 63 - Then, reload `sshd`: 64 64 - 65 65 - ``` 66 66 - sudo systemctl reload ssh 67 67 - ``` 68 68 - 69 69 - Next, create the `git` user. We'll use the `git` user's home directory 70 70 - to store repositories: 71 71 - 72 72 - ``` 73 73 - sudo adduser git 74 74 - ``` 75 75 - 76 76 - Create `/home/git/.knot.env` with the following, updating the values as 77 77 - necessary. The `KNOT_SERVER_OWNER` should be set to your 78 78 - DID, you can find your DID in the [Settings](https://tangled.sh/settings) page. 79 79 - 80 80 - ``` 81 81 - KNOT_REPO_SCAN_PATH=/home/git 82 82 - KNOT_SERVER_HOSTNAME=knot.example.com 83 83 - APPVIEW_ENDPOINT=https://tangled.sh 84 84 - KNOT_SERVER_OWNER=did:plc:foobar 85 85 - KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444 86 86 - KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555 87 87 - ``` 88 88 - 89 89 - If you run a Linux distribution that uses systemd, you can use the provided 90 90 - service file to run the server. Copy 91 91 - [`knotserver.service`](/systemd/knotserver.service) 92 92 - to `/etc/systemd/system/`. Then, run: 93 93 - 94 94 - ``` 95 95 - systemctl enable knotserver 96 96 - systemctl start knotserver 97 97 - ``` 98 98 - 99 99 - The last step is to configure a reverse proxy like Nginx or Caddy to front your 100 100 - knot. Here's an example configuration for Nginx: 101 101 - 102 102 - ``` 103 103 - server { 104 104 - listen 80; 105 105 - listen [::]:80; 106 106 - server_name knot.example.com; 107 107 - 108 108 - location / { 109 109 - proxy_pass http://localhost:5555; 110 110 - proxy_set_header Host $host; 111 111 - proxy_set_header X-Real-IP $remote_addr; 112 112 - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 113 113 - proxy_set_header X-Forwarded-Proto $scheme; 114 114 - } 115 115 - 116 116 - # wss endpoint for git events 117 117 - location /events { 118 118 - proxy_set_header X-Forwarded-For $remote_addr; 119 119 - proxy_set_header Host $http_host; 120 120 - proxy_set_header Upgrade websocket; 121 121 - proxy_set_header Connection Upgrade; 122 122 - proxy_pass http://localhost:5555; 123 123 - } 124 124 - # additional config for SSL/TLS go here. 125 125 - } 126 126 - 127 127 - ``` 128 128 - 129 129 - Remember to use Let's Encrypt or similar to procure a certificate for your 130 130 - knot domain. 131 131 - 132 132 - You should now have a running knot server! You can finalize 133 133 - your registration by hitting the `verify` button on the 134 134 - [/settings/knots](https://tangled.org/settings/knots) page. This simply creates 135 135 - a record on your PDS to announce the existence of the knot. 136 136 - 137 137 - ### custom paths 138 138 - 139 139 - (This section applies to manual setup only. Docker users should edit the mounts 140 140 - in `docker-compose.yml` instead.) 141 141 - 142 142 - Right now, the database and repositories of your knot lives in `/home/git`. You 143 143 - can move these paths if you'd like to store them in another folder. Be careful 144 144 - when adjusting these paths: 145 145 - 146 146 - * Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent 147 147 - any possible side effects. Remember to restart it once you're done. 148 148 - * Make backups before moving in case something goes wrong. 149 149 - * Make sure the `git` user can read and write from the new paths. 150 150 - 151 151 - #### database 152 152 - 153 153 - As an example, let's say the current database is at `/home/git/knotserver.db`, 154 154 - and we want to move it to `/home/git/database/knotserver.db`. 155 155 - 156 156 - Copy the current database to the new location. Make sure to copy the `.db-shm` 157 157 - and `.db-wal` files if they exist. 158 158 - 159 159 - ``` 160 160 - mkdir /home/git/database 161 161 - cp /home/git/knotserver.db* /home/git/database 162 162 - ``` 163 163 - 164 164 - In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to 165 165 - the new file path (_not_ the directory): 166 166 - 167 167 - ``` 168 168 - KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db 169 169 - ``` 170 170 - 171 171 - #### repositories 172 172 - 173 173 - As an example, let's say the repositories are currently in `/home/git`, and we 174 174 - want to move them into `/home/git/repositories`. 175 175 - 176 176 - Create the new folder, then move the existing repositories (if there are any): 177 177 - 178 178 - ``` 179 179 - mkdir /home/git/repositories 180 180 - # move all DIDs into the new folder; these will vary for you! 181 181 - mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories 182 182 - ``` 183 183 - 184 184 - In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH` 185 185 - to the new directory: 186 186 - 187 187 - ``` 188 188 - KNOT_REPO_SCAN_PATH=/home/git/repositories 189 189 - ``` 190 190 - 191 191 - Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated 192 192 - repository path: 193 193 - 194 194 - ``` 195 195 - sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF 196 196 - Match User git 197 197 - AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories 198 198 - AuthorizedKeysCommandUser nobody 199 199 - EOF 200 200 - ``` 201 201 - 202 202 - Make sure to restart your SSH server! 203 203 - 204 204 - #### MOTD (message of the day) 205 205 - 206 206 - To configure the MOTD used ("Welcome to this knot!" by default), edit the 207 207 - `/home/git/motd` file: 208 208 - 209 209 - ``` 210 210 - printf "Hi from this knot!\n" > /home/git/motd 211 211 - ``` 212 212 - 213 213 - Note that you should add a newline at the end if setting a non-empty message 214 214 - since the knot won't do this for you.

-59

docs/migrations.md

Reviewed

··· 1 1 - # Migrations 2 2 - 3 3 - This document is laid out in reverse-chronological order. 4 4 - Newer migration guides are listed first, and older guides 5 5 - are further down the page. 6 6 - 7 7 - ## Upgrading from v1.8.x 8 8 - 9 9 - After v1.8.2, the HTTP API for knot and spindles have been 10 10 - deprecated and replaced with XRPC. Repositories on outdated 11 11 - knots will not be viewable from the appview. Upgrading is 12 12 - straightforward however. 13 13 - 14 14 - For knots: 15 15 - 16 16 - - Upgrade to latest tag (v1.9.0 or above) 17 17 - - Head to the [knot dashboard](https://tangled.org/settings/knots) and 18 18 - hit the "retry" button to verify your knot 19 19 - 20 20 - For spindles: 21 21 - 22 22 - - Upgrade to latest tag (v1.9.0 or above) 23 23 - - Head to the [spindle 24 24 - dashboard](https://tangled.org/settings/spindles) and hit the 25 25 - "retry" button to verify your spindle 26 26 - 27 27 - ## Upgrading from v1.7.x 28 28 - 29 29 - After v1.7.0, knot secrets have been deprecated. You no 30 30 - longer need a secret from the appview to run a knot. All 31 31 - authorized commands to knots are managed via [Inter-Service 32 32 - Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt). 33 33 - Knots will be read-only until upgraded. 34 34 - 35 35 - Upgrading is quite easy, in essence: 36 36 - 37 37 - - `KNOT_SERVER_SECRET` is no more, you can remove this 38 38 - environment variable entirely 39 39 - - `KNOT_SERVER_OWNER` is now required on boot, set this to 40 40 - your DID. You can find your DID in the 41 41 - [settings](https://tangled.org/settings) page. 42 42 - - Restart your knot once you have replaced the environment 43 43 - variable 44 44 - - Head to the [knot dashboard](https://tangled.org/settings/knots) and 45 45 - hit the "retry" button to verify your knot. This simply 46 46 - writes a `sh.tangled.knot` record to your PDS. 47 47 - 48 48 - If you use the nix module, simply bump the flake to the 49 49 - latest revision, and change your config block like so: 50 50 - 51 51 - ```diff 52 52 - services.tangled.knot = { 53 53 - enable = true; 54 54 - server = { 55 55 - - secretFile = /path/to/secret; 56 56 - + owner = "did:plc:foo"; 57 57 - }; 58 58 - }; 59 59 - ```

-25

docs/spindle/architecture.md

Reviewed

··· 1 1 - # spindle architecture 2 2 - 3 3 - Spindle is a small CI runner service. Here's a high level overview of how it operates: 4 4 - 5 5 - * listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and 6 6 - [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream. 7 7 - * when a new repo record comes through (typically when you add a spindle to a 8 8 - repo from the settings), spindle then resolves the underlying knot and 9 9 - subscribes to repo events (see: 10 10 - [`sh.tangled.pipeline`](/lexicons/pipeline.json)). 11 11 - * the spindle engine then handles execution of the pipeline, with results and 12 12 - logs beamed on the spindle event stream over wss 13 13 - 14 14 - ### the engine 15 15 - 16 16 - At present, the only supported backend is Docker (and Podman, if Docker 17 17 - compatibility is enabled, so that `/run/docker.sock` is created). Spindle 18 18 - executes each step in the pipeline in a fresh container, with state persisted 19 19 - across steps within the `/tangled/workspace` directory. 20 20 - 21 21 - The base image for the container is constructed on the fly using 22 22 - [Nixery](https://nixery.dev), which is handy for caching layers for frequently 23 23 - used packages. 24 24 - 25 25 - The pipeline manifest is [specified here](/docs/spindle/pipeline.md).

-52

docs/spindle/hosting.md

Reviewed

··· 1 1 - # spindle self-hosting guide 2 2 - 3 3 - ## prerequisites 4 4 - 5 5 - * Go 6 6 - * Docker (the only supported backend currently) 7 7 - 8 8 - ## configuration 9 9 - 10 10 - Spindle is configured using environment variables. The following environment variables are available: 11 11 - 12 12 - * `SPINDLE_SERVER_LISTEN_ADDR`: The address the server listens on (default: `"0.0.0.0:6555"`). 13 13 - * `SPINDLE_SERVER_DB_PATH`: The path to the SQLite database file (default: `"spindle.db"`). 14 14 - * `SPINDLE_SERVER_HOSTNAME`: The hostname of the server (required). 15 15 - * `SPINDLE_SERVER_JETSTREAM_ENDPOINT`: The endpoint of the Jetstream server (default: `"wss://jetstream1.us-west.bsky.network/subscribe"`). 16 16 - * `SPINDLE_SERVER_DEV`: A boolean indicating whether the server is running in development mode (default: `false`). 17 17 - * `SPINDLE_SERVER_OWNER`: The DID of the owner (required). 18 18 - * `SPINDLE_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`). 19 19 - * `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`). 20 20 - * `SPINDLE_PIPELINES_LOG_DIR`: The directory to store workflow logs (default: `"/var/log/spindle"`). 21 21 - 22 22 - ## running spindle 23 23 - 24 24 - 1. **Set the environment variables.** For example: 25 25 - 26 26 - ```shell 27 27 - export SPINDLE_SERVER_HOSTNAME="your-hostname" 28 28 - export SPINDLE_SERVER_OWNER="your-did" 29 29 - ``` 30 30 - 31 31 - 2. **Build the Spindle binary.** 32 32 - 33 33 - ```shell 34 34 - cd core 35 35 - go mod download 36 36 - go build -o cmd/spindle/spindle cmd/spindle/main.go 37 37 - ``` 38 38 - 39 39 - 3. **Create the log directory.** 40 40 - 41 41 - ```shell 42 42 - sudo mkdir -p /var/log/spindle 43 43 - sudo chown $USER:$USER -R /var/log/spindle 44 44 - ``` 45 45 - 46 46 - 4. **Run the Spindle binary.** 47 47 - 48 48 - ```shell 49 49 - ./cmd/spindle/spindle 50 50 - ``` 51 51 - 52 52 - Spindle will now start, connect to the Jetstream server, and begin processing pipelines.

-285

docs/spindle/openbao.md

Reviewed

··· 1 1 - # spindle secrets with openbao 2 2 - 3 3 - This document covers setting up Spindle to use OpenBao for secrets 4 4 - management via OpenBao Proxy instead of the default SQLite backend. 5 5 - 6 6 - ## overview 7 7 - 8 8 - Spindle now uses OpenBao Proxy for secrets management. The proxy handles 9 9 - authentication automatically using AppRole credentials, while Spindle 10 10 - connects to the local proxy instead of directly to the OpenBao server. 11 11 - 12 12 - This approach provides better security, automatic token renewal, and 13 13 - simplified application code. 14 14 - 15 15 - ## installation 16 16 - 17 17 - Install OpenBao from nixpkgs: 18 18 - 19 19 - ```bash 20 20 - nix shell nixpkgs#openbao # for a local server 21 21 - ``` 22 22 - 23 23 - ## setup 24 24 - 25 25 - The setup process can is documented for both local development and production. 26 26 - 27 27 - ### local development 28 28 - 29 29 - Start OpenBao in dev mode: 30 30 - 31 31 - ```bash 32 32 - bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201 33 33 - ``` 34 34 - 35 35 - This starts OpenBao on `http://localhost:8201` with a root token. 36 36 - 37 37 - Set up environment for bao CLI: 38 38 - 39 39 - ```bash 40 40 - export BAO_ADDR=http://localhost:8200 41 41 - export BAO_TOKEN=root 42 42 - ``` 43 43 - 44 44 - ### production 45 45 - 46 46 - You would typically use a systemd service with a configuration file. Refer to 47 47 - [@tangled.org/infra](https://tangled.org/@tangled.org/infra) for how this can be 48 48 - achieved using Nix. 49 49 - 50 50 - Then, initialize the bao server: 51 51 - ```bash 52 52 - bao operator init -key-shares=1 -key-threshold=1 53 53 - ``` 54 54 - 55 55 - This will print out an unseal key and a root key. Save them somewhere (like a password manager). Then unseal the vault to begin setting it up: 56 56 - ```bash 57 57 - bao operator unseal <unseal_key> 58 58 - ``` 59 59 - 60 60 - All steps below remain the same across both dev and production setups. 61 61 - 62 62 - ### configure openbao server 63 63 - 64 64 - Create the spindle KV mount: 65 65 - 66 66 - ```bash 67 67 - bao secrets enable -path=spindle -version=2 kv 68 68 - ``` 69 69 - 70 70 - Set up AppRole authentication and policy: 71 71 - 72 72 - Create a policy file `spindle-policy.hcl`: 73 73 - 74 74 - ```hcl 75 75 - # Full access to spindle KV v2 data 76 76 - path "spindle/data/*" { 77 77 - capabilities = ["create", "read", "update", "delete"] 78 78 - } 79 79 - 80 80 - # Access to metadata for listing and management 81 81 - path "spindle/metadata/*" { 82 82 - capabilities = ["list", "read", "delete", "update"] 83 83 - } 84 84 - 85 85 - # Allow listing at root level 86 86 - path "spindle/" { 87 87 - capabilities = ["list"] 88 88 - } 89 89 - 90 90 - # Required for connection testing and health checks 91 91 - path "auth/token/lookup-self" { 92 92 - capabilities = ["read"] 93 93 - } 94 94 - ``` 95 95 - 96 96 - Apply the policy and create an AppRole: 97 97 - 98 98 - ```bash 99 99 - bao policy write spindle-policy spindle-policy.hcl 100 100 - bao auth enable approle 101 101 - bao write auth/approle/role/spindle \ 102 102 - token_policies="spindle-policy" \ 103 103 - token_ttl=1h \ 104 104 - token_max_ttl=4h \ 105 105 - bind_secret_id=true \ 106 106 - secret_id_ttl=0 \ 107 107 - secret_id_num_uses=0 108 108 - ``` 109 109 - 110 110 - Get the credentials: 111 111 - 112 112 - ```bash 113 113 - # Get role ID (static) 114 114 - ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id) 115 115 - 116 116 - # Generate secret ID 117 117 - SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id) 118 118 - 119 119 - echo "Role ID: $ROLE_ID" 120 120 - echo "Secret ID: $SECRET_ID" 121 121 - ``` 122 122 - 123 123 - ### create proxy configuration 124 124 - 125 125 - Create the credential files: 126 126 - 127 127 - ```bash 128 128 - # Create directory for OpenBao files 129 129 - mkdir -p /tmp/openbao 130 130 - 131 131 - # Save credentials 132 132 - echo "$ROLE_ID" > /tmp/openbao/role-id 133 133 - echo "$SECRET_ID" > /tmp/openbao/secret-id 134 134 - chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id 135 135 - ``` 136 136 - 137 137 - Create a proxy configuration file `/tmp/openbao/proxy.hcl`: 138 138 - 139 139 - ```hcl 140 140 - # OpenBao server connection 141 141 - vault { 142 142 - address = "http://localhost:8200" 143 143 - } 144 144 - 145 145 - # Auto-Auth using AppRole 146 146 - auto_auth { 147 147 - method "approle" { 148 148 - mount_path = "auth/approle" 149 149 - config = { 150 150 - role_id_file_path = "/tmp/openbao/role-id" 151 151 - secret_id_file_path = "/tmp/openbao/secret-id" 152 152 - } 153 153 - } 154 154 - 155 155 - # Optional: write token to file for debugging 156 156 - sink "file" { 157 157 - config = { 158 158 - path = "/tmp/openbao/token" 159 159 - mode = 0640 160 160 - } 161 161 - } 162 162 - } 163 163 - 164 164 - # Proxy listener for Spindle 165 165 - listener "tcp" { 166 166 - address = "127.0.0.1:8201" 167 167 - tls_disable = true 168 168 - } 169 169 - 170 170 - # Enable API proxy with auto-auth token 171 171 - api_proxy { 172 172 - use_auto_auth_token = true 173 173 - } 174 174 - 175 175 - # Enable response caching 176 176 - cache { 177 177 - use_auto_auth_token = true 178 178 - } 179 179 - 180 180 - # Logging 181 181 - log_level = "info" 182 182 - ``` 183 183 - 184 184 - ### start the proxy 185 185 - 186 186 - Start OpenBao Proxy: 187 187 - 188 188 - ```bash 189 189 - bao proxy -config=/tmp/openbao/proxy.hcl 190 190 - ``` 191 191 - 192 192 - The proxy will authenticate with OpenBao and start listening on 193 193 - `127.0.0.1:8201`. 194 194 - 195 195 - ### configure spindle 196 196 - 197 197 - Set these environment variables for Spindle: 198 198 - 199 199 - ```bash 200 200 - export SPINDLE_SERVER_SECRETS_PROVIDER=openbao 201 201 - export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201 202 202 - export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle 203 203 - ``` 204 204 - 205 205 - Start Spindle: 206 206 - 207 207 - Spindle will now connect to the local proxy, which handles all 208 208 - authentication automatically. 209 209 - 210 210 - ## production setup for proxy 211 211 - 212 212 - For production, you'll want to run the proxy as a service: 213 213 - 214 214 - Place your production configuration in `/etc/openbao/proxy.hcl` with 215 215 - proper TLS settings for the vault connection. 216 216 - 217 217 - ## verifying setup 218 218 - 219 219 - Test the proxy directly: 220 220 - 221 221 - ```bash 222 222 - # Check proxy health 223 223 - curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health 224 224 - 225 225 - # Test token lookup through proxy 226 226 - curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self 227 227 - ``` 228 228 - 229 229 - Test OpenBao operations through the server: 230 230 - 231 231 - ```bash 232 232 - # List all secrets 233 233 - bao kv list spindle/ 234 234 - 235 235 - # Add a test secret via Spindle API, then check it exists 236 236 - bao kv list spindle/repos/ 237 237 - 238 238 - # Get a specific secret 239 239 - bao kv get spindle/repos/your_repo_path/SECRET_NAME 240 240 - ``` 241 241 - 242 242 - ## how it works 243 243 - 244 244 - - Spindle connects to OpenBao Proxy on localhost (typically port 8200 or 8201) 245 245 - - The proxy authenticates with OpenBao using AppRole credentials 246 246 - - All Spindle requests go through the proxy, which injects authentication tokens 247 247 - - Secrets are stored at `spindle/repos/{sanitized_repo_path}/{secret_key}` 248 248 - - Repository paths like `did:plc:alice/myrepo` become `did_plc_alice_myrepo` 249 249 - - The proxy handles all token renewal automatically 250 250 - - Spindle no longer manages tokens or authentication directly 251 251 - 252 252 - ## troubleshooting 253 253 - 254 254 - **Connection refused**: Check that the OpenBao Proxy is running and 255 255 - listening on the configured address. 256 256 - 257 257 - **403 errors**: Verify the AppRole credentials are correct and the policy 258 258 - has the necessary permissions. 259 259 - 260 260 - **404 route errors**: The spindle KV mount probably doesn't exist - run 261 261 - the mount creation step again. 262 262 - 263 263 - **Proxy authentication failures**: Check the proxy logs and verify the 264 264 - role-id and secret-id files are readable and contain valid credentials. 265 265 - 266 266 - **Secret not found after writing**: This can indicate policy permission 267 267 - issues. Verify the policy includes both `spindle/data/*` and 268 268 - `spindle/metadata/*` paths with appropriate capabilities. 269 269 - 270 270 - Check proxy logs: 271 271 - 272 272 - ```bash 273 273 - # If running as systemd service 274 274 - journalctl -u openbao-proxy -f 275 275 - 276 276 - # If running directly, check the console output 277 277 - ``` 278 278 - 279 279 - Test AppRole authentication manually: 280 280 - 281 281 - ```bash 282 282 - bao write auth/approle/login \ 283 283 - role_id="$(cat /tmp/openbao/role-id)" \ 284 284 - secret_id="$(cat /tmp/openbao/secret-id)" 285 285 - ```

-183

docs/spindle/pipeline.md

Reviewed

··· 1 1 - # spindle pipelines 2 2 - 3 3 - Spindle workflows allow you to write CI/CD pipelines in a simple format. They're located in the `.tangled/workflows` directory at the root of your repository, and are defined using YAML. 4 4 - 5 5 - The fields are: 6 6 - 7 7 - - [Trigger](#trigger): A **required** field that defines when a workflow should be triggered. 8 8 - - [Engine](#engine): A **required** field that defines which engine a workflow should run on. 9 9 - - [Clone options](#clone-options): An **optional** field that defines how the repository should be cloned. 10 10 - - [Dependencies](#dependencies): An **optional** field that allows you to list dependencies you may need. 11 11 - - [Environment](#environment): An **optional** field that allows you to define environment variables. 12 12 - - [Steps](#steps): An **optional** field that allows you to define what steps should run in the workflow. 13 13 - 14 14 - ## Trigger 15 15 - 16 16 - The first thing to add to a workflow is the trigger, which defines when a workflow runs. This is defined using a `when` field, which takes in a list of conditions. Each condition has the following fields: 17 17 - 18 18 - - `event`: This is a **required** field that defines when your workflow should run. It's a list that can take one or more of the following values: 19 19 - - `push`: The workflow should run every time a commit is pushed to the repository. 20 20 - - `pull_request`: The workflow should run every time a pull request is made or updated. 21 21 - - `manual`: The workflow can be triggered manually. 22 22 - - `branch`: Defines which branches the workflow should run for. If used with the `push` event, commits to the branch(es) listed here will trigger the workflow. If used with the `pull_request` event, updates to pull requests targeting the branch(es) listed here will trigger the workflow. This field has no effect with the `manual` event. Supports glob patterns using `*` and `**` (e.g., `main`, `develop`, `release-*`). Either `branch` or `tag` (or both) must be specified for `push` events. 23 23 - - `tag`: Defines which tags the workflow should run for. Only used with the `push` event - when tags matching the pattern(s) listed here are pushed, the workflow will trigger. This field has no effect with `pull_request` or `manual` events. Supports glob patterns using `*` and `**` (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or `tag` (or both) must be specified for `push` events. 24 24 - 25 25 - For example, if you'd like to define a workflow that runs when commits are pushed to the `main` and `develop` branches, or when pull requests that target the `main` branch are updated, or manually, you can do so with: 26 26 - 27 27 - ```yaml 28 28 - when: 29 29 - - event: ["push", "manual"] 30 30 - branch: ["main", "develop"] 31 31 - - event: ["pull_request"] 32 32 - branch: ["main"] 33 33 - ``` 34 34 - 35 35 - You can also trigger workflows on tag pushes. For instance, to run a deployment workflow when tags matching `v*` are pushed: 36 36 - 37 37 - ```yaml 38 38 - when: 39 39 - - event: ["push"] 40 40 - tag: ["v*"] 41 41 - ``` 42 42 - 43 43 - You can even combine branch and tag patterns in a single constraint (the workflow triggers if either matches): 44 44 - 45 45 - ```yaml 46 46 - when: 47 47 - - event: ["push"] 48 48 - branch: ["main", "release-*"] 49 49 - tag: ["v*", "stable"] 50 50 - ``` 51 51 - 52 52 - ## Engine 53 53 - 54 54 - Next is the engine on which the workflow should run, defined using the **required** `engine` field. The currently supported engines are: 55 55 - 56 56 - - `nixery`: This uses an instance of [Nixery](https://nixery.dev) to run steps, which allows you to add [dependencies](#dependencies) from [Nixpkgs](https://github.com/NixOS/nixpkgs). You can search for packages on https://search.nixos.org, and there's a pretty good chance the package(s) you're looking for will be there. 57 57 - 58 58 - Example: 59 59 - 60 60 - ```yaml 61 61 - engine: "nixery" 62 62 - ``` 63 63 - 64 64 - ## Clone options 65 65 - 66 66 - When a workflow starts, the first step is to clone the repository. You can customize this behavior using the **optional** `clone` field. It has the following fields: 67 67 - 68 68 - - `skip`: Setting this to `true` will skip cloning the repository. This can be useful if your workflow is doing something that doesn't require anything from the repository itself. This is `false` by default. 69 69 - - `depth`: This sets the number of commits, or the "clone depth", to fetch from the repository. For example, if you set this to 2, the last 2 commits will be fetched. By default, the depth is set to 1, meaning only the most recent commit will be fetched, which is the commit that triggered the workflow. 70 70 - - `submodules`: If you use [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in your repository, setting this field to `true` will recursively fetch all submodules. This is `false` by default. 71 71 - 72 72 - The default settings are: 73 73 - 74 74 - ```yaml 75 75 - clone: 76 76 - skip: false 77 77 - depth: 1 78 78 - submodules: false 79 79 - ``` 80 80 - 81 81 - ## Dependencies 82 82 - 83 83 - Usually when you're running a workflow, you'll need additional dependencies. The `dependencies` field lets you define which dependencies to get, and from where. It's a key-value map, with the key being the registry to fetch dependencies from, and the value being the list of dependencies to fetch. 84 84 - 85 85 - Say you want to fetch Node.js and Go from `nixpkgs`, and a package called `my_pkg` you've made from your own registry at your repository at `https://tangled.sh/@example.com/my_pkg`. You can define those dependencies like so: 86 86 - 87 87 - ```yaml 88 88 - dependencies: 89 89 - # nixpkgs 90 90 - nixpkgs: 91 91 - - nodejs 92 92 - - go 93 93 - # custom registry 94 94 - git+https://tangled.org/@example.com/my_pkg: 95 95 - - my_pkg 96 96 - ``` 97 97 - 98 98 - Now these dependencies are available to use in your workflow! 99 99 - 100 100 - ## Environment 101 101 - 102 102 - The `environment` field allows you define environment variables that will be available throughout the entire workflow. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.** 103 103 - 104 104 - Example: 105 105 - 106 106 - ```yaml 107 107 - environment: 108 108 - GOOS: "linux" 109 109 - GOARCH: "arm64" 110 110 - NODE_ENV: "production" 111 111 - MY_ENV_VAR: "MY_ENV_VALUE" 112 112 - ``` 113 113 - 114 114 - ## Steps 115 115 - 116 116 - The `steps` field allows you to define what steps should run in the workflow. It's a list of step objects, each with the following fields: 117 117 - 118 118 - - `name`: This field allows you to give your step a name. This name is visible in your workflow runs, and is used to describe what the step is doing. 119 119 - - `command`: This field allows you to define a command to run in that step. The step is run in a Bash shell, and the logs from the command will be visible in the pipelines page on the Tangled website. The [dependencies](#dependencies) you added will be available to use here. 120 120 - - `environment`: Similar to the global [environment](#environment) config, this **optional** field is a key-value map that allows you to set environment variables for the step. **Do not put secrets here, these environment variables are visible to anyone viewing the repository. You can add secrets for pipelines in your repository's settings.** 121 121 - 122 122 - Example: 123 123 - 124 124 - ```yaml 125 125 - steps: 126 126 - - name: "Build backend" 127 127 - command: "go build" 128 128 - environment: 129 129 - GOOS: "darwin" 130 130 - GOARCH: "arm64" 131 131 - - name: "Build frontend" 132 132 - command: "npm run build" 133 133 - environment: 134 134 - NODE_ENV: "production" 135 135 - ``` 136 136 - 137 137 - ## Complete workflow 138 138 - 139 139 - ```yaml 140 140 - # .tangled/workflows/build.yml 141 141 - 142 142 - when: 143 143 - - event: ["push", "manual"] 144 144 - branch: ["main", "develop"] 145 145 - - event: ["pull_request"] 146 146 - branch: ["main"] 147 147 - 148 148 - engine: "nixery" 149 149 - 150 150 - # using the default values 151 151 - clone: 152 152 - skip: false 153 153 - depth: 1 154 154 - submodules: false 155 155 - 156 156 - dependencies: 157 157 - # nixpkgs 158 158 - nixpkgs: 159 159 - - nodejs 160 160 - - go 161 161 - # custom registry 162 162 - git+https://tangled.org/@example.com/my_pkg: 163 163 - - my_pkg 164 164 - 165 165 - environment: 166 166 - GOOS: "linux" 167 167 - GOARCH: "arm64" 168 168 - NODE_ENV: "production" 169 169 - MY_ENV_VAR: "MY_ENV_VALUE" 170 170 - 171 171 - steps: 172 172 - - name: "Build backend" 173 173 - command: "go build" 174 174 - environment: 175 175 - GOOS: "darwin" 176 176 - GOARCH: "arm64" 177 177 - - name: "Build frontend" 178 178 - command: "npm run build" 179 179 - environment: 180 180 - NODE_ENV: "production" 181 181 - ``` 182 182 - 183 183 - If you want another example of a workflow, you can look at the one [Tangled uses to build the project](https://tangled.sh/@tangled.sh/core/blob/master/.tangled/workflows/build.yml).