tranquil.farm
Our Personal Data Server from scratch!
tranquil.farm
oauth
atproto
pds
rust
postgresql
objectstorage
fun
lewis.moe
1# Tranquil PDS
2
3A Personal Data Server for the AT Protocol.
4
5Bluesky runs on a federated protocol called AT Protocol. Your account lives on a PDS, a server that stores your posts, profile, follows, and cryptographic keys. Bluesky hosts one for you at bsky.social, but you can run your own. Self-hosting means you control your data; you're not dependent on any company's servers, and your account + data is actually yours.
6
7This particular PDS thrives under harsh conditions. It is a dandelion growing through the cracks in the sidewalk concrete.
8
9It has full compatibility with Bluesky's reference PDS.
10
11## What's different about Tranquil PDS
12
13It is a superset of the reference PDS, including: passkeys and 2FA (WebAuthn/FIDO2, TOTP, backup codes, trusted devices), SSO login and signup, did:web support (PDS-hosted subdomains or bring-your-own), multi-channel communication (email, discord, telegram, signal) for verification and alerts, granular OAuth scopes with a consent UI showing human-readable descriptions, app passwords with granular permissions (read-only, post-only, or custom scopes), account delegation (letting others manage an account with configurable permission levels), and a built-in web UI for account management, repo browsing, and admin.
14
15The PDS itself is a single binary with no nodeJS runtime. However, at time of writing, Tranquil requires postgres running separately. Blobs are stored on the local filesystem by default (S3 optional). Valkey is also optional (as an alternative to the built-in cache).
16
17## Quick Start
18
19```bash
20cp example.toml config.toml
21podman compose up db -d
22just run
23```
24
25## Configuration
26
27See `example.toml` for all configuration options.
28
29> [!NOTE]
30> 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.
31
32## Development
33
34Run `just` to see available commands.
35
36```bash
37just test
38just lint
39```
40
41## Production Deployment
42
43### Quick Deploy (Docker/Podman Compose)
44
45Edit `config.toml` with your values. Generate secrets with `openssl rand -base64 48`.
46
47```bash
48cp example.toml config.toml
49podman-compose -f docker-compose.prod.yaml up -d
50```
51
52### Installation Guides
53
54- [Debian](docs/install-debian.md)
55- [Containers](docs/install-containers.md)
56- [Kubernetes](docs/install-kubernetes.md)
57
58## Maintainers to ping
59
60- [@lewis.moe](https://bsky.app/profile/did:plc:3fwecdnvtcscjnrx2p4n7alz)
61- [@nel.pet](https://bsky.app/profile/did:plc:h5wsnqetncv6lu2weom35lg2)
62
63## Thanks
64
65This project is very grateful to [@nonbinary.computer](https://bsky.app/profile/did:plc:yfvwmnlztr4dwkb7hwz55r2g), [@juli.ee](https://bsky.app/profile/did:plc:7vimlesenouvuaqvle42yhvo), [@mary.my.id](https://bsky.app/profile/did:plc:ia76kvnndjutgedggx2ibrem), and [@baileytownsend.dev](https://bsky.app/profile/did:plc:rnpkyqnmsw4ipey6eotbdnnf) for their help and their code to lean on.
66
67## License
68
69AGPL-3.0-or-later. Documentation is CC BY-SA 4.0. See [LICENSE](LICENSE) for details.
70