Tangled in a Box #

A working fully private Tangled setup with frontend, bobbin, knot, and all the supporting services like plc, pds, and hydrant, all running locally. This isn't really meant to be used for anything for real, more of a fun experiment, but the setup is mostly functional. This can run fully disconnected from the public internet. It's a bit lackluster without the social features, tbh, but you could use some variation on this to run your own private Tangled on your machine or on a Tailscale private network.

Inspired by https://tangled.org/kandake.africa/atmosphereinabox, although I've put no special effort into ensuring that nothing can leak out.

PS please don't use this as a reference for how to configure your publicly available self-hosted Tangled components. I've got plaintext secrets all over. Look at something like cove.town instead.

Getting started #

Basically I started from the Tranquil dev compose, ripped out traefik for caddy, and then incrementally added stuff that Tangled needed until I could log in, create a repo, and push a commit.

You start it with

docker compose up -d

and it should just do everything automatically, setting up a user etc. To get your OS to trust the certificate and stop complaining

./trust.sh

And then you're ready to log in with dolly.tangled.inabox.at with the password Lewis-Stan1.

open https://tangled.inabox.at

Before you ask, yes, I did buy the domain inabox.at just to create the wildcard record *.tangled.inabox.at pointing at 127.0.0.1.

Undoing it all #

If you want to shut it down and clean up:

docker compose down -v
./trust.sh --undo

Components #

PLC #

As is standard for local atproto dev setups, this runs its own PLC and points all services that care to that PLC. The PLC provides the identities.

PDS #

This uses Tranquil PDS, just like Tangled does in production. Kind of an obvious choice since I'm a maintainer 🙊. The PDS owns the accounts and stores account data like records and blobs, and also acts as the auth server when logging into Tangled. Set up with the postgres DB, although you could switch to the tranquil store, Lewis says it's ready for primetime now.

Hydrant #

Hydrant does the job of the relay in atproto, where it's reading off the PDS subscribeRepos websocket and discovers all the fun new records you're creating. Other services can then /stream or /subscribe to get updates, at which points it relays the data. Hydrant can run in proper relay mode too, but nothing here uses it.

Knot #

The knot is the git repo server component in the Tangled ecosystem, so this is where your repos live. It's also a PDS nowadays, using git COBs to store issues and PRs. Neat.

Bobbin #

This is the "API server" of Tangled, the thing the frontend queries to get the data it needs to render pages. On startup it backfills from hydrant to ensure all the juicy records are available.

Frontend #

Not sure why I'm writing all this stuff really, it was just a fun idea that I for some reason have already invested way too much time in and I even bought a domain name, sigh. But it's the svelte frontend app, I guess.

Contributions #

You're very welcome to contribute with issues and PRs. I would just ask you that for PR descriptions, comments, and commit messages, that you write them yourself.

Gotchas #

• The knot is configured to use port 22, if you're already running something there you'll want to change the port in config.
• The Tangled sign up link doesn't work.
• After docker compose down -v tears everything down, if you start it up again you need to run ./trust.sh again.
• The web image bundles the domain it runs on. If you want to run it on a different domain, you need to rebuild the image.
• You can't sign up through the Tangled frontend, you have to create accounts on pds.tangled.inabox.at separately. They still function as normal accounts.