foxwitch.net
forked from
tranquil.farm/tranquil-pds
Our Personal Data Server from scratch!
5.3 kB
108 lines
1# Tranquil PDS
2
3A Personal Data Server for the AT Protocol.
4
5"A what for the what?" -> glad you asked: Bluesky, Tangled, and a bunch of other web applications use a federated protocol called AT Protocol (atproto). Your account lives on a PDS, a server that stores your posts, profile, follows, cryptographic keys, et cetera. The beauty is that a PDS is the *only* place your data lives permanently - so you can navigate any atproto app knowing that your data is yours and not getting locked behind any one app's walls.
6
7We came together to make this PDS to enable and empower our users to better host their data on this shared protocol. All of our decisions as a project are guided by their usefulness to the community: PDS hosters and end-users both.
8
9Comparatively: Bluesky the company created a "reference PDS" that we can self-host quite easily, and that's great, but Bluesky has an incentive to make software for themselves first & foremost, then secondly their software can be useful for us self-hosters. In contrast, Tranquil is not from a company, and will never be.
10
11## What's different about Tranquil PDS
12
13It is a superset of the reference PDS, including:
14- passkeys and 2FA: WebAuthn/FIDO2, TOTP, backup codes, trusted devices
15- SSO login and signup
16- did:web support: PDS-hosted subdomains or bring-your-own
17- multi-channel communication: you can be notified via email, discord, telegram, and signal for verification and alerts
18- granular OAuth scopes with a consent UI that allows unchecking specific scopes
19- app passwords with the same granular permission scope system as OAuth
20- account delegation: letting others manage an account with configurable permission levels
21- a built-in web UI for account management, repo browsing, and admin
22
23Unlike the ref PDS, Tranquil is a single binary with no nodejs runtime. That said, at time of writing, Tranquil does require postgres running separately.
24
25## Quick Start
26
27```bash
28cp example.toml config.toml
29podman compose up db -d
30just run
31```
32
33## Configuration
34
35See `example.toml` for all configuration options.
36
37> [!NOTE]
38> The order of configuration precedence is: environment variables, then a config file passed via `--config`, then `/etc/tranquil-pds/config.toml`, then the built-in defaults. So you can use environment variables, or a config file, or both.
39
40## Development
41
42Run `just` to see available commands.
43
44```bash
45just test
46just lint
47```
48
49Nix users can enter a devshell with `nix develop`, or `direnv allow` to auto-enter via the bundled `.envrc`. Pre-built artifacts including the devshell are available from our [binary cache](docs/2_INSTALL_NIX.md#binary-cache).
50
51## Production Deployment
52
53### Quick Deploy (Docker/Podman Compose)
54
55`docker-compose.prod.yaml` pulls the prebuilt image `atcr.io/tranquil.farm/tranquil-pds:latest`. Sign in to the registry first with `podman login atcr.io`. The Containers guide covers building from source.
56
57```bash
58cp example.toml config.toml
59```
60
61Edit `config.toml` with your values and generate secrets with `openssl rand -base64 48`. Set the postgres password to match `docker-compose.prod.yaml`. nginx needs a TLS certificate before it starts, so follow the wildcard cert steps in the [Containers guide](docs/2_INSTALL_CONTAINERS.md).
62
63```bash
64podman-compose -f docker-compose.prod.yaml up -d
65```
66
67### Installation Guides
68
69- [Nix](docs/2_INSTALL_NIX.md)
70- [Containers](docs/2_INSTALL_CONTAINERS.md)
71
72## Community
73
74### "Let's connect!" or whatever linkedin-types say
75
76We currently don't have a shared space to chat and organize Tranquil things, but we're very interested in changing that in the near future. What do you suggest? Anything but a discord server.
77
78### Core team
79
80- [@oyster.cafe](https://tangled.org/did:plc:3fwecdnvtcscjnrx2p4n7alz)
81- [@nel.pet](https://tangled.org/did:plc:h5wsnqetncv6lu2weom35lg2)
82
83### Amazing contributors
84
85- [@isabelroses.com](https://tangled.org/did:plc:qxichs7jsycphrsmbujwqbfb)
86- [@quilling.dev](https://tangled.org/did:plc:jrtgsidnmxaen4offglr5lsh)
87- [@koi.rip](https://tangled.org/did:plc:b26ewgkrnx3yvsp2cdao3ntu)
88- [@bas.sh](https://tangled.org/did:plc:c52wep6lj4sfbsqiz3yvb55h)
89- [@nekomimi.pet](https://tangled.org/did:plc:ttdrpj45ibqunmfhdsb4zdwq)
90- [@islacant.win](https://tangled.org/did:plc:aut6evcs6d6ngaunqgfhdzzu)
91- [@a.starrysky.fyi](https://tangled.org/did:plc:uuyqs6y3pwtbteet4swt5i5y)
92- [@sans-self.org](https://tangled.org/did:plc:wydyrngmxbcsqdvhmd7whmye)
93- [@tachyonism.tngl.sh](https://tangled.org/did:plc:w6qiwij62bmdugsd3gemhpy2)
94- [@trezy.codes](https://tangled.org/did:plc:4jrld6fwpnwqehtce56qshzv)
95- Could be your name here too!
96
97### Tranquil PDS instances in the wild!
98
99- [Tranquil Farm](https://tranquil.farm)
100- Your instance here!! Don't be a stranger.
101
102### Special thanks
103
104This project is very grateful to [@nonbinary.computer](https://tangled.org/did:plc:yfvwmnlztr4dwkb7hwz55r2g), [@juliet.paris](https://tangled.org/did:plc:hs3aly5l26pozymy4b6hz7ae), [@mary.my.id](https://tangled.org/did:plc:ia76kvnndjutgedggx2ibrem), [@baileytownsend.dev](https://tangled.org/did:plc:rnpkyqnmsw4ipey6eotbdnnf), and [@ptr.pet](https://tangled.org/did:plc:dfl62fgb7wtjj3fcbb72naae) for their help and their code to lean on.
105
106## License
107
108AGPL-3.0-or-later. Documentation is CC BY-SA 4.0. See [LICENSE](LICENSE) for details.