Monorepo for Tangled
tangled.org
1---
2title: Tangled docs
3author: The Tangled Contributors
4date: 21 Sun, Dec 2025
5abstract: |
6 Tangled is a decentralized code hosting and collaboration
7 platform. Every component of Tangled is open-source and
8 self-hostable. [tangled.org](https://tangled.org) also
9 provides hosting and CI services that are free to use.
10
11 There are several models for decentralized code
12 collaboration platforms, ranging from ActivityPub’s
13 (Forgejo) federated model, to Radicle’s entirely P2P model.
14 Our approach attempts to be the best of both worlds by
15 adopting the AT Protocol—a protocol for building decentralized
16 social applications with a central identity
17
18 Our approach to this is the idea of “knots”. Knots are
19 lightweight, headless servers that enable users to host Git
20 repositories with ease. Knots are designed for either single
21 or multi-tenant use which is perfect for self-hosting on a
22 Raspberry Pi at home, or larger “community” servers. By
23 default, Tangled provides managed knots where you can host
24 your repositories for free.
25
26 The appview at tangled.org acts as a consolidated "view"
27 into the whole network, allowing users to access, clone and
28 contribute to repositories hosted across different knots
29 seamlessly.
30---
31
32# Quick start guide
33
34## Login or sign up
35
36You can [login](https://tangled.org) by using your AT Protocol
37account. If you are unclear on what that means, simply head
38to the [signup](https://tangled.org/signup) page and create
39an account. By doing so, you will be choosing Tangled as
40your account provider (you will be granted a handle of the
41form `user.tngl.sh`).
42
43In the AT Protocol network, users are free to choose their account
44provider (known as a "Personal Data Service", or PDS), and
45login to applications that support AT accounts.
46
47You can think of it as "one account for all of the atmosphere"!
48
49If you already have an AT account (you may have one if you
50signed up to Bluesky, for example), you can login with the
51same handle on Tangled (so just use `user.bsky.social` on
52the login page).
53
54## Add an SSH key
55
56Once you are logged in, you can start creating repositories
57and pushing code. Tangled supports pushing git repositories
58over SSH.
59
60First, you'll need to generate an SSH key if you don't
61already have one:
62
63```bash
64ssh-keygen -t ed25519 -C "foo@bar.com"
65```
66
67When prompted, save the key to the default location
68(`~/.ssh/id_ed25519`) and optionally set a passphrase.
69
70Copy your public key to your clipboard:
71
72```bash
73# on X11
74cat ~/.ssh/id_ed25519.pub | xclip -sel c
75
76# on wayland
77cat ~/.ssh/id_ed25519.pub | wl-copy
78
79# on macos
80cat ~/.ssh/id_ed25519.pub | pbcopy
81```
82
83Now, navigate to 'Settings' -> 'Keys' and hit 'Add Key',
84paste your public key, give it a descriptive name, and hit
85save.
86
87## Create a repository
88
89Once your SSH key is added, create your first repository:
90
911. Hit the green `+` icon on the topbar, and select
92 repository
932. Enter a repository name
943. Add a description
954. Choose a knotserver to host this repository on
965. Hit create
97
98Knots are self-hostable, lightweight Git servers that can
99host your repository. Unlike traditional code forges, your
100code can live on any server. Read the [Knots](TODO) section
101for more.
102
103## Configure SSH
104
105To ensure Git uses the correct SSH key and connects smoothly
106to Tangled, add this configuration to your `~/.ssh/config`
107file:
108
109```
110Host tangled.org
111 Hostname tangled.org
112 User git
113 IdentityFile ~/.ssh/id_ed25519
114 AddressFamily inet
115```
116
117This tells SSH to use your specific key when connecting to
118Tangled and prevents authentication issues if you have
119multiple SSH keys.
120
121Note that this configuration only works for knotservers that
122are hosted by tangled.org. If you use a custom knot, refer
123to the [Knots](TODO) section.
124
125## Push your first repository
126
127Initialize a new Git repository:
128
129```bash
130mkdir my-project
131cd my-project
132
133git init
134echo "# My Project" > README.md
135```
136
137Add some content and push!
138
139```bash
140git add README.md
141git commit -m "Initial commit"
142git remote add origin git@tangled.org:user.tngl.sh/my-project
143git push -u origin main
144```
145
146That's it! Your code is now hosted on Tangled.
147
148## Migrating an existing repository
149
150Moving your repositories from GitHub, GitLab, Bitbucket, or
151any other Git forge to Tangled is straightforward. You'll
152simply change your repository's remote URL. At the moment,
153Tangled does not have any tooling to migrate data such as
154GitHub issues or pull requests.
155
156First, create a new repository on tangled.org as described
157in the [Quick Start Guide](#create-a-repository).
158
159Navigate to your existing local repository:
160
161```bash
162cd /path/to/your/existing/repo
163```
164
165You can inspect your existing Git remote like so:
166
167```bash
168git remote -v
169```
170
171You'll see something like:
172
173```bash
174origin git@github.com:username/my-project.git (fetch)
175origin git@github.com:username/my-project.git (push)
176```
177
178Update the remote URL to point to tangled:
179
180```bash
181git remote set-url origin git@tangled.org:user.tngl.sh/my-project
182```
183
184Verify the change:
185
186```bash
187git remote -v
188```
189
190You should now see:
191
192```bash
193origin git@tangled.org:user.tngl.sh/my-project (fetch)
194origin git@tangled.org:user.tngl.sh/my-project (push)
195```
196
197Push all your branches and tags to Tangled:
198
199```bash
200git push -u origin --all
201git push -u origin --tags
202```
203
204Your repository is now migrated to Tangled! All commit
205history, branches, and tags have been preserved.
206
207## Mirroring a repository to Tangled
208
209If you want to maintain your repository on multiple forges
210simultaneously, for example, keeping your primary repository
211on GitHub while mirroring to Tangled for backup or
212redundancy, you can do so by adding [multiple remotes](https://git-scm.com/docs/git-push#_remotes).
213
214You can configure your local repository to push to both
215Tangled and, say, GitHub. You may already have the following
216setup:
217
218```bash
219$ git remote -v
220origin git@github.com:username/my-project.git (fetch)
221origin git@github.com:username/my-project.git (push)
222```
223
224Now add Tangled as an additional push URL to the same
225remote:
226
227```bash
228git remote set-url --add --push origin git@tangled.org:user.tngl.sh/my-project
229```
230
231You also need to re-add the original URL as a push
232destination (Git will now use the original URL to fetch only):
233
234```bash
235git remote set-url --add --push origin git@github.com:username/my-project.git
236```
237
238Verify your configuration:
239
240```bash
241$ git remote -v
242origin git@github.com:username/my-project.git (fetch)
243origin git@tangled.org:user.tngl.sh/my-project (push)
244origin git@github.com:username/my-project.git (push)
245```
246
247Notice that there's one fetch URL (the primary remote) and
248two push URLs. Now, whenever you push, Git will
249automatically push to both remotes:
250
251```bash
252git push origin main
253```
254
255This single command pushes your `main` branch to both GitHub
256and Tangled simultaneously.
257
258To push all branches and tags:
259
260```bash
261git push origin --all
262git push origin --tags
263```
264
265If you prefer more control over which remote you push to,
266you can maintain separate remotes:
267
268```bash
269git remote add github git@github.com:username/my-project.git
270git remote add tangled git@tangled.org:user.tngl.sh/my-project
271```
272
273Then push to each explicitly:
274
275```bash
276git push github main
277git push tangled main
278```
279
280# Hosting websites on Tangled
281
282You can serve static websites directly from your git repositories on
283Tangled. If you've used GitHub Pages or Codeberg Pages, this should feel
284familiar.
285
286## Overview
287
288Every user gets a sites domain. If you signed up through Tangled's own
289PDS (`tngl.sh`), your sites domain is automatically
290`<your-handle>.tngl.sh` no setup needed. Otherwise, you can claim a
291`<subdomain>.tngl.io` domain from your settings.
292
293You can serve multiple sites per domain:
294
295- One **index site** served at the root of your domain (e.g.
296 `alice.tngl.sh`)
297- Any number of **sub-path sites** served under the repository name
298 (e.g. `alice.tngl.sh/my-project`)
299
300## Claiming a domain
301
302If you don't have a `tngl.sh` handle, you need to claim a domain before
303publishing sites:
304
3051. Go to **Settings → Sites**
3062. Enter a subdomain (e.g. `alice` to claim `alice.tngl.io`)
3073. Click **claim**
308
309You can only hold one domain at a time. Releasing a domain puts it in a
31030-day cooldown before anyone else can claim it.
311
312## Configuring a site for a repository
313
3141. Navigate to your repository
3152. Go to **Settings → Sites**
3163. Choose a **branch** to deploy from
3174. Set the **deploy directory** — the path within the repository
318 containing your `index.html`. Use `/` for the root, or a subdirectory
319 like `/docs` or `/public`
3205. Choose the **site type**:
321 - **Index site** — served at the root of your domain (e.g.
322 `alice.tngl.sh`)
323 - **Sub-path site** — served under the repository name (e.g.
324 `alice.tngl.sh/my-project`)
3256. Click **save**
326
327The site will be deployed automatically. You can see the status of your
328previous deploys in the **Recent Deploys** section at the bottom of the
329page.
330
331Sites are redeployed automatically on every push to the configured
332branch.
333
334## Custom domains
335
336Tangled currently doesn't support custom domains for sites. This will be
337added in a future update.
338
339## Deploy directory
340
341The deploy directory is the path within your repository that Tangled
342serves as the site root. It must contain an `index.html`.
343
344| Deploy directory | Result |
345|---|---|
346| `/` | Serves the repository root |
347| `/docs` | Serves the `docs/` subdirectory |
348| `/public` | Serves the `public/` subdirectory |
349
350Directories are served with automatic `index.html` resolution -- a
351request to `/about` will serve `/about/index.html` if it exists.
352
353## Site types
354
355| Type | URL |
356|---|---|
357| Index site | `alice.tngl.sh` |
358| Sub-path site | `alice.tngl.sh/my-project` |
359
360Only one repository can be the index site for a given domain at a time.
361If another repository already holds the index site, you will see a
362notice in the settings and only the sub-path option will be available.
363
364## Deploy triggers
365
366A deployment is triggered automatically when:
367
368- You push to the configured branch
369- You change the site configuration (branch, deploy directory, or site
370 type)
371
372## Disabling a site
373
374To stop serving a site, go to **Settings → Sites** in your repository
375and click **Disable**. This removes the site configuration and stops
376serving the site. The deployed files are also deleted from storage.
377
378Releasing your domain from **Settings → Sites** at the account level
379will disable all sites associated with it and delete their files.
380
381
382# Knot self-hosting guide
383
384So you want to run your own knot server? Great! Here are a few prerequisites:
385
3861. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux distribution of some kind.
3872. A (sub)domain name. People generally use `knot.example.com`.
3883. A valid SSL certificate for your domain.
389
390## NixOS
391
392Refer to the [knot
393module](https://tangled.org/tangled.org/core/blob/master/nix/modules/knot.nix)
394for a full list of options. Sample configurations:
395
396- [The test VM](https://tangled.org/tangled.org/core/blob/master/nix/vm.nix#L85)
397- [@pyrox.dev/nix](https://tangled.org/pyrox.dev/nix/blob/d19571cc1b5fe01035e1e6951ec8cf8a476b4dee/hosts/marvin/services/tangled.nix#L15-25)
398
399## Docker
400
401Refer to
402[@tangled.org/knot-docker](https://tangled.org/@tangled.org/knot-docker).
403Note that this is community maintained.
404
405## Manual setup
406
407First, clone this repository:
408
409```
410git clone https://tangled.org/@tangled.org/core
411```
412
413Then, build the `knot` CLI. This is the knot administration
414and operation tool. For the purpose of this guide, we're
415only concerned with these subcommands:
416
417- `knot server`: the main knot server process, typically
418 run as a supervised service
419- `knot guard`: handles role-based access control for git
420 over SSH (you'll never have to run this yourself)
421- `knot keys`: fetches SSH keys associated with your knot;
422 we'll use this to generate the SSH
423 `AuthorizedKeysCommand`
424
425```
426cd core
427export CGO_ENABLED=1
428go build -o knot ./cmd/knot
429```
430
431Next, move the `knot` binary to a location owned by `root` --
432`/usr/local/bin/` is a good choice. Make sure the binary itself is also owned by `root`:
433
434```
435sudo mv knot /usr/local/bin/knot
436sudo chown root:root /usr/local/bin/knot
437```
438
439This is necessary because SSH `AuthorizedKeysCommand` requires [really
440specific permissions](https://stackoverflow.com/a/27638306). The
441`AuthorizedKeysCommand` specifies a command that is run by `sshd` to
442retrieve a user's public SSH keys dynamically for authentication. Let's
443set that up.
444
445```
446sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
447Match User git
448 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys
449 AuthorizedKeysCommandUser nobody
450EOF
451```
452
453Then, reload `sshd`:
454
455```
456sudo systemctl reload ssh
457```
458
459Next, create the `git` user. We'll use the `git` user's home directory
460to store repositories:
461
462```
463sudo adduser git
464```
465
466Create `/home/git/.knot.env` with the following, updating the values as
467necessary. The `KNOT_SERVER_OWNER` should be set to your
468DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.
469
470```
471KNOT_REPO_SCAN_PATH=/home/git
472KNOT_SERVER_HOSTNAME=knot.example.com
473APPVIEW_ENDPOINT=https://tangled.org
474KNOT_SERVER_OWNER=did:plc:foobar
475KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
476KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
477```
478
479If you run a Linux distribution that uses systemd, you can
480use the provided service file to run the server. Copy
481[`knotserver.service`](https://tangled.org/tangled.org/core/blob/master/systemd/knotserver.service)
482to `/etc/systemd/system/`. Then, run:
483
484```
485systemctl enable knotserver
486systemctl start knotserver
487```
488
489The last step is to configure a reverse proxy like Nginx or Caddy to front your
490knot. Here's an example configuration for Nginx:
491
492```
493server {
494 listen 80;
495 listen [::]:80;
496 server_name knot.example.com;
497
498 location / {
499 proxy_pass http://localhost:5555;
500 proxy_set_header Host $host;
501 proxy_set_header X-Real-IP $remote_addr;
502 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
503 proxy_set_header X-Forwarded-Proto $scheme;
504 }
505
506 # wss endpoint for git events
507 location /events {
508 proxy_set_header X-Forwarded-For $remote_addr;
509 proxy_set_header Host $http_host;
510 proxy_set_header Upgrade websocket;
511 proxy_set_header Connection Upgrade;
512 proxy_pass http://localhost:5555;
513 }
514 # additional config for SSL/TLS go here.
515}
516
517```
518
519Remember to use Let's Encrypt or similar to procure a certificate for your
520knot domain.
521
522You should now have a running knot server! You can finalize
523your registration by hitting the `verify` button on the
524[/settings/knots](https://tangled.org/settings/knots) page. This simply creates
525a record on your PDS to announce the existence of the knot.
526
527### Custom paths
528
529(This section applies to manual setup only. Docker users should edit the mounts
530in `docker-compose.yml` instead.)
531
532Right now, the database and repositories of your knot lives in `/home/git`. You
533can move these paths if you'd like to store them in another folder. Be careful
534when adjusting these paths:
535
536- Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent
537 any possible side effects. Remember to restart it once you're done.
538- Make backups before moving in case something goes wrong.
539- Make sure the `git` user can read and write from the new paths.
540
541#### Database
542
543As an example, let's say the current database is at `/home/git/knotserver.db`,
544and we want to move it to `/home/git/database/knotserver.db`.
545
546Copy the current database to the new location. Make sure to copy the `.db-shm`
547and `.db-wal` files if they exist.
548
549```
550mkdir /home/git/database
551cp /home/git/knotserver.db* /home/git/database
552```
553
554In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to
555the new file path (_not_ the directory):
556
557```
558KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db
559```
560
561#### Repositories
562
563As an example, let's say the repositories are currently in `/home/git`, and we
564want to move them into `/home/git/repositories`.
565
566Create the new folder, then move the existing repositories (if there are any):
567
568```
569mkdir /home/git/repositories
570# move all DIDs into the new folder; these will vary for you!
571mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories
572```
573
574In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`
575to the new directory:
576
577```
578KNOT_REPO_SCAN_PATH=/home/git/repositories
579```
580
581Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated
582repository path:
583
584```
585sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
586Match User git
587 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories
588 AuthorizedKeysCommandUser nobody
589EOF
590```
591
592Make sure to restart your SSH server!
593
594#### MOTD (message of the day)
595
596To configure the MOTD used ("Welcome to this knot!" by default), edit the
597`/home/git/motd` file:
598
599```
600printf "Hi from this knot!\n" > /home/git/motd
601```
602
603Note that you should add a newline at the end if setting a non-empty message
604since the knot won't do this for you.
605
606## Troubleshooting
607
608If you run your own knot, you may run into some of these
609common issues. You can always join the
610[IRC](https://web.libera.chat/#tangled) or
611[Discord](https://chat.tangled.org/) if this section does
612not help.
613
614### Unable to push
615
616If you are unable to push to your knot or repository:
617
6181. First, ensure that you have added your SSH public key to
619 your account
6202. Check to see that your knot has synced the key by running
621 `knot keys`
6223. Check to see if git is supplying the correct private key
623 when pushing: `GIT_SSH_COMMAND="ssh -v" git push ...`
6244. Check to see if `sshd` on the knot is rejecting the push
625 for some reason: `journalctl -xeu ssh` (or `sshd`,
626 depending on your machine). These logs are unavailable if
627 using docker.
6285. Check to see if the knot itself is rejecting the push,
629 depending on your setup, the logs might be in one of the
630 following paths:
631 - `/tmp/knotguard.log`
632 - `/home/git/log`
633 - `/home/git/guard.log`
634
635# Spindles
636
637## Pipelines
638
639Spindle workflows allow you to write CI/CD pipelines in a
640simple format. They're located in the `.tangled/workflows`
641directory at the root of your repository, and are defined
642using YAML.
643
644The fields are:
645
646- [Trigger](#trigger): A **required** field that defines
647 when a workflow should be triggered.
648- [Engine](#engine): A **required** field that defines which
649 engine a workflow should run on.
650- [Clone options](#clone-options): An **optional** field
651 that defines how the repository should be cloned.
652- [Dependencies](#dependencies): An **optional** field that
653 allows you to list dependencies you may need.
654- [Environment](#environment): An **optional** field that
655 allows you to define environment variables.
656- [Steps](#steps): An **optional** field that allows you to
657 define what steps should run in the workflow.
658
659### Trigger
660
661The first thing to add to a workflow is the trigger, which
662defines when a workflow runs. This is defined using a `when`
663field, which takes in a list of conditions. Each condition
664has the following fields:
665
666- `event`: This is a **required** field that defines when
667 your workflow should run. It's a list that can take one or
668 more of the following values:
669 - `push`: The workflow should run every time a commit is
670 pushed to the repository.
671 - `pull_request`: The workflow should run every time a
672 pull request is made or updated.
673 - `manual`: The workflow can be triggered manually.
674- `branch`: Defines which branches the workflow should run
675 for. If used with the `push` event, commits to the
676 branch(es) listed here will trigger the workflow. If used
677 with the `pull_request` event, updates to pull requests
678 targeting the branch(es) listed here will trigger the
679 workflow. This field has no effect with the `manual`
680 event. Supports glob patterns using `*` and `**` (e.g.,
681 `main`, `develop`, `release-*`). Either `branch` or `tag`
682 (or both) must be specified for `push` events.
683- `tag`: Defines which tags the workflow should run for.
684 Only used with the `push` event - when tags matching the
685 pattern(s) listed here are pushed, the workflow will
686 trigger. This field has no effect with `pull_request` or
687 `manual` events. Supports glob patterns using `*` and `**`
688 (e.g., `v*`, `v1.*`, `release-**`). Either `branch` or
689 `tag` (or both) must be specified for `push` events.
690
691For example, if you'd like to define a workflow that runs
692when commits are pushed to the `main` and `develop`
693branches, or when pull requests that target the `main`
694branch are updated, or manually, you can do so with:
695
696```yaml
697when:
698 - event: ["push", "manual"]
699 branch: ["main", "develop"]
700 - event: ["pull_request"]
701 branch: ["main"]
702```
703
704You can also trigger workflows on tag pushes. For instance,
705to run a deployment workflow when tags matching `v*` are
706pushed:
707
708```yaml
709when:
710 - event: ["push"]
711 tag: ["v*"]
712```
713
714You can even combine branch and tag patterns in a single
715constraint (the workflow triggers if either matches):
716
717```yaml
718when:
719 - event: ["push"]
720 branch: ["main", "release-*"]
721 tag: ["v*", "stable"]
722```
723
724### Engine
725
726Next is the engine on which the workflow should run, defined
727using the **required** `engine` field. The currently
728supported engines are:
729
730- `nixery`: This uses an instance of
731 [Nixery](https://nixery.dev) to run steps, which allows
732 you to add [dependencies](#dependencies) from
733 Nixpkgs (https://github.com/NixOS/nixpkgs). You can
734 search for packages on https://search.nixos.org, and
735 there's a pretty good chance the package(s) you're looking
736 for will be there.
737
738Example:
739
740```yaml
741engine: "nixery"
742```
743
744### Clone options
745
746When a workflow starts, the first step is to clone the
747repository. You can customize this behavior using the
748**optional** `clone` field. It has the following fields:
749
750- `skip`: Setting this to `true` will skip cloning the
751 repository. This can be useful if your workflow is doing
752 something that doesn't require anything from the
753 repository itself. This is `false` by default.
754- `depth`: This sets the number of commits, or the "clone
755 depth", to fetch from the repository. For example, if you
756 set this to 2, the last 2 commits will be fetched. By
757 default, the depth is set to 1, meaning only the most
758 recent commit will be fetched, which is the commit that
759 triggered the workflow.
760- `submodules`: If you use Git submodules
761 (https://git-scm.com/book/en/v2/Git-Tools-Submodules)
762 in your repository, setting this field to `true` will
763 recursively fetch all submodules. This is `false` by
764 default.
765
766The default settings are:
767
768```yaml
769clone:
770 skip: false
771 depth: 1
772 submodules: false
773```
774
775### Dependencies
776
777Usually when you're running a workflow, you'll need
778additional dependencies. The `dependencies` field lets you
779define which dependencies to get, and from where. It's a
780key-value map, with the key being the registry to fetch
781dependencies from, and the value being the list of
782dependencies to fetch.
783
784The registry URL syntax can be found [on the nix
785manual](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-registry-add).
786
787Say you want to fetch Node.js and Go from `nixpkgs`, and a
788package called `my_pkg` you've made from your own registry
789at your repository at
790`https://tangled.org/@example.com/my_pkg`. You can define
791those dependencies like so:
792
793```yaml
794dependencies:
795 # nixpkgs
796 nixpkgs:
797 - nodejs
798 - go
799 # unstable
800 nixpkgs/nixpkgs-unstable:
801 - bun
802 # custom registry
803 git+https://tangled.org/@example.com/my_pkg:
804 - my_pkg
805```
806
807Now these dependencies are available to use in your
808workflow!
809
810### Environment
811
812The `environment` field allows you define environment
813variables that will be available throughout the entire
814workflow. **Do not put secrets here, these environment
815variables are visible to anyone viewing the repository. You
816can add secrets for pipelines in your repository's
817settings.**
818
819Example:
820
821```yaml
822environment:
823 GOOS: "linux"
824 GOARCH: "arm64"
825 NODE_ENV: "production"
826 MY_ENV_VAR: "MY_ENV_VALUE"
827```
828
829By default, the following environment variables are set:
830
831- `CI` - Always set to `true` to indicate a CI environment
832- `TANGLED_PIPELINE_ID` - The AT URI of the current pipeline
833- `TANGLED_PIPELINE_KIND` - One of `push`, `pull_request` or
834 `manual`
835- `TANGLED_REPO_KNOT` - The repository's knot hostname
836- `TANGLED_REPO_DID` - The DID of the repository owner
837- `TANGLED_REPO_NAME` - The name of the repository
838- `TANGLED_REPO_DEFAULT_BRANCH` - The default branch of the
839 repository
840- `TANGLED_REPO_URL` - The full URL to the repository
841
842These variables are only available when the pipeline is
843triggered by a push:
844
845- `TANGLED_REF` - The full git reference (e.g.,
846 `refs/heads/main` or `refs/tags/v1.0.0`)
847- `TANGLED_REF_NAME` - The short name of the reference
848 (e.g., `main` or `v1.0.0`)
849- `TANGLED_REF_TYPE` - The type of reference, either
850 `branch` or `tag`
851- `TANGLED_SHA` - The commit SHA that triggered the pipeline
852- `TANGLED_COMMIT_SHA` - Alias for `TANGLED_SHA`
853
854These variables are only available when the pipeline is
855triggered by a pull request:
856
857- `TANGLED_PR_SOURCE_BRANCH` - The source branch of the pull
858 request
859- `TANGLED_PR_TARGET_BRANCH` - The target branch of the pull
860 request
861- `TANGLED_PR_SOURCE_SHA` - The commit SHA of the source
862 branch
863
864### Steps
865
866The `steps` field allows you to define what steps should run
867in the workflow. It's a list of step objects, each with the
868following fields:
869
870- `name`: This field allows you to give your step a name.
871 This name is visible in your workflow runs, and is used to
872 describe what the step is doing.
873- `command`: This field allows you to define a command to
874 run in that step. The step is run in a Bash shell, and the
875 logs from the command will be visible in the pipelines
876 page on the Tangled website. The
877 [dependencies](#dependencies) you added will be available
878 to use here.
879- `environment`: Similar to the global
880 [environment](#environment) config, this **optional**
881 field is a key-value map that allows you to set
882 environment variables for the step. **Do not put secrets
883 here, these environment variables are visible to anyone
884 viewing the repository. You can add secrets for pipelines
885 in your repository's settings.**
886
887Example:
888
889```yaml
890steps:
891 - name: "Build backend"
892 command: "go build"
893 environment:
894 GOOS: "darwin"
895 GOARCH: "arm64"
896 - name: "Build frontend"
897 command: "npm run build"
898 environment:
899 NODE_ENV: "production"
900```
901
902### Complete workflow
903
904```yaml
905# .tangled/workflows/build.yml
906
907when:
908 - event: ["push", "manual"]
909 branch: ["main", "develop"]
910 - event: ["pull_request"]
911 branch: ["main"]
912
913engine: "nixery"
914
915# using the default values
916clone:
917 skip: false
918 depth: 1
919 submodules: false
920
921dependencies:
922 # nixpkgs
923 nixpkgs:
924 - nodejs
925 - go
926 # custom registry
927 git+https://tangled.org/@example.com/my_pkg:
928 - my_pkg
929
930environment:
931 GOOS: "linux"
932 GOARCH: "arm64"
933 NODE_ENV: "production"
934 MY_ENV_VAR: "MY_ENV_VALUE"
935
936steps:
937 - name: "Build backend"
938 command: "go build"
939 environment:
940 GOOS: "darwin"
941 GOARCH: "arm64"
942 - name: "Build frontend"
943 command: "npm run build"
944 environment:
945 NODE_ENV: "production"
946```
947
948If you want another example of a workflow, you can look at
949the one [Tangled uses to build the
950project](https://tangled.org/@tangled.org/core/blob/master/.tangled/workflows/build.yml).
951
952## Self-hosting guide
953
954### Prerequisites
955
956- Go
957- Docker (the only supported backend currently)
958
959### Configuration
960
961Spindle is configured using environment variables. The following environment variables are available:
962
963- `SPINDLE_SERVER_LISTEN_ADDR`: The address the server listens on (default: `"0.0.0.0:6555"`).
964- `SPINDLE_SERVER_DB_PATH`: The path to the SQLite database file (default: `"spindle.db"`).
965- `SPINDLE_SERVER_HOSTNAME`: The hostname of the server (required).
966- `SPINDLE_SERVER_JETSTREAM_ENDPOINT`: The endpoint of the Jetstream server (default: `"wss://jetstream1.us-west.bsky.network/subscribe"`).
967- `SPINDLE_SERVER_DEV`: A boolean indicating whether the server is running in development mode (default: `false`).
968- `SPINDLE_SERVER_OWNER`: The DID of the owner (required).
969- `SPINDLE_SERVER_LOG_DIR`: The directory to store workflow logs (default: `"/var/log/spindle"`).
970- `SPINDLE_SERVER_DOCKER_SOCKET`: Path to Docker socket to expose to invoked Spindle containers (default: `""`).
971- `SPINDLE_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`).
972- `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`).
973
974### Running spindle
975
9761. **Set the environment variables.** For example:
977
978 ```shell
979 export SPINDLE_SERVER_HOSTNAME="your-hostname"
980 export SPINDLE_SERVER_OWNER="your-did"
981 ```
982
9832. **Build the Spindle binary.**
984
985 ```shell
986 cd core
987 go mod download
988 go build -o cmd/spindle/spindle cmd/spindle/main.go
989 ```
990
9913. **Create the log directory.**
992
993 ```shell
994 sudo mkdir -p /var/log/spindle
995 sudo chown $USER:$USER -R /var/log/spindle
996 ```
997
9984. **Run the Spindle binary.**
999
1000 ```shell
1001 ./cmd/spindle/spindle
1002 ```
1003
1004Spindle will now start, connect to the Jetstream server, and begin processing pipelines.
1005
1006## Architecture
1007
1008Spindle is a small CI runner service. Here's a high-level overview of how it operates:
1009
1010- Listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and
1011 [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream.
1012- When a new repo record comes through (typically when you add a spindle to a
1013 repo from the settings), spindle then resolves the underlying knot and
1014 subscribes to repo events (see:
1015 [`sh.tangled.pipeline`](/lexicons/pipeline.json)).
1016- The spindle engine then handles execution of the pipeline, with results and
1017 logs beamed on the spindle event stream over WebSocket
1018
1019### The engine
1020
1021At present, the only supported backend is Docker (and Podman, if Docker
1022compatibility is enabled, so that `/run/docker.sock` is created). spindle
1023executes each step in the pipeline in a fresh container, with state persisted
1024across steps within the `/tangled/workspace` directory.
1025
1026The base image for the container is constructed on the fly using
1027[Nixery](https://nixery.dev), which is handy for caching layers for frequently
1028used packages.
1029
1030The pipeline manifest is [specified here](https://docs.tangled.org/spindles.html#pipelines).
1031
1032## Secrets with openbao
1033
1034This document covers setting up spindle to use OpenBao for secrets
1035management via OpenBao Proxy instead of the default SQLite backend.
1036
1037### Overview
1038
1039Spindle now uses OpenBao Proxy for secrets management. The proxy handles
1040authentication automatically using AppRole credentials, while spindle
1041connects to the local proxy instead of directly to the OpenBao server.
1042
1043This approach provides better security, automatic token renewal, and
1044simplified application code.
1045
1046### Installation
1047
1048Install OpenBao from Nixpkgs:
1049
1050```bash
1051nix shell nixpkgs#openbao # for a local server
1052```
1053
1054### Setup
1055
1056The setup process can is documented for both local development and production.
1057
1058#### Local development
1059
1060Start OpenBao in dev mode:
1061
1062```bash
1063bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201
1064```
1065
1066This starts OpenBao on `http://localhost:8201` with a root token.
1067
1068Set up environment for bao CLI:
1069
1070```bash
1071export BAO_ADDR=http://localhost:8200
1072export BAO_TOKEN=root
1073```
1074
1075#### Production
1076
1077You would typically use a systemd service with a
1078configuration file. Refer to
1079[@tangled.org/infra](https://tangled.org/@tangled.org/infra)
1080for how this can be achieved using Nix.
1081
1082Then, initialize the bao server:
1083
1084```bash
1085bao operator init -key-shares=1 -key-threshold=1
1086```
1087
1088This will print out an unseal key and a root key. Save them
1089somewhere (like a password manager). Then unseal the vault
1090to begin setting it up:
1091
1092```bash
1093bao operator unseal <unseal_key>
1094```
1095
1096All steps below remain the same across both dev and
1097production setups.
1098
1099#### Configure openbao server
1100
1101Create the spindle KV mount:
1102
1103```bash
1104bao secrets enable -path=spindle -version=2 kv
1105```
1106
1107Set up AppRole authentication and policy:
1108
1109Create a policy file `spindle-policy.hcl`:
1110
1111```hcl
1112# Full access to spindle KV v2 data
1113path "spindle/data/*" {
1114 capabilities = ["create", "read", "update", "delete"]
1115}
1116
1117# Access to metadata for listing and management
1118path "spindle/metadata/*" {
1119 capabilities = ["list", "read", "delete", "update"]
1120}
1121
1122# Allow listing at root level
1123path "spindle/" {
1124 capabilities = ["list"]
1125}
1126
1127# Required for connection testing and health checks
1128path "auth/token/lookup-self" {
1129 capabilities = ["read"]
1130}
1131```
1132
1133Apply the policy and create an AppRole:
1134
1135```bash
1136bao policy write spindle-policy spindle-policy.hcl
1137bao auth enable approle
1138bao write auth/approle/role/spindle \
1139 token_policies="spindle-policy" \
1140 token_ttl=1h \
1141 token_max_ttl=4h \
1142 bind_secret_id=true \
1143 secret_id_ttl=0 \
1144 secret_id_num_uses=0
1145```
1146
1147Get the credentials:
1148
1149```bash
1150# Get role ID (static)
1151ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id)
1152
1153# Generate secret ID
1154SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id)
1155
1156echo "Role ID: $ROLE_ID"
1157echo "Secret ID: $SECRET_ID"
1158```
1159
1160#### Create proxy configuration
1161
1162Create the credential files:
1163
1164```bash
1165# Create directory for OpenBao files
1166mkdir -p /tmp/openbao
1167
1168# Save credentials
1169echo "$ROLE_ID" > /tmp/openbao/role-id
1170echo "$SECRET_ID" > /tmp/openbao/secret-id
1171chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id
1172```
1173
1174Create a proxy configuration file `/tmp/openbao/proxy.hcl`:
1175
1176```hcl
1177# OpenBao server connection
1178vault {
1179 address = "http://localhost:8200"
1180}
1181
1182# Auto-Auth using AppRole
1183auto_auth {
1184 method "approle" {
1185 mount_path = "auth/approle"
1186 config = {
1187 role_id_file_path = "/tmp/openbao/role-id"
1188 secret_id_file_path = "/tmp/openbao/secret-id"
1189 }
1190 }
1191
1192 # Optional: write token to file for debugging
1193 sink "file" {
1194 config = {
1195 path = "/tmp/openbao/token"
1196 mode = 0640
1197 }
1198 }
1199}
1200
1201# Proxy listener for spindle
1202listener "tcp" {
1203 address = "127.0.0.1:8201"
1204 tls_disable = true
1205}
1206
1207# Enable API proxy with auto-auth token
1208api_proxy {
1209 use_auto_auth_token = true
1210}
1211
1212# Enable response caching
1213cache {
1214 use_auto_auth_token = true
1215}
1216
1217# Logging
1218log_level = "info"
1219```
1220
1221#### Start the proxy
1222
1223Start OpenBao Proxy:
1224
1225```bash
1226bao proxy -config=/tmp/openbao/proxy.hcl
1227```
1228
1229The proxy will authenticate with OpenBao and start listening on
1230`127.0.0.1:8201`.
1231
1232#### Configure spindle
1233
1234Set these environment variables for spindle:
1235
1236```bash
1237export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
1238export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201
1239export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
1240```
1241
1242On startup, spindle will now connect to the local proxy,
1243which handles all authentication automatically.
1244
1245### Production setup for proxy
1246
1247For production, you'll want to run the proxy as a service:
1248
1249Place your production configuration in
1250`/etc/openbao/proxy.hcl` with proper TLS settings for the
1251vault connection.
1252
1253### Verifying setup
1254
1255Test the proxy directly:
1256
1257```bash
1258# Check proxy health
1259curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health
1260
1261# Test token lookup through proxy
1262curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self
1263```
1264
1265Test OpenBao operations through the server:
1266
1267```bash
1268# List all secrets
1269bao kv list spindle/
1270
1271# Add a test secret via the spindle API, then check it exists
1272bao kv list spindle/repos/
1273
1274# Get a specific secret
1275bao kv get spindle/repos/your_repo_path/SECRET_NAME
1276```
1277
1278### How it works
1279
1280- Spindle connects to OpenBao Proxy on localhost (typically
1281 port 8200 or 8201)
1282- The proxy authenticates with OpenBao using AppRole
1283 credentials
1284- All spindle requests go through the proxy, which injects
1285 authentication tokens
1286- Secrets are stored at
1287 `spindle/repos/{sanitized_repo_path}/{secret_key}`
1288- Repository paths like `did:plc:alice/myrepo` become
1289 `did_plc_alice_myrepo`
1290- The proxy handles all token renewal automatically
1291- Spindle no longer manages tokens or authentication
1292 directly
1293
1294### Troubleshooting
1295
1296**Connection refused**: Check that the OpenBao Proxy is
1297running and listening on the configured address.
1298
1299**403 errors**: Verify the AppRole credentials are correct
1300and the policy has the necessary permissions.
1301
1302**404 route errors**: The spindle KV mount probably doesn't
1303exist—run the mount creation step again.
1304
1305**Proxy authentication failures**: Check the proxy logs and
1306verify the role-id and secret-id files are readable and
1307contain valid credentials.
1308
1309**Secret not found after writing**: This can indicate policy
1310permission issues. Verify the policy includes both
1311`spindle/data/*` and `spindle/metadata/*` paths with
1312appropriate capabilities.
1313
1314Check proxy logs:
1315
1316```bash
1317# If running as systemd service
1318journalctl -u openbao-proxy -f
1319
1320# If running directly, check the console output
1321```
1322
1323Test AppRole authentication manually:
1324
1325```bash
1326bao write auth/approle/login \
1327 role_id="$(cat /tmp/openbao/role-id)" \
1328 secret_id="$(cat /tmp/openbao/secret-id)"
1329```
1330
1331# Webhooks
1332
1333Webhooks allow you to receive HTTP POST notifications when events occur in your repositories. This enables you to integrate Tangled with external services, trigger CI/CD pipelines, send notifications, or automate workflows.
1334
1335## Overview
1336
1337Webhooks send HTTP POST requests to URLs you configure whenever specific events happen. Currently, Tangled supports push events, with more event types coming soon.
1338
1339## Configuring webhooks
1340
1341To set up a webhook for your repository:
1342
13431. Navigate to your repository
13442. Go to **Settings → Hooks**
13453. Click **new webhook**
13464. Configure your webhook:
1347 - **Payload URL**: The endpoint that will receive the webhook POST requests
1348 - **Secret**: An optional secret key for verifying webhook authenticity (leave blank to send unsigned webhooks)
1349 - **Events**: Select which events trigger the webhook (currently only push events)
1350 - **Active**: Toggle whether the webhook is enabled
1351
1352## Webhook payload
1353
1354### Push
1355
1356When a push event occurs, Tangled sends a POST request with a JSON payload of the format:
1357
1358```json
1359{
1360 "after": "7b320e5cbee2734071e4310c1d9ae401d8f6cab5",
1361 "before": "c04ddf64eddc90e4e2a9846ba3b43e67a0e2865e",
1362 "pusher": {
1363 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq"
1364 },
1365 "ref": "refs/heads/main",
1366 "repository": {
1367 "clone_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1368 "created_at": "2025-09-15T08:57:23Z",
1369 "description": "an example repository",
1370 "fork": false,
1371 "full_name": "did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1372 "html_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1373 "name": "some-repo",
1374 "open_issues_count": 5,
1375 "owner": {
1376 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq"
1377 },
1378 "ssh_url": "ssh://git@tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1379 "stars_count": 1,
1380 "updated_at": "2025-09-15T08:57:23Z"
1381 }
1382}
1383```
1384
1385## HTTP headers
1386
1387Each webhook request includes the following headers:
1388
1389- `Content-Type: application/json`
1390- `User-Agent: Tangled-Hook/<short-sha>` — User agent with short SHA of the commit
1391- `X-Tangled-Event: push` — The event type
1392- `X-Tangled-Hook-ID: <webhook-id>` — The webhook ID
1393- `X-Tangled-Delivery: <uuid>` — Unique delivery ID
1394- `X-Tangled-Signature-256: sha256=<hmac>` — HMAC-SHA256 signature (if secret configured)
1395
1396## Verifying webhook signatures
1397
1398If you configured a secret, you should verify the webhook signature to ensure requests are authentic. For example, in Go:
1399
1400```go
1401package main
1402
1403import (
1404 "crypto/hmac"
1405 "crypto/sha256"
1406 "encoding/hex"
1407 "io"
1408 "net/http"
1409 "strings"
1410)
1411
1412func verifySignature(payload []byte, signatureHeader, secret string) bool {
1413 // Remove 'sha256=' prefix from signature header
1414 signature := strings.TrimPrefix(signatureHeader, "sha256=")
1415
1416 // Compute expected signature
1417 mac := hmac.New(sha256.New, []byte(secret))
1418 mac.Write(payload)
1419 expected := hex.EncodeToString(mac.Sum(nil))
1420
1421 // Use constant-time comparison to prevent timing attacks
1422 return hmac.Equal([]byte(signature), []byte(expected))
1423}
1424
1425func webhookHandler(w http.ResponseWriter, r *http.Request) {
1426 // Read the request body
1427 payload, err := io.ReadAll(r.Body)
1428 if err != nil {
1429 http.Error(w, "Bad request", http.StatusBadRequest)
1430 return
1431 }
1432
1433 // Get signature from header
1434 signatureHeader := r.Header.Get("X-Tangled-Signature-256")
1435
1436 // Verify signature
1437 if signatureHeader != "" && verifySignature(payload, signatureHeader, yourSecret) {
1438 // Webhook is authentic, process it
1439 processWebhook(payload)
1440 w.WriteHeader(http.StatusOK)
1441 } else {
1442 http.Error(w, "Invalid signature", http.StatusUnauthorized)
1443 }
1444}
1445```
1446
1447## Delivery retries
1448
1449Webhooks are automatically retried on failure:
1450
1451- **3 total attempts** (1 initial + 2 retries)
1452- **Exponential backoff** starting at 1 second, max 10 seconds
1453- **Retried on**:
1454 - Network errors
1455 - HTTP 5xx server errors
1456- **Not retried on**:
1457 - HTTP 4xx client errors (bad request, unauthorized, etc.)
1458
1459### Timeouts
1460
1461Webhook requests timeout after 30 seconds. If your endpoint needs more time:
1462
14631. Respond with 200 OK immediately
14642. Process the webhook asynchronously in the background
1465
1466## Example integrations
1467
1468### Discord notifications
1469
1470```javascript
1471app.post("/webhook", (req, res) => {
1472 const payload = req.body;
1473
1474 fetch("https://discord.com/api/webhooks/...", {
1475 method: "POST",
1476 headers: { "Content-Type": "application/json" },
1477 body: JSON.stringify({
1478 content: `New push to ${payload.repository.full_name}`,
1479 embeds: [
1480 {
1481 title: `${payload.pusher.did} pushed to ${payload.ref}`,
1482 url: payload.repository.html_url,
1483 color: 0x00ff00,
1484 },
1485 ],
1486 }),
1487 });
1488
1489 res.status(200).send("OK");
1490});
1491```
1492
1493# Migrating knots and spindles
1494
1495Sometimes, non-backwards compatible changes are made to the
1496knot/spindle XRPC APIs. If you host a knot or a spindle, you
1497will need to follow this guide to upgrade. Typically, this
1498only requires you to deploy the newest version.
1499
1500This document is laid out in reverse-chronological order.
1501Newer migration guides are listed first, and older guides
1502are further down the page.
1503
1504## Upgrading to v1.14.0-alpha
1505
1506Starting with v1.14.0-alpha, the fully knot uses the repoDID as its
1507canonical handle for repositories. This unlocks repository
1508renames from the appview UI and changes the wire format for
1509the following lexicons (`sh.tangled.repo.pull`, `sh.tangled.repo.collaborator`,
1510`sh.tangled.repo.issue`, `sh.tangled.git.refUpdate`).
1511
1512Knots that have not been upgraded may silently drop new push
1513events, pull requests, issues, and collaborator invites for
1514repositories they host until upgraded. So upgrade please!!!
1515
1516- Upgrade to the latest tag (v1.14.0 or above)
1517- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1518 hit the "retry" button to verify your knot
1519
1520## Upgrading to v1.13.0-alpha
1521
1522Starting with v1.13.0-alpha, every repository on a knot is
1523assigned a DID. This makes repositories stable across
1524renames and transfers.
1525
1526When you upgrade your knot to this version, the server will
1527automatically mint DIDs for all existing repositories on
1528startup. This is a one-time process and you may see
1529additional log output during the first boot as DIDs are
1530assigned.
1531
1532- Upgrade to the latest tag (v1.13.0 or above)
1533- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1534 hit the "retry" button to verify your knot
1535
1536## Upgrading from v1.8.x
1537
1538After v1.8.2, the HTTP API for knots and spindles has been
1539deprecated and replaced with XRPC. Repositories on outdated
1540knots will not be viewable from the appview. Upgrading is
1541straightforward however.
1542
1543For knots:
1544
1545- Upgrade to the latest tag (v1.9.0 or above)
1546- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1547 hit the "retry" button to verify your knot
1548
1549For spindles:
1550
1551- Upgrade to the latest tag (v1.9.0 or above)
1552- Head to the [spindle
1553 dashboard](https://tangled.org/settings/spindles) and hit the
1554 "retry" button to verify your spindle
1555
1556## Upgrading from v1.7.x
1557
1558After v1.7.0, knot secrets have been deprecated. You no
1559longer need a secret from the appview to run a knot. All
1560authorized commands to knots are managed via [Inter-Service
1561Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
1562Knots will be read-only until upgraded.
1563
1564Upgrading is quite easy, in essence:
1565
1566- `KNOT_SERVER_SECRET` is no more, you can remove this
1567 environment variable entirely
1568- `KNOT_SERVER_OWNER` is now required on boot, set this to
1569 your DID. You can find your DID in the
1570 [settings](https://tangled.org/settings) page.
1571- Restart your knot once you have replaced the environment
1572 variable
1573- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1574 hit the "retry" button to verify your knot. This simply
1575 writes a `sh.tangled.knot` record to your PDS.
1576
1577If you use the nix module, simply bump the flake to the
1578latest revision, and change your config block like so:
1579
1580```diff
1581 services.tangled.knot = {
1582 enable = true;
1583 server = {
1584- secretFile = /path/to/secret;
1585+ owner = "did:plc:foo";
1586 };
1587 };
1588```
1589
1590# Hacking on Tangled
1591
1592We highly recommend [installing
1593Nix](https://nixos.org/download/) (the package manager)
1594before working on the codebase. The Nix flake provides a lot
1595of helpers to get started and most importantly, builds and
1596dev shells are entirely deterministic.
1597
1598To set up your dev environment:
1599
1600```bash
1601nix develop
1602```
1603
1604Non-Nix users can look at the `devShell` attribute in the
1605`flake.nix` file to determine necessary dependencies.
1606
1607## Running the appview
1608
1609The appview requires Redis and OAuth JWKs. Start these
1610first, before launching the appview itself.
1611
1612```bash
1613# OAuth JWKs should already be set up by the Nix devshell:
1614echo $TANGLED_OAUTH_CLIENT_SECRET
1615z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc
1616
1617echo $TANGLED_OAUTH_CLIENT_KID
16181761667908
1619
1620# if not, you can set it up yourself:
1621goat key generate -t P-256
1622Key Type: P-256 / secp256r1 / ES256 private key
1623Secret Key (Multibase Syntax): save this securely (eg, add to password manager)
1624 z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL
1625Public Key (DID Key Syntax): share or publish this (eg, in DID document)
1626 did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR
1627
1628# the secret key from above
1629export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..."
1630
1631# Run Redis in a new shell to store OAuth sessions
1632redis-server
1633```
1634
1635The Nix flake exposes a few `app` attributes (run `nix
1636flake show` to see a full list of what the flake provides),
1637one of the apps runs the appview with the `air`
1638live-reloader:
1639
1640```bash
1641TANGLED_DEV=true nix run .#watch-appview
1642
1643# TANGLED_DB_PATH might be of interest to point to
1644# different sqlite DBs
1645
1646# in a separate shell, you can live-reload tailwind
1647nix run .#watch-tailwind
1648```
1649
1650## Running knots and spindles
1651
1652An end-to-end knot setup requires setting up a machine with
1653`sshd`, `AuthorizedKeysCommand`, and a Git user, which is
1654quite cumbersome. So the Nix flake provides a
1655`nixosConfiguration` to do so.
1656
1657<details>
1658 <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary>
1659
1660In order to build Tangled's dev VM on macOS, you will
1661first need to set up a Linux Nix builder. The recommended
1662way to do so is to run a [`darwin.linux-builder`
1663VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)
1664and to register it in `nix.conf` as a builder for Linux
1665with the same architecture as your Mac (`linux-aarch64` if
1666you are using Apple Silicon).
1667
1668If you're on nix-darwin, you can simply add
1669
1670```
1671nix.linux-builder.enable = true;
1672```
1673
1674to your host's `configuration.nix`.
1675
1676Alternatively, you can use any other method to set up a
1677Linux machine with Nix installed that you can `sudo ssh`
1678into (in other words, root user on your Mac has to be able
1679to ssh into the Linux machine without entering a password)
1680and that has the same architecture as your Mac. See
1681[remote builder
1682instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)
1683for how to register such a builder in `nix.conf`.
1684
1685> WARNING: If you'd like to use
1686> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
1687> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
1688ssh` works can be tricky. It seems to be [possible with
1689> Orbstack](https://github.com/orgs/orbstack/discussions/1669).
1690
1691</details>
1692
1693To begin, grab your DID from http://localhost:3000/settings.
1694Then, set `TANGLED_VM_KNOT_OWNER` and
1695`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a
1696lightweight NixOS VM like so:
1697
1698```bash
1699nix run --impure .#vm
1700
1701# type `poweroff` at the shell to exit the VM
1702```
1703
1704This starts a knot on port 6444, a spindle on port 6555
1705with `ssh` exposed on port 2222.
1706
1707Once the services are running, head to
1708http://localhost:3000/settings/knots and hit "Verify". It should
1709verify the ownership of the services instantly if everything
1710went smoothly.
1711
1712You can push repositories to this VM with this ssh config
1713block on your main machine:
1714
1715```bash
1716Host nixos-shell
1717 Hostname localhost
1718 Port 2222
1719 User git
1720 IdentityFile ~/.ssh/my_tangled_key
1721```
1722
1723Set up a remote called `local-dev` on a git repo:
1724
1725```bash
1726git remote add local-dev git@nixos-shell:user/repo
1727git push local-dev main
1728```
1729
1730The above VM should already be running a spindle on
1731`localhost:6555`. Head to http://localhost:3000/settings/spindles and
1732hit "Verify". You can then configure each repository to use
1733this spindle and run CI jobs.
1734
1735Of interest when debugging spindles:
1736
1737```
1738# Service logs from journald:
1739journalctl -xeu spindle
1740
1741# CI job logs from disk:
1742ls /var/log/spindle
1743
1744# Debugging spindle database:
1745sqlite3 /var/lib/spindle/spindle.db
1746
1747# litecli has a nicer REPL interface:
1748litecli /var/lib/spindle/spindle.db
1749```
1750
1751If for any reason you wish to disable either one of the
1752services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set
1753`services.tangled.spindle.enable` (or
1754`services.tangled.knot.enable`) to `false`.
1755
1756# Contribution guide
1757
1758## Commit guidelines
1759
1760We follow a commit style similar to the Go project. Please keep commits:
1761
1762- **atomic**: each commit should represent one logical change
1763- **descriptive**: the commit message should clearly describe what the
1764 change does and why it's needed
1765
1766### Message format
1767
1768```
1769<service/top-level directory>/<affected package/directory>: <short summary of change>
1770
1771Optional longer description can go here, if necessary. Explain what the
1772change does and why, especially if not obvious. Reference relevant
1773issues or PRs when applicable. These can be links for now since we don't
1774auto-link issues/PRs yet.
1775```
1776
1777Here are some examples:
1778
1779```
1780appview/state: fix token expiry check in middleware
1781
1782The previous check did not account for clock drift, leading to premature
1783token invalidation.
1784```
1785
1786```
1787knotserver/git/service: improve error checking in upload-pack
1788```
1789
1790### General notes
1791
1792- PRs get merged "as-is" (fast-forward)—like applying a patch-series
1793 using `git am`. At present, there is no squashing—so please author
1794 your commits as they would appear on `master`, following the above
1795 guidelines.
1796- If there is a lot of nesting, for example "appview:
1797 pages/templates/repo/fragments: ...", these can be truncated down to
1798 just "appview: repo/fragments: ...". If the change affects a lot of
1799 subdirectories, you may abbreviate to just the top-level names, e.g.
1800 "appview: ..." or "knotserver: ...".
1801- Keep commits lowercased with no trailing period.
1802- Use the imperative mood in the summary line (e.g., "fix bug" not
1803 "fixed bug" or "fixes bug").
1804- Try to keep the summary line under 72 characters, but we aren't too
1805 fussed about this.
1806- Follow the same formatting for PR titles if filled manually.
1807- Don't include unrelated changes in the same commit.
1808- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
1809 before submitting if necessary.
1810
1811## Code formatting
1812
1813We use a variety of tools to format our code, and multiplex them with
1814[`treefmt`](https://treefmt.com). All you need to do to format your changes
1815is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).
1816
1817## Proposals for bigger changes
1818
1819Small fixes like typos, minor bugs, or trivial refactors can be
1820submitted directly as PRs.
1821
1822For larger changes—especially those introducing new features, significant
1823refactoring, or altering system behavior—please open a proposal first. This
1824helps us evaluate the scope, design, and potential impact before implementation.
1825
1826Create a new issue titled:
1827
1828```
1829proposal: <affected scope>: <summary of change>
1830```
1831
1832In the description, explain:
1833
1834- What the change is
1835- Why it's needed
1836- How you plan to implement it (roughly)
1837- Any open questions or tradeoffs
1838
1839We'll use the issue thread to discuss and refine the idea before moving
1840forward.
1841
1842## Developer Certificate of Origin (DCO)
1843
1844We require all contributors to certify that they have the right to
1845submit the code they're contributing. To do this, we follow the
1846[Developer Certificate of Origin
1847(DCO)](https://developercertificate.org/).
1848
1849By signing your commits, you're stating that the contribution is your
1850own work, or that you have the right to submit it under the project's
1851license. This helps us keep things clean and legally sound.
1852
1853To sign your commit, just add the `-s` flag when committing:
1854
1855```sh
1856git commit -s -m "your commit message"
1857```
1858
1859This appends a line like:
1860
1861```
1862Signed-off-by: Your Name <your.email@example.com>
1863```
1864
1865We won't merge commits if they aren't signed off. If you forget, you can
1866amend the last commit like this:
1867
1868```sh
1869git commit --amend -s
1870```
1871
1872If you're submitting a PR with multiple commits, make sure each one is
1873signed.
1874
1875For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command
1876to make it sign off commits in the tangled repo:
1877
1878```shell
1879# Safety check, should say "No matching config key..."
1880jj config list templates.commit_trailers
1881# The command below may need to be adjusted if the command above returned something.
1882jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"
1883```
1884
1885Refer to the [jujutsu
1886documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)
1887for more information.
1888
1889# Troubleshooting guide
1890
1891## Login issues
1892
1893Owing to the distributed nature of OAuth on AT Protocol, you
1894may run into issues with logging in. If you run a
1895self-hosted PDS:
1896
1897- You may need to ensure that your PDS is timesynced using
1898 NTP:
1899 - Enable the `ntpd` service
1900 - Run `ntpd -qg` to synchronize your clock
1901- You may need to increase the default request timeout:
1902 `NODE_OPTIONS="--network-family-autoselection-attempt-timeout=500"`
1903
1904## Empty punchcard
1905
1906For Tangled to register commits that you make across the
1907network, you need to setup one of following:
1908
1909- The committer email should be a verified email associated
1910 to your account. You can add and verify emails on the
1911 settings page.
1912- Or, the committer email should be set to your account's
1913 DID: `git config user.email "did:plc:foobar"`. You can find
1914 your account's DID on the settings page
1915
1916## Commit is not marked as verified
1917
1918Presently, Tangled only supports SSH commit signatures.
1919
1920To sign commits using an SSH key with git:
1921
1922```
1923git config --global gpg.format ssh
1924git config --global user.signingkey ~/.ssh/tangled-key
1925```
1926
1927To sign commits using an SSH key with jj, add this to your
1928config:
1929
1930```
1931[signing]
1932behavior = "own"
1933backend = "ssh"
1934key = "~/.ssh/tangled-key"
1935```
1936
1937## Self-hosted knot issues
1938
1939If you need help troubleshooting a self-hosted knot, check
1940out the [knot troubleshooting
1941guide](/knot-self-hosting-guide.html#troubleshooting).