+65 -66

docs/DOCS.md

Reviewed

··· 1 1 --- 2 2 - title: Tangled Documentation 2 2 + title: Tangled docs 3 3 author: The Tangled Contributors 4 4 date: 21 Sun, Dec 2025 5 5 --- ··· 8 8 9 9 Tangled is a decentralized code hosting and collaboration 10 10 platform. Every component of Tangled is open-source and 11 11 - selfhostable. [tangled.org](https://tangled.org) also 11 11 + self-hostable. [tangled.org](https://tangled.org) also 12 12 provides hosting and CI services that are free to use. 13 13 14 14 There are several models for decentralized code 15 15 collaboration platforms, ranging from ActivityPub’s 16 16 (Forgejo) federated model, to Radicle’s entirely P2P model. 17 17 Our approach attempts to be the best of both worlds by 18 18 - adopting atproto—a protocol for building decentralized 18 18 + adopting the AT Protocol—a protocol for building decentralized 19 19 social applications with a central identity 20 20 21 21 Our approach to this is the idea of “knots”. Knots are ··· 26 26 default, Tangled provides managed knots where you can host 27 27 your repositories for free. 28 28 29 29 - The "appview" at tangled.org acts as a consolidated “view” 29 29 + The appview at tangled.org acts as a consolidated "view" 30 30 into the whole network, allowing users to access, clone and 31 31 contribute to repositories hosted across different knots 32 32 seamlessly. 33 33 34 34 - # Quick Start Guide 34 34 + # Quick start guide 35 35 36 36 - ## Login or Sign up 36 36 + ## Login or sign up 37 37 38 38 - You can [login](https://tangled.org) by using your AT 38 38 + You can [login](https://tangled.org) by using your AT Protocol 39 39 account. If you are unclear on what that means, simply head 40 40 to the [signup](https://tangled.org/signup) page and create 41 41 an account. By doing so, you will be choosing Tangled as 42 42 your account provider (you will be granted a handle of the 43 43 form `user.tngl.sh`). 44 44 45 45 - In the AT network, users are free to choose their account 45 45 + In the AT Protocol network, users are free to choose their account 46 46 provider (known as a "Personal Data Service", or PDS), and 47 47 login to applications that support AT accounts. 48 48 49 49 - You can think of it as "one account for all of the 50 50 - atmosphere"! 49 49 + You can think of it as "one account for all of the atmosphere"! 51 50 52 51 If you already have an AT account (you may have one if you 53 52 signed up to Bluesky, for example), you can login with the 54 53 same handle on Tangled (so just use `user.bsky.social` on 55 54 the login page). 56 55 57 57 - ## Add an SSH Key 56 56 + ## Add an SSH key 58 57 59 58 Once you are logged in, you can start creating repositories 60 59 and pushing code. Tangled supports pushing git repositories ··· 87 86 paste your public key, give it a descriptive name, and hit 88 87 save. 89 88 90 90 - ## Create a Repository 89 89 + ## Create a repository 91 90 92 91 Once your SSH key is added, create your first repository: 93 92 ··· 98 97 4. Choose a knotserver to host this repository on 99 98 5. Hit create 100 99 101 101 - "Knots" are selfhostable, lightweight git servers that can 100 100 + Knots are self-hostable, lightweight Git servers that can 102 101 host your repository. Unlike traditional code forges, your 103 102 code can live on any server. Read the [Knots](TODO) section 104 103 for more. ··· 125 124 are hosted by tangled.org. If you use a custom knot, refer 126 125 to the [Knots](TODO) section. 127 126 128 128 - ## Push Your First Repository 127 127 + ## Push your first repository 129 128 130 130 - Initialize a new git repository: 129 129 + Initialize a new Git repository: 131 130 132 131 ```bash 133 132 mkdir my-project ··· 165 164 cd /path/to/your/existing/repo 166 165 ``` 167 166 168 168 - You can inspect your existing git remote like so: 167 167 + You can inspect your existing Git remote like so: 169 168 170 169 ```bash 171 170 git remote -v ··· 197 196 origin git@tangled.org:user.tngl.sh/my-project (push) 198 197 ``` 199 198 200 200 - Push all your branches and tags to tangled: 199 199 + Push all your branches and tags to Tangled: 201 200 202 201 ```bash 203 202 git push -u origin --all ··· 232 231 ``` 233 232 234 233 You also need to re-add the original URL as a push 235 235 - destination (git replaces the push URL when you use `--add` 234 234 + destination (Git replaces the push URL when you use `--add` 236 235 the first time): 237 236 238 237 ```bash ··· 249 248 ``` 250 249 251 250 Notice that there's one fetch URL (the primary remote) and 252 252 - two push URLs. Now, whenever you push, git will 251 251 + two push URLs. Now, whenever you push, Git will 253 252 automatically push to both remotes: 254 253 255 254 ```bash ··· 301 300 ## Docker 302 301 303 302 Refer to 304 304 - [@tangled.org/knot-docker](https://tangled.sh/@tangled.sh/knot-docker). 303 303 + [@tangled.org/knot-docker](https://tangled.org/@tangled.org/knot-docker). 305 304 Note that this is community maintained. 306 305 307 306 ## Manual setup ··· 372 371 ``` 373 372 KNOT_REPO_SCAN_PATH=/home/git 374 373 KNOT_SERVER_HOSTNAME=knot.example.com 375 375 - APPVIEW_ENDPOINT=https://tangled.sh 374 374 + APPVIEW_ENDPOINT=https://tangled.org 376 375 KNOT_SERVER_OWNER=did:plc:foobar 377 376 KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444 378 377 KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555 ··· 603 602 - `nixery`: This uses an instance of 604 603 [Nixery](https://nixery.dev) to run steps, which allows 605 604 you to add [dependencies](#dependencies) from 606 606 - [Nixpkgs](https://github.com/NixOS/nixpkgs). You can 605 605 + Nixpkgs (https://github.com/NixOS/nixpkgs). You can 607 606 search for packages on https://search.nixos.org, and 608 607 there's a pretty good chance the package(s) you're looking 609 608 for will be there. ··· 630 629 default, the depth is set to 1, meaning only the most 631 630 recent commit will be fetched, which is the commit that 632 631 triggered the workflow. 633 633 - - `submodules`: If you use [git 634 634 - submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) 632 632 + - `submodules`: If you use Git submodules 633 633 + (https://git-scm.com/book/en/v2/Git-Tools-Submodules) 635 634 in your repository, setting this field to `true` will 636 635 recursively fetch all submodules. This is `false` by 637 636 default. ··· 657 656 Say you want to fetch Node.js and Go from `nixpkgs`, and a 658 657 package called `my_pkg` you've made from your own registry 659 658 at your repository at 660 660 - `https://tangled.sh/@example.com/my_pkg`. You can define 659 659 + `https://tangled.org/@example.com/my_pkg`. You can define 661 660 those dependencies like so: 662 661 663 662 ```yaml ··· 779 778 780 779 If you want another example of a workflow, you can look at 781 780 the one [Tangled uses to build the 782 782 - project](https://tangled.sh/@tangled.sh/core/blob/master/.tangled/workflows/build.yml). 781 781 + project](https://tangled.org/@tangled.org/core/blob/master/.tangled/workflows/build.yml). 783 782 784 783 ## Self-hosting guide 785 784 ··· 836 835 837 836 ## Architecture 838 837 839 839 - Spindle is a small CI runner service. Here's a high level overview of how it operates: 838 838 + Spindle is a small CI runner service. Here's a high-level overview of how it operates: 840 839 841 841 - * listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and 840 840 + * Listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and 842 841 [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream. 843 843 - * when a new repo record comes through (typically when you add a spindle to a 842 842 + * When a new repo record comes through (typically when you add a spindle to a 844 843 repo from the settings), spindle then resolves the underlying knot and 845 844 subscribes to repo events (see: 846 845 [`sh.tangled.pipeline`](/lexicons/pipeline.json)). 847 847 - * the spindle engine then handles execution of the pipeline, with results and 848 848 - logs beamed on the spindle event stream over wss 846 846 + * The spindle engine then handles execution of the pipeline, with results and 847 847 + logs beamed on the spindle event stream over WebSocket 849 848 850 849 ### The engine 851 850 852 851 At present, the only supported backend is Docker (and Podman, if Docker 853 853 - compatibility is enabled, so that `/run/docker.sock` is created). Spindle 852 852 + compatibility is enabled, so that `/run/docker.sock` is created). spindle 854 853 executes each step in the pipeline in a fresh container, with state persisted 855 854 across steps within the `/tangled/workspace` directory. 856 855 ··· 862 861 863 862 ## Secrets with openbao 864 863 865 865 - This document covers setting up Spindle to use OpenBao for secrets 864 864 + This document covers setting up spindle to use OpenBao for secrets 866 865 management via OpenBao Proxy instead of the default SQLite backend. 867 866 868 867 ### Overview 869 868 870 869 Spindle now uses OpenBao Proxy for secrets management. The proxy handles 871 871 - authentication automatically using AppRole credentials, while Spindle 870 870 + authentication automatically using AppRole credentials, while spindle 872 871 connects to the local proxy instead of directly to the OpenBao server. 873 872 874 873 This approach provides better security, automatic token renewal, and ··· 876 875 877 876 ### Installation 878 877 879 879 - Install OpenBao from nixpkgs: 878 878 + Install OpenBao from Nixpkgs: 880 879 881 880 ```bash 882 881 nix shell nixpkgs#openbao # for a local server ··· 1029 1028 } 1030 1029 } 1031 1030 1032 1032 - # Proxy listener for Spindle 1031 1031 + # Proxy listener for spindle 1033 1032 listener "tcp" { 1034 1033 address = "127.0.0.1:8201" 1035 1034 tls_disable = true ··· 1062 1061 1063 1062 #### Configure spindle 1064 1063 1065 1065 - Set these environment variables for Spindle: 1064 1064 + Set these environment variables for spindle: 1066 1065 1067 1066 ```bash 1068 1067 export SPINDLE_SERVER_SECRETS_PROVIDER=openbao ··· 1070 1069 export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle 1071 1070 ``` 1072 1071 1073 1073 - On startup, the spindle will now connect to the local proxy, 1072 1072 + On startup, spindle will now connect to the local proxy, 1074 1073 which handles all authentication automatically. 1075 1074 1076 1075 ### Production setup for proxy ··· 1099 1098 # List all secrets 1100 1099 bao kv list spindle/ 1101 1100 1102 1102 - # Add a test secret via Spindle API, then check it exists 1101 1101 + # Add a test secret via the spindle API, then check it exists 1103 1102 bao kv list spindle/repos/ 1104 1103 1105 1104 # Get a specific secret ··· 1112 1111 port 8200 or 8201) 1113 1112 - The proxy authenticates with OpenBao using AppRole 1114 1113 credentials 1115 1115 - - All Spindle requests go through the proxy, which injects 1114 1114 + - All spindle requests go through the proxy, which injects 1116 1115 authentication tokens 1117 1116 - Secrets are stored at 1118 1117 `spindle/repos/{sanitized_repo_path}/{secret_key}` ··· 1131 1130 and the policy has the necessary permissions. 1132 1131 1133 1132 **404 route errors**: The spindle KV mount probably doesn't 1134 1134 - exist - run the mount creation step again. 1133 1133 + exist—run the mount creation step again. 1135 1134 1136 1135 **Proxy authentication failures**: Check the proxy logs and 1137 1136 verify the role-id and secret-id files are readable and ··· 1159 1158 secret_id="$(cat /tmp/openbao/secret-id)" 1160 1159 ``` 1161 1160 1162 1162 - # Migrating knots & spindles 1161 1161 + # Migrating knots and spindles 1163 1162 1164 1163 Sometimes, non-backwards compatible changes are made to the 1165 1164 knot/spindle XRPC APIs. If you host a knot or a spindle, you ··· 1172 1171 1173 1172 ## Upgrading from v1.8.x 1174 1173 1175 1175 - After v1.8.2, the HTTP API for knot and spindles have been 1174 1174 + After v1.8.2, the HTTP API for knots and spindles has been 1176 1175 deprecated and replaced with XRPC. Repositories on outdated 1177 1176 knots will not be viewable from the appview. Upgrading is 1178 1177 straightforward however. 1179 1178 1180 1179 For knots: 1181 1180 1182 1182 - - Upgrade to latest tag (v1.9.0 or above) 1181 1181 + - Upgrade to the latest tag (v1.9.0 or above) 1183 1182 - Head to the [knot dashboard](https://tangled.org/settings/knots) and 1184 1183 hit the "retry" button to verify your knot 1185 1184 1186 1185 For spindles: 1187 1186 1188 1188 - - Upgrade to latest tag (v1.9.0 or above) 1187 1187 + - Upgrade to the latest tag (v1.9.0 or above) 1189 1188 - Head to the [spindle 1190 1189 dashboard](https://tangled.org/settings/spindles) and hit the 1191 1190 "retry" button to verify your spindle ··· 1227 1226 # Hacking on Tangled 1228 1227 1229 1228 We highly recommend [installing 1230 1230 - nix](https://nixos.org/download/) (the package manager) 1231 1231 - before working on the codebase. The nix flake provides a lot 1229 1229 + Nix](https://nixos.org/download/) (the package manager) 1230 1230 + before working on the codebase. The Nix flake provides a lot 1232 1231 of helpers to get started and most importantly, builds and 1233 1232 dev shells are entirely deterministic. 1234 1233 ··· 1238 1237 nix develop 1239 1238 ``` 1240 1239 1241 1241 - Non-nix users can look at the `devShell` attribute in the 1240 1240 + Non-Nix users can look at the `devShell` attribute in the 1242 1241 `flake.nix` file to determine necessary dependencies. 1243 1242 1244 1243 ## Running the appview 1245 1244 1246 1246 - The nix flake also exposes a few `app` attributes (run `nix 1245 1245 + The Nix flake also exposes a few `app` attributes (run `nix 1247 1246 flake show` to see a full list of what the flake provides), 1248 1247 one of the apps runs the appview with the `air` 1249 1248 live-reloader: ··· 1258 1257 nix run .#watch-tailwind 1259 1258 ``` 1260 1259 1261 1261 - To authenticate with the appview, you will need redis and 1262 1262 - OAUTH JWKs to be setup: 1260 1260 + To authenticate with the appview, you will need Redis and 1261 1261 + OAuth JWKs to be set up: 1263 1262 1264 1263 ``` 1265 1265 - # oauth jwks should already be setup by the nix devshell: 1264 1264 + # OAuth JWKs should already be set up by the Nix devshell: 1266 1265 echo $TANGLED_OAUTH_CLIENT_SECRET 1267 1266 z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc 1268 1267 ··· 1280 1279 # the secret key from above 1281 1280 export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..." 1282 1281 1283 1283 - # run redis in at a new shell to store oauth sessions 1282 1282 + # Run Redis in a new shell to store OAuth sessions 1284 1283 redis-server 1285 1284 ``` 1286 1285 1287 1286 ## Running knots and spindles 1288 1287 1289 1288 An end-to-end knot setup requires setting up a machine with 1290 1290 - `sshd`, `AuthorizedKeysCommand`, and git user, which is 1291 1291 - quite cumbersome. So the nix flake provides a 1289 1289 + `sshd`, `AuthorizedKeysCommand`, and a Git user, which is 1290 1290 + quite cumbersome. So the Nix flake provides a 1292 1291 `nixosConfiguration` to do so. 1293 1292 1294 1293 <details> 1295 1295 - <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary> 1294 1294 + <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary> 1296 1295 1297 1296 In order to build Tangled's dev VM on macOS, you will 1298 1297 first need to set up a Linux Nix builder. The recommended ··· 1303 1302 you are using Apple Silicon). 1304 1303 1305 1304 > IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside 1306 1306 - > the tangled repo so that it doesn't conflict with the other VM. For example, 1305 1305 + > the Tangled repo so that it doesn't conflict with the other VM. For example, 1307 1306 > you can do 1308 1307 > 1309 1308 > ```shell ··· 1316 1315 > avoid subtle problems. 1317 1316 1318 1317 Alternatively, you can use any other method to set up a 1319 1319 - Linux machine with `nix` installed that you can `sudo ssh` 1318 1318 + Linux machine with Nix installed that you can `sudo ssh` 1320 1319 into (in other words, root user on your Mac has to be able 1321 1320 to ssh into the Linux machine without entering a password) 1322 1321 and that has the same architecture as your Mac. See ··· 1347 1346 with `ssh` exposed on port 2222. 1348 1347 1349 1348 Once the services are running, head to 1350 1350 - http://localhost:3000/settings/knots and hit verify. It should 1349 1349 + http://localhost:3000/settings/knots and hit "Verify". It should 1351 1350 verify the ownership of the services instantly if everything 1352 1351 went smoothly. 1353 1352 ··· 1371 1370 1372 1371 The above VM should already be running a spindle on 1373 1372 `localhost:6555`. Head to http://localhost:3000/settings/spindles and 1374 1374 - hit verify. You can then configure each repository to use 1373 1373 + hit "Verify". You can then configure each repository to use 1375 1374 this spindle and run CI jobs. 1376 1375 1377 1376 Of interest when debugging spindles: 1378 1377 1379 1378 ``` 1380 1380 - # service logs from journald: 1379 1379 + # Service logs from journald: 1381 1380 journalctl -xeu spindle 1382 1381 1383 1382 # CI job logs from disk: 1384 1383 ls /var/log/spindle 1385 1384 1386 1386 - # debugging spindle db: 1385 1385 + # Debugging spindle database: 1387 1386 sqlite3 /var/lib/spindle/spindle.db 1388 1387 1389 1388 # litecli has a nicer REPL interface: ··· 1432 1431 1433 1432 ### General notes 1434 1433 1435 1435 - - PRs get merged "as-is" (fast-forward) -- like applying a patch-series 1436 1436 - using `git am`. At present, there is no squashing -- so please author 1434 1434 + - PRs get merged "as-is" (fast-forward)—like applying a patch-series 1435 1435 + using `git am`. At present, there is no squashing—so please author 1437 1436 your commits as they would appear on `master`, following the above 1438 1437 guidelines. 1439 1438 - If there is a lot of nesting, for example "appview: ··· 1454 1453 ## Code formatting 1455 1454 1456 1455 We use a variety of tools to format our code, and multiplex them with 1457 1457 - [`treefmt`](https://treefmt.com): all you need to do to format your changes 1456 1456 + [`treefmt`](https://treefmt.com). All you need to do to format your changes 1458 1457 is run `nix run .#fmt` (or just `treefmt` if you're in the devshell). 1459 1458 1460 1459 ## Proposals for bigger changes ··· 1482 1481 We'll use the issue thread to discuss and refine the idea before moving 1483 1482 forward. 1484 1483 1485 1485 - ## Developer certificate of origin (DCO) 1484 1484 + ## Developer Certificate of Origin (DCO) 1486 1485 1487 1486 We require all contributors to certify that they have the right to 1488 1487 submit the code they're contributing. To do this, we follow the

+1 -1

docs/template.html

Reviewed

··· 20 20 <meta name="description" content="$description-meta$" /> 21 21 $endif$ 22 22 23 23 - <title>$pagetitle$ - Tangled docs</title> 23 23 + <title>$pagetitle$</title> 24 24 25 25 <style> 26 26 $styles.css()$