forked from
tangled.org/core
Monorepo for Tangled
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_PIPELINES_NIXERY`: The Nixery URL (default: `"nixery.tangled.sh"`).
971- `SPINDLE_PIPELINES_WORKFLOW_TIMEOUT`: The default workflow timeout (default: `"5m"`).
972
973### Running spindle
974
9751. **Set the environment variables.** For example:
976
977 ```shell
978 export SPINDLE_SERVER_HOSTNAME="your-hostname"
979 export SPINDLE_SERVER_OWNER="your-did"
980 ```
981
9822. **Build the Spindle binary.**
983
984 ```shell
985 cd core
986 go mod download
987 go build -o cmd/spindle/spindle cmd/spindle/main.go
988 ```
989
9903. **Create the log directory.**
991
992 ```shell
993 sudo mkdir -p /var/log/spindle
994 sudo chown $USER:$USER -R /var/log/spindle
995 ```
996
9974. **Run the Spindle binary.**
998
999 ```shell
1000 ./cmd/spindle/spindle
1001 ```
1002
1003Spindle will now start, connect to the Jetstream server, and begin processing pipelines.
1004
1005## Architecture
1006
1007Spindle is a small CI runner service. Here's a high-level overview of how it operates:
1008
1009- Listens for [`sh.tangled.spindle.member`](/lexicons/spindle/member.json) and
1010 [`sh.tangled.repo`](/lexicons/repo.json) records on the Jetstream.
1011- When a new repo record comes through (typically when you add a spindle to a
1012 repo from the settings), spindle then resolves the underlying knot and
1013 subscribes to repo events (see:
1014 [`sh.tangled.pipeline`](/lexicons/pipeline.json)).
1015- The spindle engine then handles execution of the pipeline, with results and
1016 logs beamed on the spindle event stream over WebSocket
1017
1018### The engine
1019
1020At present, the only supported backend is Docker (and Podman, if Docker
1021compatibility is enabled, so that `/run/docker.sock` is created). spindle
1022executes each step in the pipeline in a fresh container, with state persisted
1023across steps within the `/tangled/workspace` directory.
1024
1025The base image for the container is constructed on the fly using
1026[Nixery](https://nixery.dev), which is handy for caching layers for frequently
1027used packages.
1028
1029The pipeline manifest is [specified here](https://docs.tangled.org/spindles.html#pipelines).
1030
1031## Secrets with openbao
1032
1033This document covers setting up spindle to use OpenBao for secrets
1034management via OpenBao Proxy instead of the default SQLite backend.
1035
1036### Overview
1037
1038Spindle now uses OpenBao Proxy for secrets management. The proxy handles
1039authentication automatically using AppRole credentials, while spindle
1040connects to the local proxy instead of directly to the OpenBao server.
1041
1042This approach provides better security, automatic token renewal, and
1043simplified application code.
1044
1045### Installation
1046
1047Install OpenBao from Nixpkgs:
1048
1049```bash
1050nix shell nixpkgs#openbao # for a local server
1051```
1052
1053### Setup
1054
1055The setup process can is documented for both local development and production.
1056
1057#### Local development
1058
1059Start OpenBao in dev mode:
1060
1061```bash
1062bao server -dev -dev-root-token-id="root" -dev-listen-address=127.0.0.1:8201
1063```
1064
1065This starts OpenBao on `http://localhost:8201` with a root token.
1066
1067Set up environment for bao CLI:
1068
1069```bash
1070export BAO_ADDR=http://localhost:8200
1071export BAO_TOKEN=root
1072```
1073
1074#### Production
1075
1076You would typically use a systemd service with a
1077configuration file. Refer to
1078[@tangled.org/infra](https://tangled.org/@tangled.org/infra)
1079for how this can be achieved using Nix.
1080
1081Then, initialize the bao server:
1082
1083```bash
1084bao operator init -key-shares=1 -key-threshold=1
1085```
1086
1087This will print out an unseal key and a root key. Save them
1088somewhere (like a password manager). Then unseal the vault
1089to begin setting it up:
1090
1091```bash
1092bao operator unseal <unseal_key>
1093```
1094
1095All steps below remain the same across both dev and
1096production setups.
1097
1098#### Configure openbao server
1099
1100Create the spindle KV mount:
1101
1102```bash
1103bao secrets enable -path=spindle -version=2 kv
1104```
1105
1106Set up AppRole authentication and policy:
1107
1108Create a policy file `spindle-policy.hcl`:
1109
1110```hcl
1111# Full access to spindle KV v2 data
1112path "spindle/data/*" {
1113 capabilities = ["create", "read", "update", "delete"]
1114}
1115
1116# Access to metadata for listing and management
1117path "spindle/metadata/*" {
1118 capabilities = ["list", "read", "delete", "update"]
1119}
1120
1121# Allow listing at root level
1122path "spindle/" {
1123 capabilities = ["list"]
1124}
1125
1126# Required for connection testing and health checks
1127path "auth/token/lookup-self" {
1128 capabilities = ["read"]
1129}
1130```
1131
1132Apply the policy and create an AppRole:
1133
1134```bash
1135bao policy write spindle-policy spindle-policy.hcl
1136bao auth enable approle
1137bao write auth/approle/role/spindle \
1138 token_policies="spindle-policy" \
1139 token_ttl=1h \
1140 token_max_ttl=4h \
1141 bind_secret_id=true \
1142 secret_id_ttl=0 \
1143 secret_id_num_uses=0
1144```
1145
1146Get the credentials:
1147
1148```bash
1149# Get role ID (static)
1150ROLE_ID=$(bao read -field=role_id auth/approle/role/spindle/role-id)
1151
1152# Generate secret ID
1153SECRET_ID=$(bao write -f -field=secret_id auth/approle/role/spindle/secret-id)
1154
1155echo "Role ID: $ROLE_ID"
1156echo "Secret ID: $SECRET_ID"
1157```
1158
1159#### Create proxy configuration
1160
1161Create the credential files:
1162
1163```bash
1164# Create directory for OpenBao files
1165mkdir -p /tmp/openbao
1166
1167# Save credentials
1168echo "$ROLE_ID" > /tmp/openbao/role-id
1169echo "$SECRET_ID" > /tmp/openbao/secret-id
1170chmod 600 /tmp/openbao/role-id /tmp/openbao/secret-id
1171```
1172
1173Create a proxy configuration file `/tmp/openbao/proxy.hcl`:
1174
1175```hcl
1176# OpenBao server connection
1177vault {
1178 address = "http://localhost:8200"
1179}
1180
1181# Auto-Auth using AppRole
1182auto_auth {
1183 method "approle" {
1184 mount_path = "auth/approle"
1185 config = {
1186 role_id_file_path = "/tmp/openbao/role-id"
1187 secret_id_file_path = "/tmp/openbao/secret-id"
1188 }
1189 }
1190
1191 # Optional: write token to file for debugging
1192 sink "file" {
1193 config = {
1194 path = "/tmp/openbao/token"
1195 mode = 0640
1196 }
1197 }
1198}
1199
1200# Proxy listener for spindle
1201listener "tcp" {
1202 address = "127.0.0.1:8201"
1203 tls_disable = true
1204}
1205
1206# Enable API proxy with auto-auth token
1207api_proxy {
1208 use_auto_auth_token = true
1209}
1210
1211# Enable response caching
1212cache {
1213 use_auto_auth_token = true
1214}
1215
1216# Logging
1217log_level = "info"
1218```
1219
1220#### Start the proxy
1221
1222Start OpenBao Proxy:
1223
1224```bash
1225bao proxy -config=/tmp/openbao/proxy.hcl
1226```
1227
1228The proxy will authenticate with OpenBao and start listening on
1229`127.0.0.1:8201`.
1230
1231#### Configure spindle
1232
1233Set these environment variables for spindle:
1234
1235```bash
1236export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
1237export SPINDLE_SERVER_SECRETS_OPENBAO_PROXY_ADDR=http://127.0.0.1:8201
1238export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
1239```
1240
1241On startup, spindle will now connect to the local proxy,
1242which handles all authentication automatically.
1243
1244### Production setup for proxy
1245
1246For production, you'll want to run the proxy as a service:
1247
1248Place your production configuration in
1249`/etc/openbao/proxy.hcl` with proper TLS settings for the
1250vault connection.
1251
1252### Verifying setup
1253
1254Test the proxy directly:
1255
1256```bash
1257# Check proxy health
1258curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/sys/health
1259
1260# Test token lookup through proxy
1261curl -H "X-Vault-Request: true" http://127.0.0.1:8201/v1/auth/token/lookup-self
1262```
1263
1264Test OpenBao operations through the server:
1265
1266```bash
1267# List all secrets
1268bao kv list spindle/
1269
1270# Add a test secret via the spindle API, then check it exists
1271bao kv list spindle/repos/
1272
1273# Get a specific secret
1274bao kv get spindle/repos/your_repo_path/SECRET_NAME
1275```
1276
1277### How it works
1278
1279- Spindle connects to OpenBao Proxy on localhost (typically
1280 port 8200 or 8201)
1281- The proxy authenticates with OpenBao using AppRole
1282 credentials
1283- All spindle requests go through the proxy, which injects
1284 authentication tokens
1285- Secrets are stored at
1286 `spindle/repos/{sanitized_repo_path}/{secret_key}`
1287- Repository paths like `did:plc:alice/myrepo` become
1288 `did_plc_alice_myrepo`
1289- The proxy handles all token renewal automatically
1290- Spindle no longer manages tokens or authentication
1291 directly
1292
1293### Troubleshooting
1294
1295**Connection refused**: Check that the OpenBao Proxy is
1296running and listening on the configured address.
1297
1298**403 errors**: Verify the AppRole credentials are correct
1299and the policy has the necessary permissions.
1300
1301**404 route errors**: The spindle KV mount probably doesn't
1302exist—run the mount creation step again.
1303
1304**Proxy authentication failures**: Check the proxy logs and
1305verify the role-id and secret-id files are readable and
1306contain valid credentials.
1307
1308**Secret not found after writing**: This can indicate policy
1309permission issues. Verify the policy includes both
1310`spindle/data/*` and `spindle/metadata/*` paths with
1311appropriate capabilities.
1312
1313Check proxy logs:
1314
1315```bash
1316# If running as systemd service
1317journalctl -u openbao-proxy -f
1318
1319# If running directly, check the console output
1320```
1321
1322Test AppRole authentication manually:
1323
1324```bash
1325bao write auth/approle/login \
1326 role_id="$(cat /tmp/openbao/role-id)" \
1327 secret_id="$(cat /tmp/openbao/secret-id)"
1328```
1329
1330# Webhooks
1331
1332Webhooks 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.
1333
1334## Overview
1335
1336Webhooks send HTTP POST requests to URLs you configure whenever specific events happen. Currently, Tangled supports push events, with more event types coming soon.
1337
1338## Configuring webhooks
1339
1340To set up a webhook for your repository:
1341
13421. Navigate to your repository
13432. Go to **Settings → Hooks**
13443. Click **new webhook**
13454. Configure your webhook:
1346 - **Payload URL**: The endpoint that will receive the webhook POST requests
1347 - **Secret**: An optional secret key for verifying webhook authenticity (leave blank to send unsigned webhooks)
1348 - **Events**: Select which events trigger the webhook (currently only push events)
1349 - **Active**: Toggle whether the webhook is enabled
1350
1351## Webhook payload
1352
1353### Push
1354
1355When a push event occurs, Tangled sends a POST request with a JSON payload of the format:
1356
1357```json
1358{
1359 "after": "7b320e5cbee2734071e4310c1d9ae401d8f6cab5",
1360 "before": "c04ddf64eddc90e4e2a9846ba3b43e67a0e2865e",
1361 "pusher": {
1362 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq"
1363 },
1364 "ref": "refs/heads/main",
1365 "repository": {
1366 "clone_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1367 "created_at": "2025-09-15T08:57:23Z",
1368 "description": "an example repository",
1369 "fork": false,
1370 "full_name": "did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1371 "html_url": "https://tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1372 "name": "some-repo",
1373 "open_issues_count": 5,
1374 "owner": {
1375 "did": "did:plc:hwevmowznbiukdf6uk5dwrrq"
1376 },
1377 "ssh_url": "ssh://git@tangled.org/did:plc:hwevmowznbiukdf6uk5dwrrq/some-repo",
1378 "stars_count": 1,
1379 "updated_at": "2025-09-15T08:57:23Z"
1380 }
1381}
1382```
1383
1384## HTTP headers
1385
1386Each webhook request includes the following headers:
1387
1388- `Content-Type: application/json`
1389- `User-Agent: Tangled-Hook/<short-sha>` — User agent with short SHA of the commit
1390- `X-Tangled-Event: push` — The event type
1391- `X-Tangled-Hook-ID: <webhook-id>` — The webhook ID
1392- `X-Tangled-Delivery: <uuid>` — Unique delivery ID
1393- `X-Tangled-Signature-256: sha256=<hmac>` — HMAC-SHA256 signature (if secret configured)
1394
1395## Verifying webhook signatures
1396
1397If you configured a secret, you should verify the webhook signature to ensure requests are authentic. For example, in Go:
1398
1399```go
1400package main
1401
1402import (
1403 "crypto/hmac"
1404 "crypto/sha256"
1405 "encoding/hex"
1406 "io"
1407 "net/http"
1408 "strings"
1409)
1410
1411func verifySignature(payload []byte, signatureHeader, secret string) bool {
1412 // Remove 'sha256=' prefix from signature header
1413 signature := strings.TrimPrefix(signatureHeader, "sha256=")
1414
1415 // Compute expected signature
1416 mac := hmac.New(sha256.New, []byte(secret))
1417 mac.Write(payload)
1418 expected := hex.EncodeToString(mac.Sum(nil))
1419
1420 // Use constant-time comparison to prevent timing attacks
1421 return hmac.Equal([]byte(signature), []byte(expected))
1422}
1423
1424func webhookHandler(w http.ResponseWriter, r *http.Request) {
1425 // Read the request body
1426 payload, err := io.ReadAll(r.Body)
1427 if err != nil {
1428 http.Error(w, "Bad request", http.StatusBadRequest)
1429 return
1430 }
1431
1432 // Get signature from header
1433 signatureHeader := r.Header.Get("X-Tangled-Signature-256")
1434
1435 // Verify signature
1436 if signatureHeader != "" && verifySignature(payload, signatureHeader, yourSecret) {
1437 // Webhook is authentic, process it
1438 processWebhook(payload)
1439 w.WriteHeader(http.StatusOK)
1440 } else {
1441 http.Error(w, "Invalid signature", http.StatusUnauthorized)
1442 }
1443}
1444```
1445
1446## Delivery retries
1447
1448Webhooks are automatically retried on failure:
1449
1450- **3 total attempts** (1 initial + 2 retries)
1451- **Exponential backoff** starting at 1 second, max 10 seconds
1452- **Retried on**:
1453 - Network errors
1454 - HTTP 5xx server errors
1455- **Not retried on**:
1456 - HTTP 4xx client errors (bad request, unauthorized, etc.)
1457
1458### Timeouts
1459
1460Webhook requests timeout after 30 seconds. If your endpoint needs more time:
1461
14621. Respond with 200 OK immediately
14632. Process the webhook asynchronously in the background
1464
1465## Example integrations
1466
1467### Discord notifications
1468
1469```javascript
1470app.post("/webhook", (req, res) => {
1471 const payload = req.body;
1472
1473 fetch("https://discord.com/api/webhooks/...", {
1474 method: "POST",
1475 headers: { "Content-Type": "application/json" },
1476 body: JSON.stringify({
1477 content: `New push to ${payload.repository.full_name}`,
1478 embeds: [
1479 {
1480 title: `${payload.pusher.did} pushed to ${payload.ref}`,
1481 url: payload.repository.html_url,
1482 color: 0x00ff00,
1483 },
1484 ],
1485 }),
1486 });
1487
1488 res.status(200).send("OK");
1489});
1490```
1491
1492# Migrating knots and spindles
1493
1494Sometimes, non-backwards compatible changes are made to the
1495knot/spindle XRPC APIs. If you host a knot or a spindle, you
1496will need to follow this guide to upgrade. Typically, this
1497only requires you to deploy the newest version.
1498
1499This document is laid out in reverse-chronological order.
1500Newer migration guides are listed first, and older guides
1501are further down the page.
1502
1503## Upgrading to v1.14.0-alpha
1504
1505Starting with v1.14.0-alpha, the fully knot uses the repoDID as its
1506canonical handle for repositories. This unlocks repository
1507renames from the appview UI and changes the wire format for
1508the following lexicons (`sh.tangled.repo.pull`, `sh.tangled.repo.collaborator`,
1509`sh.tangled.repo.issue`, `sh.tangled.git.refUpdate`).
1510
1511Knots that have not been upgraded may silently drop new push
1512events, pull requests, issues, and collaborator invites for
1513repositories they host until upgraded. So upgrade please!!!
1514
1515- Upgrade to the latest tag (v1.14.0 or above)
1516- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1517 hit the "retry" button to verify your knot
1518
1519## Upgrading to v1.13.0-alpha
1520
1521Starting with v1.13.0-alpha, every repository on a knot is
1522assigned a DID. This makes repositories stable across
1523renames and transfers.
1524
1525When you upgrade your knot to this version, the server will
1526automatically mint DIDs for all existing repositories on
1527startup. This is a one-time process and you may see
1528additional log output during the first boot as DIDs are
1529assigned.
1530
1531- Upgrade to the latest tag (v1.13.0 or above)
1532- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1533 hit the "retry" button to verify your knot
1534
1535## Upgrading from v1.8.x
1536
1537After v1.8.2, the HTTP API for knots and spindles has been
1538deprecated and replaced with XRPC. Repositories on outdated
1539knots will not be viewable from the appview. Upgrading is
1540straightforward however.
1541
1542For knots:
1543
1544- Upgrade to the latest tag (v1.9.0 or above)
1545- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1546 hit the "retry" button to verify your knot
1547
1548For spindles:
1549
1550- Upgrade to the latest tag (v1.9.0 or above)
1551- Head to the [spindle
1552 dashboard](https://tangled.org/settings/spindles) and hit the
1553 "retry" button to verify your spindle
1554
1555## Upgrading from v1.7.x
1556
1557After v1.7.0, knot secrets have been deprecated. You no
1558longer need a secret from the appview to run a knot. All
1559authorized commands to knots are managed via [Inter-Service
1560Authentication](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
1561Knots will be read-only until upgraded.
1562
1563Upgrading is quite easy, in essence:
1564
1565- `KNOT_SERVER_SECRET` is no more, you can remove this
1566 environment variable entirely
1567- `KNOT_SERVER_OWNER` is now required on boot, set this to
1568 your DID. You can find your DID in the
1569 [settings](https://tangled.org/settings) page.
1570- Restart your knot once you have replaced the environment
1571 variable
1572- Head to the [knot dashboard](https://tangled.org/settings/knots) and
1573 hit the "retry" button to verify your knot. This simply
1574 writes a `sh.tangled.knot` record to your PDS.
1575
1576If you use the nix module, simply bump the flake to the
1577latest revision, and change your config block like so:
1578
1579```diff
1580 services.tangled.knot = {
1581 enable = true;
1582 server = {
1583- secretFile = /path/to/secret;
1584+ owner = "did:plc:foo";
1585 };
1586 };
1587```
1588
1589# Hacking on Tangled
1590
1591We highly recommend [installing
1592Nix](https://nixos.org/download/) (the package manager)
1593before working on the codebase. The Nix flake provides a lot
1594of helpers to get started and most importantly, builds and
1595dev shells are entirely deterministic.
1596
1597To set up your dev environment:
1598
1599```bash
1600nix develop
1601```
1602
1603Non-Nix users can look at the `devShell` attribute in the
1604`flake.nix` file to determine necessary dependencies.
1605
1606## Running the appview
1607
1608The appview requires Redis and OAuth JWKs. Start these
1609first, before launching the appview itself.
1610
1611```bash
1612# OAuth JWKs should already be set up by the Nix devshell:
1613echo $TANGLED_OAUTH_CLIENT_SECRET
1614z42ty4RT1ovnTopY8B8ekz9NuziF2CuMkZ7rbRFpAR9jBqMc
1615
1616echo $TANGLED_OAUTH_CLIENT_KID
16171761667908
1618
1619# if not, you can set it up yourself:
1620goat key generate -t P-256
1621Key Type: P-256 / secp256r1 / ES256 private key
1622Secret Key (Multibase Syntax): save this securely (eg, add to password manager)
1623 z42tuPDKRfM2mz2Kv953ARen2jmrPA8S9LX9tRq4RVcUMwwL
1624Public Key (DID Key Syntax): share or publish this (eg, in DID document)
1625 did:key:zDnaeUBxtG6Xuv3ATJE4GaWeyXM3jyamJsZw3bSPpxx4bNXDR
1626
1627# the secret key from above
1628export TANGLED_OAUTH_CLIENT_SECRET="z42tuP..."
1629
1630# Run Redis in a new shell to store OAuth sessions
1631redis-server
1632```
1633
1634The Nix flake exposes a few `app` attributes (run `nix
1635flake show` to see a full list of what the flake provides),
1636one of the apps runs the appview with the `air`
1637live-reloader:
1638
1639```bash
1640TANGLED_DEV=true nix run .#watch-appview
1641
1642# TANGLED_DB_PATH might be of interest to point to
1643# different sqlite DBs
1644
1645# in a separate shell, you can live-reload tailwind
1646nix run .#watch-tailwind
1647```
1648
1649## Running knots and spindles
1650
1651An end-to-end knot setup requires setting up a machine with
1652`sshd`, `AuthorizedKeysCommand`, and a Git user, which is
1653quite cumbersome. So the Nix flake provides a
1654`nixosConfiguration` to do so.
1655
1656<details>
1657 <summary><strong>macOS users will have to set up a Nix Builder first</strong></summary>
1658
1659In order to build Tangled's dev VM on macOS, you will
1660first need to set up a Linux Nix builder. The recommended
1661way to do so is to run a [`darwin.linux-builder`
1662VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)
1663and to register it in `nix.conf` as a builder for Linux
1664with the same architecture as your Mac (`linux-aarch64` if
1665you are using Apple Silicon).
1666
1667> IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside
1668> the Tangled repo so that it doesn't conflict with the other VM. For example,
1669> you can do
1670>
1671> ```shell
1672> cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder
1673> ```
1674>
1675> to store the builder VM in a temporary dir.
1676>
1677> You should read and follow [all the other instructions][darwin builder vm] to
1678> avoid subtle problems.
1679
1680Alternatively, you can use any other method to set up a
1681Linux machine with Nix installed that you can `sudo ssh`
1682into (in other words, root user on your Mac has to be able
1683to ssh into the Linux machine without entering a password)
1684and that has the same architecture as your Mac. See
1685[remote builder
1686instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)
1687for how to register such a builder in `nix.conf`.
1688
1689> WARNING: If you'd like to use
1690> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
1691> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
1692ssh` works can be tricky. It seems to be [possible with
1693> Orbstack](https://github.com/orgs/orbstack/discussions/1669).
1694
1695</details>
1696
1697To begin, grab your DID from http://localhost:3000/settings.
1698Then, set `TANGLED_VM_KNOT_OWNER` and
1699`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a
1700lightweight NixOS VM like so:
1701
1702```bash
1703nix run --impure .#vm
1704
1705# type `poweroff` at the shell to exit the VM
1706```
1707
1708This starts a knot on port 6444, a spindle on port 6555
1709with `ssh` exposed on port 2222.
1710
1711Once the services are running, head to
1712http://localhost:3000/settings/knots and hit "Verify". It should
1713verify the ownership of the services instantly if everything
1714went smoothly.
1715
1716You can push repositories to this VM with this ssh config
1717block on your main machine:
1718
1719```bash
1720Host nixos-shell
1721 Hostname localhost
1722 Port 2222
1723 User git
1724 IdentityFile ~/.ssh/my_tangled_key
1725```
1726
1727Set up a remote called `local-dev` on a git repo:
1728
1729```bash
1730git remote add local-dev git@nixos-shell:user/repo
1731git push local-dev main
1732```
1733
1734The above VM should already be running a spindle on
1735`localhost:6555`. Head to http://localhost:3000/settings/spindles and
1736hit "Verify". You can then configure each repository to use
1737this spindle and run CI jobs.
1738
1739Of interest when debugging spindles:
1740
1741```
1742# Service logs from journald:
1743journalctl -xeu spindle
1744
1745# CI job logs from disk:
1746ls /var/log/spindle
1747
1748# Debugging spindle database:
1749sqlite3 /var/lib/spindle/spindle.db
1750
1751# litecli has a nicer REPL interface:
1752litecli /var/lib/spindle/spindle.db
1753```
1754
1755If for any reason you wish to disable either one of the
1756services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set
1757`services.tangled.spindle.enable` (or
1758`services.tangled.knot.enable`) to `false`.
1759
1760# Contribution guide
1761
1762## Commit guidelines
1763
1764We follow a commit style similar to the Go project. Please keep commits:
1765
1766- **atomic**: each commit should represent one logical change
1767- **descriptive**: the commit message should clearly describe what the
1768 change does and why it's needed
1769
1770### Message format
1771
1772```
1773<service/top-level directory>/<affected package/directory>: <short summary of change>
1774
1775Optional longer description can go here, if necessary. Explain what the
1776change does and why, especially if not obvious. Reference relevant
1777issues or PRs when applicable. These can be links for now since we don't
1778auto-link issues/PRs yet.
1779```
1780
1781Here are some examples:
1782
1783```
1784appview/state: fix token expiry check in middleware
1785
1786The previous check did not account for clock drift, leading to premature
1787token invalidation.
1788```
1789
1790```
1791knotserver/git/service: improve error checking in upload-pack
1792```
1793
1794### General notes
1795
1796- PRs get merged "as-is" (fast-forward)—like applying a patch-series
1797 using `git am`. At present, there is no squashing—so please author
1798 your commits as they would appear on `master`, following the above
1799 guidelines.
1800- If there is a lot of nesting, for example "appview:
1801 pages/templates/repo/fragments: ...", these can be truncated down to
1802 just "appview: repo/fragments: ...". If the change affects a lot of
1803 subdirectories, you may abbreviate to just the top-level names, e.g.
1804 "appview: ..." or "knotserver: ...".
1805- Keep commits lowercased with no trailing period.
1806- Use the imperative mood in the summary line (e.g., "fix bug" not
1807 "fixed bug" or "fixes bug").
1808- Try to keep the summary line under 72 characters, but we aren't too
1809 fussed about this.
1810- Follow the same formatting for PR titles if filled manually.
1811- Don't include unrelated changes in the same commit.
1812- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
1813 before submitting if necessary.
1814
1815## Code formatting
1816
1817We use a variety of tools to format our code, and multiplex them with
1818[`treefmt`](https://treefmt.com). All you need to do to format your changes
1819is run `nix run .#fmt` (or just `treefmt` if you're in the devshell).
1820
1821## Proposals for bigger changes
1822
1823Small fixes like typos, minor bugs, or trivial refactors can be
1824submitted directly as PRs.
1825
1826For larger changes—especially those introducing new features, significant
1827refactoring, or altering system behavior—please open a proposal first. This
1828helps us evaluate the scope, design, and potential impact before implementation.
1829
1830Create a new issue titled:
1831
1832```
1833proposal: <affected scope>: <summary of change>
1834```
1835
1836In the description, explain:
1837
1838- What the change is
1839- Why it's needed
1840- How you plan to implement it (roughly)
1841- Any open questions or tradeoffs
1842
1843We'll use the issue thread to discuss and refine the idea before moving
1844forward.
1845
1846## Developer Certificate of Origin (DCO)
1847
1848We require all contributors to certify that they have the right to
1849submit the code they're contributing. To do this, we follow the
1850[Developer Certificate of Origin
1851(DCO)](https://developercertificate.org/).
1852
1853By signing your commits, you're stating that the contribution is your
1854own work, or that you have the right to submit it under the project's
1855license. This helps us keep things clean and legally sound.
1856
1857To sign your commit, just add the `-s` flag when committing:
1858
1859```sh
1860git commit -s -m "your commit message"
1861```
1862
1863This appends a line like:
1864
1865```
1866Signed-off-by: Your Name <your.email@example.com>
1867```
1868
1869We won't merge commits if they aren't signed off. If you forget, you can
1870amend the last commit like this:
1871
1872```sh
1873git commit --amend -s
1874```
1875
1876If you're submitting a PR with multiple commits, make sure each one is
1877signed.
1878
1879For [jj](https://jj-vcs.github.io/jj/latest/) users, you can run the following command
1880to make it sign off commits in the tangled repo:
1881
1882```shell
1883# Safety check, should say "No matching config key..."
1884jj config list templates.commit_trailers
1885# The command below may need to be adjusted if the command above returned something.
1886jj config set --repo templates.commit_trailers "format_signed_off_by_trailer(self)"
1887```
1888
1889Refer to the [jujutsu
1890documentation](https://jj-vcs.github.io/jj/latest/config/#commit-trailers)
1891for more information.
1892
1893# Troubleshooting guide
1894
1895## Login issues
1896
1897Owing to the distributed nature of OAuth on AT Protocol, you
1898may run into issues with logging in. If you run a
1899self-hosted PDS:
1900
1901- You may need to ensure that your PDS is timesynced using
1902 NTP:
1903 - Enable the `ntpd` service
1904 - Run `ntpd -qg` to synchronize your clock
1905- You may need to increase the default request timeout:
1906 `NODE_OPTIONS="--network-family-autoselection-attempt-timeout=500"`
1907
1908## Empty punchcard
1909
1910For Tangled to register commits that you make across the
1911network, you need to setup one of following:
1912
1913- The committer email should be a verified email associated
1914 to your account. You can add and verify emails on the
1915 settings page.
1916- Or, the committer email should be set to your account's
1917 DID: `git config user.email "did:plc:foobar"`. You can find
1918 your account's DID on the settings page
1919
1920## Commit is not marked as verified
1921
1922Presently, Tangled only supports SSH commit signatures.
1923
1924To sign commits using an SSH key with git:
1925
1926```
1927git config --global gpg.format ssh
1928git config --global user.signingkey ~/.ssh/tangled-key
1929```
1930
1931To sign commits using an SSH key with jj, add this to your
1932config:
1933
1934```
1935[signing]
1936behavior = "own"
1937backend = "ssh"
1938key = "~/.ssh/tangled-key"
1939```
1940
1941## Self-hosted knot issues
1942
1943If you need help troubleshooting a self-hosted knot, check
1944out the [knot troubleshooting
1945guide](/knot-self-hosting-guide.html#troubleshooting).