lewis.moe / tangled-core
Monorepo for Tangled
fork atom

docs: make copy a bit more grammatically consistent

Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.org>

authored by

Anirudh Oppiliappan and committed by tangled.org 6e7c3686 13757608

+66 -67
unified split
+65 -66
docs/DOCS.md
··· 1 1 --- 2 - title: Tangled Documentation 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 - selfhostable. [tangled.org](https://tangled.org) also 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 - adopting atproto—a protocol for building decentralized 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 - The "appview" at tangled.org acts as a consolidated “view” 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 - # Quick Start Guide 34 + # Quick start guide 35 35 36 - ## Login or Sign up 36 + ## Login or sign up 37 37 38 - You can [login](https://tangled.org) by using your AT 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 - In the AT network, users are free to choose their account 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 - You can think of it as "one account for all of the 50 - atmosphere"! 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 - ## Add an SSH Key 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 - ## Create a Repository 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 - "Knots" are selfhostable, lightweight git servers that can 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 - ## Push Your First Repository 127 + ## Push your first repository 129 128 130 - Initialize a new git repository: 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 - You can inspect your existing git remote like so: 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 - Push all your branches and tags to tangled: 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 - destination (git replaces the push URL when you use `--add` 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 - two push URLs. Now, whenever you push, git will 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 - [@tangled.org/knot-docker](https://tangled.sh/@tangled.sh/knot-docker). 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 - APPVIEW_ENDPOINT=https://tangled.sh 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 - [Nixpkgs](https://github.com/NixOS/nixpkgs). You can 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 - - `submodules`: If you use [git 634 - submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) 632 + - `submodules`: If you use Git submodules 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 - `https://tangled.sh/@example.com/my_pkg`. You can define 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 - project](https://tangled.sh/@tangled.sh/core/blob/master/.tangled/workflows/build.yml). 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 - Spindle is a small CI runner service. Here's a high level overview of how it operates: 838 + Spindle is a small CI runner service. Here's a high-level overview of how it operates: 840 839 841 - * listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and 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 - * when a new repo record comes through (typically when you add a spindle to a 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 - * the spindle engine then handles execution of the pipeline, with results and 848 - logs beamed on the spindle event stream over wss 846 + * The spindle engine then handles execution of the pipeline, with results and 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 - compatibility is enabled, so that `/run/docker.sock` is created). Spindle 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 - This document covers setting up Spindle to use OpenBao for secrets 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 - authentication automatically using AppRole credentials, while Spindle 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 - Install OpenBao from nixpkgs: 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 - # Proxy listener for Spindle 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 - Set these environment variables for Spindle: 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 - On startup, the spindle will now connect to the local proxy, 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 - # Add a test secret via Spindle API, then check it exists 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 - - All Spindle requests go through the proxy, which injects 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 - exist - run the mount creation step again. 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 - # Migrating knots & spindles 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 - After v1.8.2, the HTTP API for knot and spindles have been 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 - - Upgrade to latest tag (v1.9.0 or above) 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 - - Upgrade to latest tag (v1.9.0 or above) 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 - nix](https://nixos.org/download/) (the package manager) 1231 - before working on the codebase. The nix flake provides a lot 1229 + Nix](https://nixos.org/download/) (the package manager) 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 - Non-nix users can look at the `devShell` attribute in the 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 - The nix flake also exposes a few `app` attributes (run `nix 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 - To authenticate with the appview, you will need redis and 1262 - OAUTH JWKs to be setup: 1260 + To authenticate with the appview, you will need Redis and 1261 + OAuth JWKs to be set up: 1263 1262 1264 1263 ``` 1265 - # oauth jwks should already be setup by the nix devshell: 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 - # run redis in at a new shell to store oauth sessions 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 - `sshd`, `AuthorizedKeysCommand`, and git user, which is 1291 - quite cumbersome. So the nix flake provides a 1289 + `sshd`, `AuthorizedKeysCommand`, and a Git user, which is 1290 + quite cumbersome. So the Nix flake provides a 1292 1291 `nixosConfiguration` to do so. 1293 1292 1294 1293 <details> 1295 - <summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary> 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 - > the tangled repo so that it doesn't conflict with the other VM. For example, 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 - Linux machine with `nix` installed that you can `sudo ssh` 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 - http://localhost:3000/settings/knots and hit verify. It should 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 - hit verify. You can then configure each repository to use 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 - # service logs from journald: 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 - # debugging spindle db: 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 - - PRs get merged "as-is" (fast-forward) -- like applying a patch-series 1436 - using `git am`. At present, there is no squashing -- so please author 1434 + - PRs get merged "as-is" (fast-forward)—like applying a patch-series 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 - [`treefmt`](https://treefmt.com): all you need to do to format your changes 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 - ## Developer certificate of origin (DCO) 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
··· 20 20 <meta name="description" content="$description-meta$" /> 21 21 $endif$ 22 22 23 - <title>$pagetitle$ - Tangled docs</title> 23 + <title>$pagetitle$</title> 24 24 25 25 <style> 26 26 $styles.css()$