commit e67a3016fbfe981388157519136b59ac8b5d5042 · finxol.io/blog

+37 -19

content/posts/0-draft-embracing-atproto-pt-2-tangled-knot.md content/posts/embracing-atproto-pt-2-tangled-knot.md

···

       1
        
       ---

     

       2
        
       title: "Embracing ATProto, part 2: Tangled Knots and social coding"

     

       3
        
       description: |

     

       4
       -
           You thought Github was a social coding platform? Think again, get ready to tangle!

     

       5
       -
           Built on atproto, tangled allows you to use your Bluesky identity on a (not quite yet) fully feldged git platform!

     

       6
        
       date: 2025-09-15

     

       7
        
       authors:

     

       8
        
         - name: finxol

     

       9
        
       tags:

     

       10
        
         - atproto

     

       11
        
         - self-hosting

     

       12
       -
       published: false

     

       13
        
       ---

     

       14
        
       

     

       15
        
       I recently set up my own atproto PDS, for use with Bluesky and all other atproto apps.

     

       16
       -
       If you already feel lost, check out last week's post where I wuickly explain what atproto is,

     

       17
        
       roughly how it works, and the steps I followed to get my PDS running.

     

       18
        
       

     

       19
        
       ::Bookmark{url="/posts/embracing-atproto-pt-1-hosting-pds"}

     
···

       21
        
       ::

     

       22
        
       

     

       23
        
       The PDS setup and migration was an overall very smooth process.

     

       24
       -
       Bluesky and the AT Protocol are built by a very competent team of well funded engineers working on it for a few years already.

     

       25
        
       

     

       26
        
       ## What's tangled?

     

       27
        
       

     
···

       29
        
       It's a "social-enabled git collaboration platform" built for decentralisation, ownership, and social coding.

     

       30
        
       

     

       31
        
       The platform has gained a lot of traction since, and the community is very much involved in the development, but for now tangled is still in alpha.

     

       32
       -
       That doesn't mean it's not usable yet, just that some things may break.

     

       33
        
       

     

       34
        
       ### What's a Knot?

     

       35
        
       

     

       36
        
       Just like plain atproto, tangled has some lingo of its own.

     

       37
        
       

     

       38
       -
       In tangled, a knot is essentially a git server.

     

       39
       -
       It's sort of like an atproto PDS in the sense that it's where your data—here your code—lives.

     

       40
        
       

     

       41
        
       That's the main tangled-specific decentralised part, and what makes tangled special.

     

       42
       -
       You can keep ownership of your code, without cutting it off from a popular git platform by running it on a private Gitea or Gitlab server.

     

       0
        
       
     

       43
        
       

     

       44
        
       ## Setting up a Knot

     

       45
        
       

     

       46
        
       Setting up my own knot took a little bit more work than for the PDS.

     

       47
       -
       The [official docs](https://tangled.sh/@tangled.sh/core/blob/master/docs/knot-hosting.md) give instructions for installation on a NixOS system.

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       48
        
       

     

       49
        
       ## Spindles & CI

     

       50
        
       

     

       51
        
       Another piece of lingo from the tangled world is "Spindle".

     

       52
        
       

     

       53
        
       A Spindle is a very simple CI runner for tangled.

     

       54
       -
       It runs one Docker container per run, and gives access to any Nixpkg.

     

       55
        
       The syntax is very similar to Github Actions workflow files, with some slight differences.

     

       56
        
       

     

       57
        
       Since it's brand new, there isn't access to the thousands of pre-made reusable Github Actions,

     
···

       76
        
       

     

       77
        
       Migrating the repo over is the simplest things ever.

     

       78
        
       

     

       79
       -
       Just create a new repo on tangled—selecting your knot—set the remote on your local repo, and push to it!

     

       80
       -
       If you specified the knot correctly when creating your repo, it should now live directly on your Knot.

     

       81
        
       

     

       82
        
       <img src="/posts/embracing-atproto-pt2/new-repo.png" alt="Select your new knot when creating a repo" width="80%" style="margin: auto;" />

     

       83
        
       

     

       84
        
       You can now use git just as you normally do!

     

       85
        
       

     

       86
       -
       ### CI

     

       87
        
       

     

       88
        
       Migrating CI takes a tiny bit more work to migrate.

     

       89
        
       I had a Github Action workflow to automatically deploy this blog to Deno Deploy on push.

     
···

       141
        
       ```

     

       142
        
       

     

       143
        
       I'll have a look at branch deploys later.

     

       144
       -
       It needs a bit more manual work since the official GH Action doesn't do it for us.

     

       145
        
       

     

       146
        
       Since spindles work slightly differently to Github Actions runners, we need to give it a list of dependencies to install.

     

       147
        
       It's similar to the setup steps in the GH workflow to install node and pnpm.

     
···

       165
        
       

     

       166
        
       Now we can get to the actual steps of the workflow.

     

       167
        
       

     

       168
       -
       Since we don't have access to the existing Github Actions, there's a few sections that needed adapting or manual work.

     

       169
        
       The install and generate steps are exactly the same, but the deploy step changes.

     

       170
        
       

     

       171
        
       To replace the official Deno Deploy GH Action, we can directly use their `deployctl` cli tool, and give it the appropriate parametres.

     

       172
        
       

     

       173
       -
       I also used this as an excuse to using the `jsr:@std/http/file-server` entrypoint instead of the deno.land url style.

     

       174
        
       

     

       175
        
       ```yaml

     

       176
        
       steps:

     
···

       240
        
       It took me a little bit more time to get things working right.

     

       241
        
       I found a little bug in the tangled UI regarding spindle runs.

     

       242
        
       

     

       243
       -
       When pushing to the official knot, the workflow got picked up fine by the official spindle, and showed up in the UI.

     

       244
       -
       When I pushed to my knot however, the official spindle ran the workflow, but it didn't show in the UI.

     

       245
        
       It took me a while to realise what was going on.

     

       246
        
       

     

       247
        
       I thought the spindle wasn't picking up the workflow, but the bug was simply with showing the info in the UI.

···

---

title: "Embracing ATProto, part 2: Tangled Knots and social coding"

description: |

4
+
You thought Github was a social coding platform? Think again, and get ready to tangle!

5
+
Built on atproto, tangled allows you to use your Bluesky/atproto identity on a (not quite yet) fully feldged git platform!

date: 2025-09-15

authors:

- name: finxol

tags:

- atproto

- self-hosting

12
+
published: true

---

I recently set up my own atproto PDS, for use with Bluesky and all other atproto apps.

16
+
If you already feel lost, check out last week's post where I quickly explain what atproto is,

roughly how it works, and the steps I followed to get my PDS running.

::Bookmark{url="/posts/embracing-atproto-pt-1-hosting-pds"}

···

The PDS setup and migration was an overall very smooth process.

24
+
Bluesky and the AT Protocol are built by a very competent team of well funded engineers who've been working on it for a few years already.

## What's tangled?

···

It's a "social-enabled git collaboration platform" built for decentralisation, ownership, and social coding.

The platform has gained a lot of traction since, and the community is very much involved in the development, but for now tangled is still in alpha.

32
+
That doesn't mean it's not usable yet, simply that some things may break.

### What's a Knot?

Just like plain atproto, tangled has some lingo of its own.

38
+
In tangled, a knot is essentially an atproto-enabled git server.

39
+
It's sort of like a PDS in the sense that it's where your data—here your code—lives.

That's the main tangled-specific decentralised part, and what makes tangled special.

42
+
You can keep ownership of your code, without cutting it off from a popular git platform—which

43
+
is a side effect of running a private Gitea or Gitlab server.

## Setting up a Knot

Setting up my own knot took a little bit more work than for the PDS.

48
+

49
+
The [official docs](https://tangled.sh/@tangled.sh/core/blob/master/docs/knot-hosting.md) give instructions for installation on a NixOS system,

50
+
but I'm not running NixOS on my server.

51
+
Luckily, they also provide a community-maintained [Docker install process](https://tangled.sh/@tangled.sh/knot-docker).

52
+

53
+
At the top of the README that serves as a documentation page, they talk about a pre-built image to use.

54
+
Perfect!

55
+
That's exactly what I'm looking for.

56
+
Just need to spin up the container and we're done!

57
+

58
+
Not quite, unfortunately...

59
+

60
+
I tried that route, added my knot on the tangled UI, but couldn't get it verified.

61
+
I spent way too long trying to debug the parts I control, mainly the Caddy reverse proxy rules.

62
+
It turns out the pre-built image was just out of date, and rebuilding it myself fixed it immediately...

63
+

64
+
Ultimately, setting up a knot isn't all that hard.

65
+
I just ran into a slightly stupid version mismatch problem a closer inspection could've revealed earlier.

## Spindles & CI

Another piece of lingo from the tangled world is "Spindle".

A Spindle is a very simple CI runner for tangled.

72
+
It spins up one Docker container per run, and gives access to any Nixpkg.

The syntax is very similar to Github Actions workflow files, with some slight differences.

Since it's brand new, there isn't access to the thousands of pre-made reusable Github Actions,

···

Migrating the repo over is the simplest things ever.

97
+
Just create a new repo on tangled—making sure to select your knot, set the remote on your local repo, and push to it!

98
+
If you specified the knot correctly when creating your repo, the repo should now live directly on your Knot.

100

101

102

You can now use git just as you normally do!

103

104
+
### CI for auto-deploy

105

106

Migrating CI takes a tiny bit more work to migrate.

107

I had a Github Action workflow to automatically deploy this blog to Deno Deploy on push.

···

159

```

160

161

I'll have a look at branch deploys later.

162
+
It needs a bit more manual work since the official GH Action doesn't handle it for us.

163

164

Since spindles work slightly differently to Github Actions runners, we need to give it a list of dependencies to install.

165

It's similar to the setup steps in the GH workflow to install node and pnpm.

···

183

184

Now we can get to the actual steps of the workflow.

185

186
+
Since we don't have access to the existing Github Actions, there's a couple sections that needed adapting or manual work.

187

The install and generate steps are exactly the same, but the deploy step changes.

188

189

To replace the official Deno Deploy GH Action, we can directly use their `deployctl` cli tool, and give it the appropriate parametres.

190

191
+
I also used this as an excuse to switch to the `jsr:@std/http/file-server` entrypoint instead of the deno.land url style.

192

193

```yaml

194

steps:

···

258

It took me a little bit more time to get things working right.

259

I found a little bug in the tangled UI regarding spindle runs.

260

261
+
When pushing to the *official* knot, the workflow got picked up fine by the official spindle, and showed up in the UI.

262
+
When I pushed to *my* knot however, the official spindle ran the workflow, but it didn't show in the UI.

263

It took me a while to realise what was going on.

264

265

I thought the spindle wasn't picking up the workflow, but the bug was simply with showing the info in the UI.