tjh.dev / test
forked from tangled.org/core
Mirror of @tangled.org/core. Running on a Raspberry Pi Zero 2
fork atom

docs: make copy a bit more grammatically consistent

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

authored by anirudh.fi and committed by tangled.org 6e7c3686 13757608

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