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