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